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.  If
  29 the state is maintained as global data, it makes using both of those devices
  30 impossible.
  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
  47         priv = malloc(sizeof(*priv));
  48         if (priv == NULL)
  49                 return 1;
  50
  51         dev = malloc(sizeof(*dev));
  52         if (dev == NULL) {
  53                 free(priv);
  54                 return 1;
  55         }
  56
  57         /* setup whatever private state you need */
  58
  59         memset(dev, 0, sizeof(*dev));
  60         sprintf(dev->name, "APE");
  61
  62         /* if your device has dedicated hardware storage for the
  63          * MAC, read it and initialize dev->enetaddr with it
  64          */
  65         ape_mac_read(dev->enetaddr);
  66
  67         dev->iobase = iobase;
  68         dev->priv = priv;
  69         dev->init = ape_init;
  70         dev->halt = ape_halt;
  71         dev->send = ape_send;
  72         dev->recv = ape_recv;
  73
  74         eth_register(dev);
  75
  76 #ifdef CONFIG_CMD_MII)
  77         miiphy_register(dev->name, ape_mii_read, ape_mii_write);
  78 #endif
  79
  80         return 0;
  81 }
  82
  83 The exact arguments needed to initialize your device are up to you.  If you
  84 need to pass more/less arguments, that's fine.  You should also add the
  85 prototype for your new register function to include/netdev.h.  You might notice
  86 that many drivers seem to use xxx_initialize() rather than xxx_register().
  87 This is the old naming convention and should be avoided as it causes confusion
  88 with the driver-specific init function.
  89
  90 Other than locating the MAC address in dedicated hardware storage, you should
  91 not touch the hardware in anyway.  That step is handled in the driver-specific
  92 init function.  Remember that we are only registering the device here, we are
  93 not checking its state or doing random probing.
  94
  95  -----------
  96   Callbacks
  97  -----------
  98
  99 Now that we've registered with the ethernet layer, we can start getting some
 100 real work done.  You will need four functions:
 101         int ape_init(struct eth_device *dev, bd_t *bis);
 102         int ape_send(struct eth_device *dev, volatile void *packet, int length);
 103         int ape_recv(struct eth_device *dev);
 104         int ape_halt(struct eth_device *dev);
 105
 106 The init function checks the hardware (probing/identifying) and gets it ready
 107 for send/recv operations.  You often do things here such as resetting the MAC
 108 and/or PHY, and waiting for the link to autonegotiate.  You should also take
 109 the opportunity to program the device's MAC address with the dev->enetaddr
 110 member.  This allows the rest of U-Boot to dynamically change the MAC address
 111 and have the new settings be respected.
 112
 113 The send function does what you think -- transmit the specified packet whose
 114 size is specified by length (in bytes).  You should not return until the
 115 transmission is complete, and you should leave the state such that the send
 116 function can be called multiple times in a row.
 117
 118 The recv function should process packets as long as the hardware has them
 119 readily available before returning.  i.e. you should drain the hardware fifo.
 120 The common code sets up packet buffers for you already (NetRxPackets), so there
 121 is no need to allocate your own.  For each packet you receive, you should call
 122 the NetReceive() function on it with the packet length.  So the pseudo code
 123 here would look something like:
 124 int ape_recv(struct eth_device *dev)
 125 {
 126         int length, i = 0;
 127         ...
 128         while (packets_are_available()) {
 129                 ...
 130                 length = ape_get_packet(&NetRxPackets[i]);
 131                 ...
 132                 NetReceive(&NetRxPackets[i], length);
 133                 ...
 134                 if (++i >= PKTBUFSRX)
 135                         i = 0;
 136                 ...
 137         }
 138         ...
 139         return 0;
 140 }
 141
 142 The halt function should turn off / disable the hardware and place it back in
 143 its reset state.
 144
 145 So the call graph at this stage would look something like:
 146 some net operation (ping / tftp / whatever...)
 147         eth_init()
 148                 dev->init()
 149         eth_send()
 150                 dev->send()
 151         eth_rx()
 152                 dev->recv()
 153         eth_halt()
 154                 dev->halt()
 155
 156 -----------------------------
 157  CONFIG_MII / CONFIG_CMD_MII
 158 -----------------------------
 159
 160 If your device supports banging arbitrary values on the MII bus (pretty much
 161 every device does), you should add support for the mii command.  Doing so is
 162 fairly trivial and makes debugging mii issues a lot easier at runtime.
 163
 164 After you have called eth_register() in your driver's register function, add
 165 a call to miiphy_register() like so:
 166 #if defined(CONFIG_MII) || defined(CONFIG_CMD_MII)
 167         miiphy_register(dev->name, mii_read, mii_write);
 168 #endif
 169
 170 And then define the mii_read and mii_write functions if you haven't already.
 171 Their syntax is straightforward:
 172         int mii_read(char *devname, uchar addr, uchar reg, ushort *val);
 173         int mii_write(char *devname, uchar addr, uchar reg, ushort val);
 174
 175 The read function should read the register 'reg' from the phy at address 'addr'
 176 and store the result in the pointer 'val'.  The implementation for the write
 177 function should logically follow.