dm: eth: Add basic driver model support to Ethernet stack

[karo-tx-uboot.git] / doc / README.drivers.eth

diff --git a/doc/README.drivers.eth b/doc/README.drivers.eth
index d0c3571165bcbc63fd54721345066542a35e25e9..8b4d3521c1b7805833dce5adb2b1bd2425b1ff5c 100644 (file)
--- a/doc/README.drivers.eth
+++ b/doc/README.drivers.eth
@@ -1,3 +1,9 @@
+!!! 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
 -----------------------
@@ -43,15 +49,16 @@ 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 1;
+               return -ENOMEM;
 
        dev = malloc(sizeof(*dev));
        if (dev == NULL) {
                free(priv);
-               return 1;
+               return -ENOMEM;
        }
 
        /* setup whatever private state you need */
@@ -59,7 +66,8 @@ int ape_register(bd_t *bis, int iobase)
        memset(dev, 0, sizeof(*dev));
        sprintf(dev->name, "APE");
 
-       /* if your device has dedicated hardware storage for the
+       /*
+        * if your device has dedicated hardware storage for the
         * MAC, read it and initialize dev->enetaddr with it
         */
        ape_mac_read(dev->enetaddr);
@@ -70,11 +78,21 @@ 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);
 
-#ifdef CONFIG_CMD_MII)
-       miiphy_register(dev->name, ape_mii_read, ape_mii_write);
+#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;
@@ -102,11 +120,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
@@ -150,6 +169,9 @@ 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()
@@ -161,25 +183,33 @@ some net operation (ping / tftp / whatever...)
        eth_halt()
                dev->halt()
 
------------------------------
- CONFIG_MII / CONFIG_CMD_MII
------------------------------
+--------------------------------
+ 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 miiphy_register() like so:
-#if defined(CONFIG_MII) || defined(CONFIG_CMD_MII)
-       miiphy_register(dev->name, mii_read, mii_write);
-#endif
+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(char *devname, uchar addr, uchar reg, ushort *val);
-       int mii_write(char *devname, uchar addr, uchar reg, ushort val);
+       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 store the result in the pointer 'val'.  The implementation for the write
-function should logically follow.
+and return the result to its caller.  The implementation for the write function
+should logically follow.