Merge branch 'master' of https://gitlab.denx.de/u-boot/custodians/u-boot-net

4 files changed, 322 insertions, 250 deletions

diff --git a/doc/README.drivers.eth b/doc/README.drivers.eth
deleted file mode 100644
index 1a9a23b51b..0000000000
--- a/doc/README.drivers.eth
+++ /dev/null
@@ -1,215 +0,0 @@
-!!! WARNING !!!
-
-This guide describes to the old way of doing things. No new Ethernet drivers
-should be implemented this way. All new drivers should be written against the
-U-Boot core driver model. See doc/driver-model/README.txt
-
------------------------
- Ethernet Driver Guide
------------------------
-
-The networking stack in Das U-Boot is designed for multiple network devices
-to be easily added and controlled at runtime.  This guide is meant for people
-who wish to review the net driver stack with an eye towards implementing your
-own ethernet device driver.  Here we will describe a new pseudo 'APE' driver.
-
-------------------
- Driver Functions
-------------------
-
-All functions you will be implementing in this document have the return value
-meaning of 0 for success and non-zero for failure.
-
- ----------
-  Register
- ----------
-
-When U-Boot initializes, it will call the common function eth_initialize().
-This will in turn call the board-specific board_eth_init() (or if that fails,
-the cpu-specific cpu_eth_init()).  These board-specific functions can do random
-system handling, but ultimately they will call the driver-specific register
-function which in turn takes care of initializing that particular instance.
-
-Keep in mind that you should code the driver to avoid storing state in global
-data as someone might want to hook up two of the same devices to one board.
-Any such information that is specific to an interface should be stored in a
-private, driver-defined data structure and pointed to by eth->priv (see below).
-
-So the call graph at this stage would look something like:
-board_init()
-	eth_initialize()
-		board_eth_init() / cpu_eth_init()
-			driver_register()
-				initialize eth_device
-				eth_register()
-
-At this point in time, the only thing you need to worry about is the driver's
-register function.  The pseudo code would look something like:
-int ape_register(bd_t *bis, int iobase)
-{
-	struct ape_priv *priv;
-	struct eth_device *dev;
-	struct mii_dev *bus;
-
-	priv = malloc(sizeof(*priv));
-	if (priv == NULL)
-		return -ENOMEM;
-
-	dev = malloc(sizeof(*dev));
-	if (dev == NULL) {
-		free(priv);
-		return -ENOMEM;
-	}
-
-	/* setup whatever private state you need */
-
-	memset(dev, 0, sizeof(*dev));
-	sprintf(dev->name, "APE");
-
-	/*
-	 * if your device has dedicated hardware storage for the
-	 * MAC, read it and initialize dev->enetaddr with it
-	 */
-	ape_mac_read(dev->enetaddr);
-
-	dev->iobase = iobase;
-	dev->priv = priv;
-	dev->init = ape_init;
-	dev->halt = ape_halt;
-	dev->send = ape_send;
-	dev->recv = ape_recv;
-	dev->write_hwaddr = ape_write_hwaddr;
-
-	eth_register(dev);
-
-#ifdef CONFIG_PHYLIB
-	bus = mdio_alloc();
-	if (!bus) {
-		free(priv);
-		free(dev);
-		return -ENOMEM;
-	}
-
-	bus->read = ape_mii_read;
-	bus->write = ape_mii_write;
-	mdio_register(bus);
-#endif
-
-	return 1;
-}
-
-The exact arguments needed to initialize your device are up to you.  If you
-need to pass more/less arguments, that's fine.  You should also add the
-prototype for your new register function to include/netdev.h.
-
-The return value for this function should be as follows:
-< 0 - failure (hardware failure, not probe failure)
->=0 - number of interfaces detected
-
-You might notice that many drivers seem to use xxx_initialize() rather than
-xxx_register().  This is the old naming convention and should be avoided as it
-causes confusion with the driver-specific init function.
-
-Other than locating the MAC address in dedicated hardware storage, you should
-not touch the hardware in anyway.  That step is handled in the driver-specific
-init function.  Remember that we are only registering the device here, we are
-not checking its state or doing random probing.
-
- -----------
-  Callbacks
- -----------
-
-Now that we've registered with the ethernet layer, we can start getting some
-real work done.  You will need five functions:
-	int ape_init(struct eth_device *dev, bd_t *bis);
-	int ape_send(struct eth_device *dev, volatile void *packet, int length);
-	int ape_recv(struct eth_device *dev);
-	int ape_halt(struct eth_device *dev);
-	int ape_write_hwaddr(struct eth_device *dev);
-
-The init function checks the hardware (probing/identifying) and gets it ready
-for send/recv operations.  You often do things here such as resetting the MAC
-and/or PHY, and waiting for the link to autonegotiate.  You should also take
-the opportunity to program the device's MAC address with the dev->enetaddr
-member.  This allows the rest of U-Boot to dynamically change the MAC address
-and have the new settings be respected.
-
-The send function does what you think -- transmit the specified packet whose
-size is specified by length (in bytes).  You should not return until the
-transmission is complete, and you should leave the state such that the send
-function can be called multiple times in a row.
-
-The recv function should process packets as long as the hardware has them
-readily available before returning.  i.e. you should drain the hardware fifo.
-For each packet you receive, you should call the net_process_received_packet() function on it
-along with the packet length.  The common code sets up packet buffers for you
-already in the .bss (net_rx_packets), so there should be no need to allocate your
-own.  This doesn't mean you must use the net_rx_packets array however; you're
-free to call the net_process_received_packet() function with any buffer you wish.  So the pseudo
-code here would look something like:
-int ape_recv(struct eth_device *dev)
-{
-	int length, i = 0;
-	...
-	while (packets_are_available()) {
-		...
-		length = ape_get_packet(&net_rx_packets[i]);
-		...
-		net_process_received_packet(&net_rx_packets[i], length);
-		...
-		if (++i >= PKTBUFSRX)
-			i = 0;
-		...
-	}
-	...
-	return 0;
-}
-
-The halt function should turn off / disable the hardware and place it back in
-its reset state.  It can be called at any time (before any call to the related
-init function), so make sure it can handle this sort of thing.
-
-The write_hwaddr function should program the MAC address stored in dev->enetaddr
-into the Ethernet controller.
-
-So the call graph at this stage would look something like:
-some net operation (ping / tftp / whatever...)
-	eth_init()
-		dev->init()
-	eth_send()
-		dev->send()
-	eth_rx()
-		dev->recv()
-	eth_halt()
-		dev->halt()
-
---------------------------------
- CONFIG_PHYLIB / CONFIG_CMD_MII
---------------------------------
-
-If your device supports banging arbitrary values on the MII bus (pretty much
-every device does), you should add support for the mii command.  Doing so is
-fairly trivial and makes debugging mii issues a lot easier at runtime.
-
-After you have called eth_register() in your driver's register function, add
-a call to mdio_alloc() and mdio_register() like so:
-	bus = mdio_alloc();
-	if (!bus) {
-		free(priv);
-		free(dev);
-		return -ENOMEM;
-	}
-
-	bus->read = ape_mii_read;
-	bus->write = ape_mii_write;
-	mdio_register(bus);
-
-And then define the mii_read and mii_write functions if you haven't already.
-Their syntax is straightforward:
-	int mii_read(struct mii_dev *bus, int addr, int devad, int reg);
-	int mii_write(struct mii_dev *bus, int addr, int devad, int reg,
-		      u16 val);
-
-The read function should read the register 'reg' from the phy at address 'addr'
-and return the result to its caller.  The implementation for the write function
-should logically follow.
diff --git a/doc/device-tree-bindings/net/ti,dp83867.txt b/doc/device-tree-bindings/net/ti,dp83867.txt
deleted file mode 100644
index 268220964a..0000000000
--- a/doc/device-tree-bindings/net/ti,dp83867.txt
+++ /dev/null
@@ -1,35 +0,0 @@
-* Texas Instruments - dp83867 Giga bit ethernet phy
-
-Required properties:
-	- reg - The ID number for the phy, usually a small integer
-	- ti,rx-internal-delay - RGMII Recieve Clock Delay - see dt-bindings/net/ti-dp83867.h
-		for applicable values
-	- ti,tx-internal-delay - RGMII Transmit Clock Delay - see dt-bindings/net/ti-dp83867.h
-		for applicable values
-	- ti,fifo-depth - Transmitt FIFO depth- see dt-bindings/net/ti-dp83867.h
-		for applicable values
-	- enet-phy-lane-swap - Indicates that PHY will swap the TX/RX lanes to
-		compensate for the board being designed with the lanes swapped.
-	- enet-phy-no-lane-swap - Indicates that PHY will disable swap of the
-		TX/RX lanes.
-	- ti,clk-output-sel - Muxing option for CLK_OUT pin.  See dt-bindings/net/ti-dp83867.h
-			      for applicable values.  The CLK_OUT pin can also
-			      be disabled by this property.  When omitted, the
-			      PHY's default will be left as is.
-
-Default child nodes are standard Ethernet PHY device
-nodes as described in doc/devicetree/bindings/net/ethernet.txt
-
-Example:
-
-	ethernet-phy@0 {
-		reg = <0>;
-		ti,rx-internal-delay = <DP83867_RGMIIDCTL_2_25_NS>;
-		ti,tx-internal-delay = <DP83867_RGMIIDCTL_2_75_NS>;
-		ti,fifo-depth = <DP83867_PHYCR_FIFO_DEPTH_4_B_NIB>;
-		enet-phy-lane-no-swap;
-		ti,clk-output-sel = <DP83867_CLK_O_SEL_CHN_A_TCLK>;
-	};
-
-Datasheet can be found:
-http://www.ti.com/product/DP83867IR/datasheet
diff --git a/doc/driver-model/ethernet.rst b/doc/driver-model/ethernet.rst
new file mode 100644
index 0000000000..359a0523cf
--- /dev/null
+++ b/doc/driver-model/ethernet.rst
@@ -0,0 +1,321 @@
+Ethernet Driver Guide
+=======================
+
+The networking stack in Das U-Boot is designed for multiple network devices
+to be easily added and controlled at runtime.  This guide is meant for people
+who wish to review the net driver stack with an eye towards implementing your
+own ethernet device driver.  Here we will describe a new pseudo 'APE' driver.
+
+Most existing drivers do already - and new network driver MUST - use the
+U-Boot core driver model. Generic information about this can be found in
+doc/driver-model/design.rst, this document will thus focus on the network
+specific code parts.
+Some drivers are still using the old Ethernet interface, differences between
+the two and hints about porting will be handled at the end.
+
+Driver framework
+------------------
+
+A network driver following the driver model must declare itself using
+the UCLASS_ETH .id field in the U-Boot driver struct:
+
+.. code-block:: c
+
+	U_BOOT_DRIVER(eth_ape) = {
+		.name			= "eth_ape",
+		.id			= UCLASS_ETH,
+		.of_match		= eth_ape_ids,
+		.ofdata_to_platdata	= eth_ape_ofdata_to_platdata,
+		.probe			= eth_ape_probe,
+		.ops			= &eth_ape_ops,
+		.priv_auto_alloc_size	= sizeof(struct eth_ape_priv),
+		.platdata_auto_alloc_size = sizeof(struct eth_ape_pdata),
+		.flags			= DM_FLAG_ALLOC_PRIV_DMA,
+	};
+
+struct eth_ape_priv contains runtime per-instance data, like buffers, pointers
+to current descriptors, current speed settings, pointers to PHY related data
+(like struct mii_dev) and so on. Declaring its size in .priv_auto_alloc_size
+will let the driver framework allocate it at the right time.
+It can be retrieved using a dev_get_priv(dev) call.
+
+struct eth_ape_pdata contains static platform data, like the MMIO base address,
+a hardware variant, the MAC address. ``struct eth_pdata eth_pdata``
+as the first member of this struct helps to avoid duplicated code.
+If you don't need any more platform data beside the standard member,
+just use sizeof(struct eth_pdata) for the platdata_auto_alloc_size.
+
+PCI devices add a line pointing to supported vendor/device ID pairs:
+
+.. code-block:: c
+
+	static struct pci_device_id supported[] = {
+		{ PCI_DEVICE(PCI_VENDOR_ID_APE, 0x4223) },
+		{}
+	};
+
+	U_BOOT_PCI_DEVICE(eth_ape, supported);
+
+It is also possible to declare support for a whole class of PCI devices::
+
+	{ PCI_DEVICE_CLASS(PCI_CLASS_SYSTEM_SDHCI << 8, 0xffff00) },
+
+Device probing and instantiation will be handled by the driver model framework,
+so follow the guidelines there. The probe() function would initialise the
+platform specific parts of the hardware, like clocks, resets, GPIOs, the MDIO
+bus. Also it would take care of any special PHY setup (power rails, enable
+bits for internal PHYs, etc.).
+
+Driver methods
+----------------
+
+The real work will be done in the driver method functions the driver provides
+by defining the members of struct eth_ops:
+
+.. code-block:: c
+
+	struct eth_ops {
+		int (*start)(struct udevice *dev);
+		int (*send)(struct udevice *dev, void *packet, int length);
+		int (*recv)(struct udevice *dev, int flags, uchar **packetp);
+		int (*free_pkt)(struct udevice *dev, uchar *packet, int length);
+		void (*stop)(struct udevice *dev);
+		int (*mcast)(struct udevice *dev, const u8 *enetaddr, int join);
+		int (*write_hwaddr)(struct udevice *dev);
+		int (*read_rom_hwaddr)(struct udevice *dev);
+	};
+
+An up-to-date version of this struct together with more information can be
+found in include/net.h.
+
+Only start, stop, send and recv are required, the rest are optional and are
+handled by generic code or ignored if not provided.
+
+The **start** function initialises the hardware and gets it ready for send/recv
+operations.  You often do things here such as resetting the MAC
+and/or PHY, and waiting for the link to autonegotiate.  You should also take
+the opportunity to program the device's MAC address with the enetaddr member
+of the generic struct eth_pdata (which would be the first member of your
+own platdata struct). This allows the rest of U-Boot to dynamically change
+the MAC address and have the new settings be respected.
+
+The **send** function does what you think -- transmit the specified packet
+whose size is specified by length (in bytes). The packet buffer can (and
+will!) be reused for subsequent calls to send(), so it must be no longer
+used when the send() function returns. The easiest way to achieve this is
+to wait until the transmission is complete. Alternatively, if supported by
+the hardware, just waiting for the buffer to be consumed (by some DMA engine)
+might be an option as well.
+Another way of consuming the buffer could be to copy the data to be send,
+then just queue the copied packet (for instance handing it over to a DMA
+engine), and return immediately afterwards.
+In any case you should leave the state such that the send function can be
+called multiple times in a row.
+
+The **recv** function polls for availability of a new packet. If none is
+available, it must return with -EAGAIN.
+If a packet has been received, make sure it is accessible to the CPU
+(invalidate caches if needed), then write its address to the packetp pointer,
+and return the length. If there is an error (receive error, too short or too
+long packet), return 0 if you require the packet to be cleaned up normally,
+or a negative error code otherwise (cleanup not necessary or already done).
+The U-Boot network stack will then process the packet.
+
+If **free_pkt** is defined, U-Boot will call it after a received packet has
+been processed, so the packet buffer can be freed or recycled. Typically you
+would hand it back to the hardware to acquire another packet. free_pkt() will
+be called after recv(), for the same packet, so you don't necessarily need
+to infer the buffer to free from the ``packet`` pointer, but can rely on that
+being the last packet that recv() handled.
+The common code sets up packet buffers for you already in the .bss
+(net_rx_packets), so there should be no need to allocate your own. This doesn't
+mean you must use the net_rx_packets array however; you're free to use any
+buffer you wish.
+
+The **stop** function should turn off / disable the hardware and place it back
+in its reset state.  It can be called at any time (before any call to the
+related start() function), so make sure it can handle this sort of thing.
+
+The (optional) **write_hwaddr** function should program the MAC address stored
+in pdata->enetaddr into the Ethernet controller.
+
+So the call graph at this stage would look something like:
+
+.. code-block:: c
+
+	(some net operation (ping / tftp / whatever...))
+	eth_init()
+		ops->start()
+	eth_send()
+		ops->send()
+	eth_rx()
+		ops->recv()
+		(process packet)
+		if (ops->free_pkt)
+			ops->free_pkt()
+	eth_halt()
+		ops->stop()
+
+
+CONFIG_PHYLIB / CONFIG_CMD_MII
+--------------------------------
+
+If your device supports banging arbitrary values on the MII bus (pretty much
+every device does), you should add support for the mii command.  Doing so is
+fairly trivial and makes debugging mii issues a lot easier at runtime.
+
+In your driver's ``probe()`` function, add a call to mdio_alloc() and
+mdio_register() like so:
+
+.. code-block:: c
+
+	bus = mdio_alloc();
+	if (!bus) {
+		...
+		return -ENOMEM;
+	}
+
+	bus->read = ape_mii_read;
+	bus->write = ape_mii_write;
+	mdio_register(bus);
+
+And then define the mii_read and mii_write functions if you haven't already.
+Their syntax is straightforward::
+
+	int mii_read(struct mii_dev *bus, int addr, int devad, int reg);
+	int mii_write(struct mii_dev *bus, int addr, int devad, int reg,
+		      u16 val);
+
+The read function should read the register 'reg' from the phy at address 'addr'
+and return the result to its caller.  The implementation for the write function
+should logically follow.
+
+................................................................
+
+Legacy network drivers
+------------------------
+
+!!! WARNING !!!
+
+This section below describes the old way of doing things. No new Ethernet
+drivers should be implemented this way. All new drivers should be written
+against the U-Boot core driver model, as described above.
+
+The actual callback functions are fairly similar, the differences are:
+
+- ``start()`` is called ``init()``
+- ``stop()`` is called ``halt()``
+- The ``recv()`` function must loop until all packets have been received, for
+  each packet it must call the net_process_received_packet() function,
+  handing it over the pointer and the length. Afterwards it should free
+  the packet, before checking for new data.
+
+For porting an old driver to the new driver model, split the existing recv()
+function into the actual new recv() function, just fetching **one** packet,
+remove the call to net_process_received_packet(), then move the packet
+cleanup into the ``free_pkt()`` function.
+
+Registering the driver and probing a device is handled very differently,
+follow the recommendations in the driver model design documentation for
+instructions on how to port this over. For the records, the old way of
+initialising a network driver is as follows:
+
+Old network driver registration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When U-Boot initializes, it will call the common function eth_initialize().
+This will in turn call the board-specific board_eth_init() (or if that fails,
+the cpu-specific cpu_eth_init()).  These board-specific functions can do random
+system handling, but ultimately they will call the driver-specific register
+function which in turn takes care of initializing that particular instance.
+
+Keep in mind that you should code the driver to avoid storing state in global
+data as someone might want to hook up two of the same devices to one board.
+Any such information that is specific to an interface should be stored in a
+private, driver-defined data structure and pointed to by eth->priv (see below).
+
+So the call graph at this stage would look something like:
+
+.. code-block:: c
+
+	board_init()
+		eth_initialize()
+			board_eth_init() / cpu_eth_init()
+				driver_register()
+					initialize eth_device
+					eth_register()
+
+At this point in time, the only thing you need to worry about is the driver's
+register function.  The pseudo code would look something like:
+
+.. code-block:: c
+
+	int ape_register(bd_t *bis, int iobase)
+	{
+		struct ape_priv *priv;
+		struct eth_device *dev;
+		struct mii_dev *bus;
+
+		priv = malloc(sizeof(*priv));
+		if (priv == NULL)
+			return -ENOMEM;
+
+		dev = malloc(sizeof(*dev));
+		if (dev == NULL) {
+			free(priv);
+			return -ENOMEM;
+		}
+
+		/* setup whatever private state you need */
+
+		memset(dev, 0, sizeof(*dev));
+		sprintf(dev->name, "APE");
+
+		/*
+		 * if your device has dedicated hardware storage for the
+		 * MAC, read it and initialize dev->enetaddr with it
+		 */
+		ape_mac_read(dev->enetaddr);
+
+		dev->iobase = iobase;
+		dev->priv = priv;
+		dev->init = ape_init;
+		dev->halt = ape_halt;
+		dev->send = ape_send;
+		dev->recv = ape_recv;
+		dev->write_hwaddr = ape_write_hwaddr;
+
+		eth_register(dev);
+
+	#ifdef CONFIG_PHYLIB
+		bus = mdio_alloc();
+		if (!bus) {
+			free(priv);
+			free(dev);
+			return -ENOMEM;
+		}
+
+		bus->read = ape_mii_read;
+		bus->write = ape_mii_write;
+		mdio_register(bus);
+	#endif
+
+		return 1;
+	}
+
+The exact arguments needed to initialize your device are up to you.  If you
+need to pass more/less arguments, that's fine.  You should also add the
+prototype for your new register function to include/netdev.h.
+
+The return value for this function should be as follows:
+< 0 - failure (hardware failure, not probe failure)
+>=0 - number of interfaces detected
+
+You might notice that many drivers seem to use xxx_initialize() rather than
+xxx_register().  This is the old naming convention and should be avoided as it
+causes confusion with the driver-specific init function.
+
+Other than locating the MAC address in dedicated hardware storage, you should
+not touch the hardware in anyway.  That step is handled in the driver-specific
+init function.  Remember that we are only registering the device here, we are
+not checking its state or doing random probing.
diff --git a/doc/driver-model/index.rst b/doc/driver-model/index.rst
index 6d55774b4c..b9df221627 100644
--- a/doc/driver-model/index.rst
+++ b/doc/driver-model/index.rst
@@ -8,6 +8,7 @@ Driver Model
 
    debugging
    design
+   ethernet
    fdt-fixup
    fs_firmware_loader
    i2c-howto