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