X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2FREADME.drivers.eth;h=eb83038b5dbd1880edc1e9f0cfa34f3ed6eb6a24;hb=bf36c5d521c17460553e39d82232a51273b83aed;hp=7f2190998a629b23cfd075221a4aae6626e9042a;hpb=1f1e774ec6242d4ea34e5cff57232deb5bb587e0;p=u-boot

diff --git a/doc/README.drivers.eth b/doc/README.drivers.eth
index 7f2190998a..eb83038b5d 100644
--- a/doc/README.drivers.eth
+++ b/doc/README.drivers.eth
@@ -25,9 +25,9 @@ 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.  If
-the state is maintained as global data, it makes using both of those devices
-impossible.
+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()
@@ -70,6 +70,7 @@ int ape_register(bd_t *bis, int iobase)
 	dev->halt = ape_halt;
 	dev->send = ape_send;
 	dev->recv = ape_recv;
+	dev->write_hwaddr = ape_write_hwaddr;
 
 	eth_register(dev);
 
@@ -77,15 +78,20 @@ int ape_register(bd_t *bis, int iobase)
 	miiphy_register(dev->name, ape_mii_read, ape_mii_write);
 #endif
 
-	return 0;
+	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.  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.
+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
@@ -97,11 +103,12 @@ not checking its state or doing random probing.
  -----------
 
 Now that we've registered with the ethernet layer, we can start getting some
-real work done.  You will need four functions:
+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
@@ -117,10 +124,12 @@ 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.
-The common code sets up packet buffers for you already (NetRxPackets), so there
-is no need to allocate your own.  For each packet you receive, you should call
-the NetReceive() function on it with the packet length.  So the pseudo code
-here would look something like:
+For each packet you receive, you should call the NetReceive() function on it
+along with the packet length.  The common code sets up packet buffers for you
+already in the .bss (NetRxPackets), so there should be no need to allocate your
+own.  This doesn't mean you must use the NetRxPackets array however; you're
+free to call the NetReceive() 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;
@@ -140,7 +149,11 @@ int ape_recv(struct eth_device *dev)
 }
 
 The halt function should turn off / disable the hardware and place it back in
-its reset state.
+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...)