doc/README.drivers.eth

   1 -----------------------
   2  Ethernet Driver Guide
   3 -----------------------
   4
   5 The networking stack in Das U-Boot is designed for multiple network devices
   6 to be easily added and controlled at runtime.  This guide is meant for people
   7 who wish to review the net driver stack with an eye towards implementing your
   8 own ethernet device driver.  Here we will describe a new pseudo 'APE' driver.
   9
  10 ------------------
  11  Driver Functions
  12 ------------------
  13
  14 All functions you will be implementing in this document have the return value
  15 meaning of 0 for success and non-zero for failure.
  16
  17  ----------
  18   Register
  19  ----------
  20
  21 When U-Boot initializes, it will call the common function eth_initialize().
  22 This will in turn call the board-specific board_eth_init() (or if that fails,
  23 the cpu-specific cpu_eth_init()).  These board-specific functions can do random
  24 system handling, but ultimately they will call the driver-specific register
  25 function which in turn takes care of initializing that particular instance.
  26
  27 Keep in mind that you should code the driver to avoid storing state in global
  28 data as someone might want to hook up two of the same devices to one board.
  29 Any such information that is specific to an interface should be stored in a
  30 private, driver-defined data structure and pointed to by eth->priv (see below).
  31
  32 So the call graph at this stage would look something like:
  33 board_init()
  34         eth_initialize()
  35                 board_eth_init() / cpu_eth_init()
  36                         driver_register()
  37                                 initialize eth_device
  38                                 eth_register()
  39
  40 At this point in time, the only thing you need to worry about is the driver's
  41 register function.  The pseudo code would look something like:
  42 int ape_register(bd_t *bis, int iobase)
  43 {
  44         struct ape_priv *priv;
  45         struct eth_device *dev;
  46         struct mii_dev *bus;
  47
  48         priv = malloc(sizeof(*priv));
  49         if (priv == NULL)
  50                 return -ENOMEM;
  51
  52         dev = malloc(sizeof(*dev));
  53         if (dev == NULL) {
  54                 free(priv);
  55                 return -ENOMEM;
  56         }
  57
  58         /* setup whatever private state you need */
  59
  60         memset(dev, 0, sizeof(*dev));
  61         sprintf(dev->name, "APE");
  62
  63         /*
  64          * if your device has dedicated hardware storage for the
  65          * MAC, read it and initialize dev->enetaddr with it
  66          */
  67         ape_mac_read(dev->enetaddr);
  68
  69         dev->iobase = iobase;
  70         dev->priv = priv;
  71         dev->init = ape_init;
  72         dev->halt = ape_halt;
  73         dev->send = ape_send;
  74         dev->recv = ape_recv;
  75         dev->write_hwaddr = ape_write_hwaddr;
  76
  77         eth_register(dev);
  78
  79 #ifdef CONFIG_PHYLIB
  80         bus = mdio_alloc();
  81         if (!bus) {
  82                 free(priv);
  83                 free(dev);
  84                 return -ENOMEM;
  85         }
  86
  87         bus->read = ape_mii_read;
  88         bus->write = ape_mii_write;
  89         mdio_register(bus);
  90 #endif
  91
  92         return 1;
  93 }
  94
  95 The exact arguments needed to initialize your device are up to you.  If you
  96 need to pass more/less arguments, that's fine.  You should also add the
  97 prototype for your new register function to include/netdev.h.
  98
  99 The return value for this function should be as follows:
 100 < 0 - failure (hardware failure, not probe failure)
 101 >=0 - number of interfaces detected
 102
 103 You might notice that many drivers seem to use xxx_initialize() rather than
 104 xxx_register().  This is the old naming convention and should be avoided as it
 105 causes confusion with the driver-specific init function.
 106
 107 Other than locating the MAC address in dedicated hardware storage, you should
 108 not touch the hardware in anyway.  That step is handled in the driver-specific
 109 init function.  Remember that we are only registering the device here, we are
 110 not checking its state or doing random probing.
 111
 112  -----------
 113   Callbacks
 114  -----------
 115
 116 Now that we've registered with the ethernet layer, we can start getting some
 117 real work done.  You will need five functions:
 118         int ape_init(struct eth_device *dev, bd_t *bis);
 119         int ape_send(struct eth_device *dev, volatile void *packet, int length);
 120         int ape_recv(struct eth_device *dev);
 121         int ape_halt(struct eth_device *dev);
 122         int ape_write_hwaddr(struct eth_device *dev);
 123
 124 The init function checks the hardware (probing/identifying) and gets it ready
 125 for send/recv operations.  You often do things here such as resetting the MAC
 126 and/or PHY, and waiting for the link to autonegotiate.  You should also take
 127 the opportunity to program the device's MAC address with the dev->enetaddr
 128 member.  This allows the rest of U-Boot to dynamically change the MAC address
 129 and have the new settings be respected.
 130
 131 The send function does what you think -- transmit the specified packet whose
 132 size is specified by length (in bytes).  You should not return until the
 133 transmission is complete, and you should leave the state such that the send
 134 function can be called multiple times in a row.
 135
 136 The recv function should process packets as long as the hardware has them
 137 readily available before returning.  i.e. you should drain the hardware fifo.
 138 For each packet you receive, you should call the NetReceive() function on it
 139 along with the packet length.  The common code sets up packet buffers for you
 140 already in the .bss (NetRxPackets), so there should be no need to allocate your
 141 own.  This doesn't mean you must use the NetRxPackets array however; you're
 142 free to call the NetReceive() function with any buffer you wish.  So the pseudo
 143 code here would look something like:
 144 int ape_recv(struct eth_device *dev)
 145 {
 146         int length, i = 0;
 147         ...
 148         while (packets_are_available()) {
 149                 ...
 150                 length = ape_get_packet(&NetRxPackets[i]);
 151                 ...
 152                 NetReceive(&NetRxPackets[i], length);
 153                 ...
 154                 if (++i >= PKTBUFSRX)
 155                         i = 0;
 156                 ...
 157         }
 158         ...
 159         return 0;
 160 }
 161
 162 The halt function should turn off / disable the hardware and place it back in
 163 its reset state.  It can be called at any time (before any call to the related
 164 init function), so make sure it can handle this sort of thing.
 165
 166 The write_hwaddr function should program the MAC address stored in dev->enetaddr
 167 into the Ethernet controller.
 168
 169 So the call graph at this stage would look something like:
 170 some net operation (ping / tftp / whatever...)
 171         eth_init()
 172                 dev->init()
 173         eth_send()
 174                 dev->send()
 175         eth_rx()
 176                 dev->recv()
 177         eth_halt()
 178                 dev->halt()
 179
 180 --------------------------------
 181  CONFIG_PHYLIB / CONFIG_CMD_MII
 182 --------------------------------
 183
 184 If your device supports banging arbitrary values on the MII bus (pretty much
 185 every device does), you should add support for the mii command.  Doing so is
 186 fairly trivial and makes debugging mii issues a lot easier at runtime.
 187
 188 After you have called eth_register() in your driver's register function, add
 189 a call to mdio_alloc() and mdio_register() like so:
 190         bus = mdio_alloc();
 191         if (!bus) {
 192                 free(priv);
 193                 free(dev);
 194                 return -ENOMEM;
 195         }
 196
 197         bus->read = ape_mii_read;
 198         bus->write = ape_mii_write;
 199         mdio_register(bus);
 200
 201 And then define the mii_read and mii_write functions if you haven't already.
 202 Their syntax is straightforward:
 203         int mii_read(struct mii_dev *bus, int addr, int devad, int reg);
 204         int mii_write(struct mii_dev *bus, int addr, int devad, int reg,
 205                       u16 val);
 206
 207 The read function should read the register 'reg' from the phy at address 'addr'
 208 and return the result to its caller.  The implementation for the write function
 209 should logically follow.