1----------------------- 2 Ethernet Driver Guide 3----------------------- 4 5The networking stack in Das U-Boot is designed for multiple network devices 6to be easily added and controlled at runtime. This guide is meant for people 7who wish to review the net driver stack with an eye towards implementing your 8own ethernet device driver. Here we will describe a new pseudo 'APE' driver. 9 10------------------ 11 Driver Functions 12------------------ 13 14All functions you will be implementing in this document have the return value 15meaning of 0 for success and non-zero for failure. 16 17 ---------- 18 Register 19 ---------- 20 21When U-Boot initializes, it will call the common function eth_initialize(). 22This will in turn call the board-specific board_eth_init() (or if that fails, 23the cpu-specific cpu_eth_init()). These board-specific functions can do random 24system handling, but ultimately they will call the driver-specific register 25function which in turn takes care of initializing that particular instance. 26 27Keep in mind that you should code the driver to avoid storing state in global 28data as someone might want to hook up two of the same devices to one board. 29Any such information that is specific to an interface should be stored in a 30private, driver-defined data structure and pointed to by eth->priv (see below). 31 32So the call graph at this stage would look something like: 33board_init() 34 eth_initialize() 35 board_eth_init() / cpu_eth_init() 36 driver_register() 37 initialize eth_device 38 eth_register() 39 40At this point in time, the only thing you need to worry about is the driver's 41register function. The pseudo code would look something like: 42int 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 95The exact arguments needed to initialize your device are up to you. If you 96need to pass more/less arguments, that's fine. You should also add the 97prototype for your new register function to include/netdev.h. 98 99The return value for this function should be as follows: 100< 0 - failure (hardware failure, not probe failure) 101>=0 - number of interfaces detected 102 103You might notice that many drivers seem to use xxx_initialize() rather than 104xxx_register(). This is the old naming convention and should be avoided as it 105causes confusion with the driver-specific init function. 106 107Other than locating the MAC address in dedicated hardware storage, you should 108not touch the hardware in anyway. That step is handled in the driver-specific 109init function. Remember that we are only registering the device here, we are 110not checking its state or doing random probing. 111 112 ----------- 113 Callbacks 114 ----------- 115 116Now that we've registered with the ethernet layer, we can start getting some 117real 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 124The init function checks the hardware (probing/identifying) and gets it ready 125for send/recv operations. You often do things here such as resetting the MAC 126and/or PHY, and waiting for the link to autonegotiate. You should also take 127the opportunity to program the device's MAC address with the dev->enetaddr 128member. This allows the rest of U-Boot to dynamically change the MAC address 129and have the new settings be respected. 130 131The send function does what you think -- transmit the specified packet whose 132size is specified by length (in bytes). You should not return until the 133transmission is complete, and you should leave the state such that the send 134function can be called multiple times in a row. 135 136The recv function should process packets as long as the hardware has them 137readily available before returning. i.e. you should drain the hardware fifo. 138For each packet you receive, you should call the NetReceive() function on it 139along with the packet length. The common code sets up packet buffers for you 140already in the .bss (NetRxPackets), so there should be no need to allocate your 141own. This doesn't mean you must use the NetRxPackets array however; you're 142free to call the NetReceive() function with any buffer you wish. So the pseudo 143code here would look something like: 144int 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 162The halt function should turn off / disable the hardware and place it back in 163its reset state. It can be called at any time (before any call to the related 164init function), so make sure it can handle this sort of thing. 165 166The write_hwaddr function should program the MAC address stored in dev->enetaddr 167into the Ethernet controller. 168 169So the call graph at this stage would look something like: 170some 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 184If your device supports banging arbitrary values on the MII bus (pretty much 185every device does), you should add support for the mii command. Doing so is 186fairly trivial and makes debugging mii issues a lot easier at runtime. 187 188After you have called eth_register() in your driver's register function, add 189a 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 201And then define the mii_read and mii_write functions if you haven't already. 202Their 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 207The read function should read the register 'reg' from the phy at address 'addr' 208and return the result to its caller. The implementation for the write function 209should logically follow. 210