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. If 29the state is maintained as global data, it makes using both of those devices 30impossible. 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 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 83The exact arguments needed to initialize your device are up to you. If you 84need to pass more/less arguments, that's fine. You should also add the 85prototype for your new register function to include/netdev.h. You might notice 86that many drivers seem to use xxx_initialize() rather than xxx_register(). 87This is the old naming convention and should be avoided as it causes confusion 88with the driver-specific init function. 89 90Other than locating the MAC address in dedicated hardware storage, you should 91not touch the hardware in anyway. That step is handled in the driver-specific 92init function. Remember that we are only registering the device here, we are 93not checking its state or doing random probing. 94 95 ----------- 96 Callbacks 97 ----------- 98 99Now that we've registered with the ethernet layer, we can start getting some 100real 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 106The init function checks the hardware (probing/identifying) and gets it ready 107for send/recv operations. You often do things here such as resetting the MAC 108and/or PHY, and waiting for the link to autonegotiate. You should also take 109the opportunity to program the device's MAC address with the dev->enetaddr 110member. This allows the rest of U-Boot to dynamically change the MAC address 111and have the new settings be respected. 112 113The send function does what you think -- transmit the specified packet whose 114size is specified by length (in bytes). You should not return until the 115transmission is complete, and you should leave the state such that the send 116function can be called multiple times in a row. 117 118The recv function should process packets as long as the hardware has them 119readily available before returning. i.e. you should drain the hardware fifo. 120The common code sets up packet buffers for you already (NetRxPackets), so there 121is no need to allocate your own. For each packet you receive, you should call 122the NetReceive() function on it with the packet length. So the pseudo code 123here would look something like: 124int 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 142The halt function should turn off / disable the hardware and place it back in 143its reset state. 144 145So the call graph at this stage would look something like: 146some 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 160If your device supports banging arbitrary values on the MII bus (pretty much 161every device does), you should add support for the mii command. Doing so is 162fairly trivial and makes debugging mii issues a lot easier at runtime. 163 164After you have called eth_register() in your driver's register function, add 165a 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 170And then define the mii_read and mii_write functions if you haven't already. 171Their 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 175The read function should read the register 'reg' from the phy at address 'addr' 176and store the result in the pointer 'val'. The implementation for the write 177function should logically follow. 178