]>
Commit | Line | Data |
---|---|---|
1f1e774e MF |
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 | |
99dbd4ef BW |
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). | |
1f1e774e MF |
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; | |
c58ea6cb | 46 | struct mii_dev *bus; |
1f1e774e MF |
47 | |
48 | priv = malloc(sizeof(*priv)); | |
49 | if (priv == NULL) | |
c58ea6cb | 50 | return -ENOMEM; |
1f1e774e MF |
51 | |
52 | dev = malloc(sizeof(*dev)); | |
53 | if (dev == NULL) { | |
54 | free(priv); | |
c58ea6cb | 55 | return -ENOMEM; |
1f1e774e MF |
56 | } |
57 | ||
58 | /* setup whatever private state you need */ | |
59 | ||
60 | memset(dev, 0, sizeof(*dev)); | |
61 | sprintf(dev->name, "APE"); | |
62 | ||
c58ea6cb BM |
63 | /* |
64 | * if your device has dedicated hardware storage for the | |
1f1e774e MF |
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; | |
ecee9324 | 75 | dev->write_hwaddr = ape_write_hwaddr; |
1f1e774e MF |
76 | |
77 | eth_register(dev); | |
78 | ||
c58ea6cb BM |
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); | |
1f1e774e MF |
90 | #endif |
91 | ||
99dbd4ef | 92 | return 1; |
1f1e774e MF |
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 | |
99dbd4ef BW |
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 | ||
4946775c | 103 | You might notice that many drivers seem to use xxx_initialize() rather than |
99dbd4ef BW |
104 | xxx_register(). This is the old naming convention and should be avoided as it |
105 | causes confusion with the driver-specific init function. | |
1f1e774e MF |
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 | |
ecee9324 | 117 | real work done. You will need five functions: |
1f1e774e MF |
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); | |
ecee9324 | 122 | int ape_write_hwaddr(struct eth_device *dev); |
1f1e774e MF |
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. | |
e5c5d9e0 MF |
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: | |
1f1e774e MF |
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 | |
e5c5d9e0 MF |
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. | |
1f1e774e | 165 | |
ecee9324 BW |
166 | The write_hwaddr function should program the MAC address stored in dev->enetaddr |
167 | into the Ethernet controller. | |
168 | ||
1f1e774e MF |
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 | ||
c58ea6cb BM |
180 | -------------------------------- |
181 | CONFIG_PHYLIB / CONFIG_CMD_MII | |
182 | -------------------------------- | |
1f1e774e MF |
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 | |
c58ea6cb BM |
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); | |
1f1e774e MF |
200 | |
201 | And then define the mii_read and mii_write functions if you haven't already. | |
202 | Their syntax is straightforward: | |
c58ea6cb BM |
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); | |
1f1e774e MF |
206 | |
207 | The read function should read the register 'reg' from the phy at address 'addr' | |
c58ea6cb BM |
208 | and return the result to its caller. The implementation for the write function |
209 | should logically follow. |