blob: 359a0523cf98e175dc914bedf0b04b5f3690dd01 [file] [log] [blame]
Andre Przywara21e4ee32019-11-25 01:32:15 +00001Ethernet Driver Guide
2=======================
3
4The networking stack in Das U-Boot is designed for multiple network devices
5to be easily added and controlled at runtime. This guide is meant for people
6who wish to review the net driver stack with an eye towards implementing your
7own ethernet device driver. Here we will describe a new pseudo 'APE' driver.
8
9Most existing drivers do already - and new network driver MUST - use the
10U-Boot core driver model. Generic information about this can be found in
11doc/driver-model/design.rst, this document will thus focus on the network
12specific code parts.
13Some drivers are still using the old Ethernet interface, differences between
14the two and hints about porting will be handled at the end.
15
16Driver framework
17------------------
18
19A network driver following the driver model must declare itself using
20the UCLASS_ETH .id field in the U-Boot driver struct:
21
22.. code-block:: c
23
24 U_BOOT_DRIVER(eth_ape) = {
25 .name = "eth_ape",
26 .id = UCLASS_ETH,
27 .of_match = eth_ape_ids,
28 .ofdata_to_platdata = eth_ape_ofdata_to_platdata,
29 .probe = eth_ape_probe,
30 .ops = &eth_ape_ops,
31 .priv_auto_alloc_size = sizeof(struct eth_ape_priv),
32 .platdata_auto_alloc_size = sizeof(struct eth_ape_pdata),
33 .flags = DM_FLAG_ALLOC_PRIV_DMA,
34 };
35
36struct eth_ape_priv contains runtime per-instance data, like buffers, pointers
37to current descriptors, current speed settings, pointers to PHY related data
38(like struct mii_dev) and so on. Declaring its size in .priv_auto_alloc_size
39will let the driver framework allocate it at the right time.
40It can be retrieved using a dev_get_priv(dev) call.
41
42struct eth_ape_pdata contains static platform data, like the MMIO base address,
43a hardware variant, the MAC address. ``struct eth_pdata eth_pdata``
44as the first member of this struct helps to avoid duplicated code.
45If you don't need any more platform data beside the standard member,
46just use sizeof(struct eth_pdata) for the platdata_auto_alloc_size.
47
48PCI devices add a line pointing to supported vendor/device ID pairs:
49
50.. code-block:: c
51
52 static struct pci_device_id supported[] = {
53 { PCI_DEVICE(PCI_VENDOR_ID_APE, 0x4223) },
54 {}
55 };
56
57 U_BOOT_PCI_DEVICE(eth_ape, supported);
58
59It is also possible to declare support for a whole class of PCI devices::
60
61 { PCI_DEVICE_CLASS(PCI_CLASS_SYSTEM_SDHCI << 8, 0xffff00) },
62
63Device probing and instantiation will be handled by the driver model framework,
64so follow the guidelines there. The probe() function would initialise the
65platform specific parts of the hardware, like clocks, resets, GPIOs, the MDIO
66bus. Also it would take care of any special PHY setup (power rails, enable
67bits for internal PHYs, etc.).
68
69Driver methods
70----------------
71
72The real work will be done in the driver method functions the driver provides
73by defining the members of struct eth_ops:
74
75.. code-block:: c
76
77 struct eth_ops {
78 int (*start)(struct udevice *dev);
79 int (*send)(struct udevice *dev, void *packet, int length);
80 int (*recv)(struct udevice *dev, int flags, uchar **packetp);
81 int (*free_pkt)(struct udevice *dev, uchar *packet, int length);
82 void (*stop)(struct udevice *dev);
83 int (*mcast)(struct udevice *dev, const u8 *enetaddr, int join);
84 int (*write_hwaddr)(struct udevice *dev);
85 int (*read_rom_hwaddr)(struct udevice *dev);
86 };
87
88An up-to-date version of this struct together with more information can be
89found in include/net.h.
90
91Only start, stop, send and recv are required, the rest are optional and are
92handled by generic code or ignored if not provided.
93
94The **start** function initialises the hardware and gets it ready for send/recv
95operations. You often do things here such as resetting the MAC
96and/or PHY, and waiting for the link to autonegotiate. You should also take
97the opportunity to program the device's MAC address with the enetaddr member
98of the generic struct eth_pdata (which would be the first member of your
99own platdata struct). This allows the rest of U-Boot to dynamically change
100the MAC address and have the new settings be respected.
101
102The **send** function does what you think -- transmit the specified packet
103whose size is specified by length (in bytes). The packet buffer can (and
104will!) be reused for subsequent calls to send(), so it must be no longer
105used when the send() function returns. The easiest way to achieve this is
106to wait until the transmission is complete. Alternatively, if supported by
107the hardware, just waiting for the buffer to be consumed (by some DMA engine)
108might be an option as well.
109Another way of consuming the buffer could be to copy the data to be send,
110then just queue the copied packet (for instance handing it over to a DMA
111engine), and return immediately afterwards.
112In any case you should leave the state such that the send function can be
113called multiple times in a row.
114
115The **recv** function polls for availability of a new packet. If none is
116available, it must return with -EAGAIN.
117If a packet has been received, make sure it is accessible to the CPU
118(invalidate caches if needed), then write its address to the packetp pointer,
119and return the length. If there is an error (receive error, too short or too
120long packet), return 0 if you require the packet to be cleaned up normally,
121or a negative error code otherwise (cleanup not necessary or already done).
122The U-Boot network stack will then process the packet.
123
124If **free_pkt** is defined, U-Boot will call it after a received packet has
125been processed, so the packet buffer can be freed or recycled. Typically you
126would hand it back to the hardware to acquire another packet. free_pkt() will
127be called after recv(), for the same packet, so you don't necessarily need
128to infer the buffer to free from the ``packet`` pointer, but can rely on that
129being the last packet that recv() handled.
130The common code sets up packet buffers for you already in the .bss
131(net_rx_packets), so there should be no need to allocate your own. This doesn't
132mean you must use the net_rx_packets array however; you're free to use any
133buffer you wish.
134
135The **stop** function should turn off / disable the hardware and place it back
136in its reset state. It can be called at any time (before any call to the
137related start() function), so make sure it can handle this sort of thing.
138
139The (optional) **write_hwaddr** function should program the MAC address stored
140in pdata->enetaddr into the Ethernet controller.
141
142So the call graph at this stage would look something like:
143
144.. code-block:: c
145
146 (some net operation (ping / tftp / whatever...))
147 eth_init()
148 ops->start()
149 eth_send()
150 ops->send()
151 eth_rx()
152 ops->recv()
153 (process packet)
154 if (ops->free_pkt)
155 ops->free_pkt()
156 eth_halt()
157 ops->stop()
158
159
160CONFIG_PHYLIB / CONFIG_CMD_MII
161--------------------------------
162
163If your device supports banging arbitrary values on the MII bus (pretty much
164every device does), you should add support for the mii command. Doing so is
165fairly trivial and makes debugging mii issues a lot easier at runtime.
166
167In your driver's ``probe()`` function, add a call to mdio_alloc() and
168mdio_register() like so:
169
170.. code-block:: c
171
172 bus = mdio_alloc();
173 if (!bus) {
174 ...
175 return -ENOMEM;
176 }
177
178 bus->read = ape_mii_read;
179 bus->write = ape_mii_write;
180 mdio_register(bus);
181
182And then define the mii_read and mii_write functions if you haven't already.
183Their syntax is straightforward::
184
185 int mii_read(struct mii_dev *bus, int addr, int devad, int reg);
186 int mii_write(struct mii_dev *bus, int addr, int devad, int reg,
187 u16 val);
188
189The read function should read the register 'reg' from the phy at address 'addr'
190and return the result to its caller. The implementation for the write function
191should logically follow.
192
193................................................................
194
195Legacy network drivers
196------------------------
197
198!!! WARNING !!!
199
200This section below describes the old way of doing things. No new Ethernet
201drivers should be implemented this way. All new drivers should be written
202against the U-Boot core driver model, as described above.
203
204The actual callback functions are fairly similar, the differences are:
205
206- ``start()`` is called ``init()``
207- ``stop()`` is called ``halt()``
208- The ``recv()`` function must loop until all packets have been received, for
209 each packet it must call the net_process_received_packet() function,
210 handing it over the pointer and the length. Afterwards it should free
211 the packet, before checking for new data.
212
213For porting an old driver to the new driver model, split the existing recv()
214function into the actual new recv() function, just fetching **one** packet,
215remove the call to net_process_received_packet(), then move the packet
216cleanup into the ``free_pkt()`` function.
217
218Registering the driver and probing a device is handled very differently,
219follow the recommendations in the driver model design documentation for
220instructions on how to port this over. For the records, the old way of
221initialising a network driver is as follows:
222
223Old network driver registration
224~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
225
226When U-Boot initializes, it will call the common function eth_initialize().
227This will in turn call the board-specific board_eth_init() (or if that fails,
228the cpu-specific cpu_eth_init()). These board-specific functions can do random
229system handling, but ultimately they will call the driver-specific register
230function which in turn takes care of initializing that particular instance.
231
232Keep in mind that you should code the driver to avoid storing state in global
233data as someone might want to hook up two of the same devices to one board.
234Any such information that is specific to an interface should be stored in a
235private, driver-defined data structure and pointed to by eth->priv (see below).
236
237So the call graph at this stage would look something like:
238
239.. code-block:: c
240
241 board_init()
242 eth_initialize()
243 board_eth_init() / cpu_eth_init()
244 driver_register()
245 initialize eth_device
246 eth_register()
247
248At this point in time, the only thing you need to worry about is the driver's
249register function. The pseudo code would look something like:
250
251.. code-block:: c
252
253 int ape_register(bd_t *bis, int iobase)
254 {
255 struct ape_priv *priv;
256 struct eth_device *dev;
257 struct mii_dev *bus;
258
259 priv = malloc(sizeof(*priv));
260 if (priv == NULL)
261 return -ENOMEM;
262
263 dev = malloc(sizeof(*dev));
264 if (dev == NULL) {
265 free(priv);
266 return -ENOMEM;
267 }
268
269 /* setup whatever private state you need */
270
271 memset(dev, 0, sizeof(*dev));
272 sprintf(dev->name, "APE");
273
274 /*
275 * if your device has dedicated hardware storage for the
276 * MAC, read it and initialize dev->enetaddr with it
277 */
278 ape_mac_read(dev->enetaddr);
279
280 dev->iobase = iobase;
281 dev->priv = priv;
282 dev->init = ape_init;
283 dev->halt = ape_halt;
284 dev->send = ape_send;
285 dev->recv = ape_recv;
286 dev->write_hwaddr = ape_write_hwaddr;
287
288 eth_register(dev);
289
290 #ifdef CONFIG_PHYLIB
291 bus = mdio_alloc();
292 if (!bus) {
293 free(priv);
294 free(dev);
295 return -ENOMEM;
296 }
297
298 bus->read = ape_mii_read;
299 bus->write = ape_mii_write;
300 mdio_register(bus);
301 #endif
302
303 return 1;
304 }
305
306The exact arguments needed to initialize your device are up to you. If you
307need to pass more/less arguments, that's fine. You should also add the
308prototype for your new register function to include/netdev.h.
309
310The return value for this function should be as follows:
311< 0 - failure (hardware failure, not probe failure)
312>=0 - number of interfaces detected
313
314You might notice that many drivers seem to use xxx_initialize() rather than
315xxx_register(). This is the old naming convention and should be avoided as it
316causes confusion with the driver-specific init function.
317
318Other than locating the MAC address in dedicated hardware storage, you should
319not touch the hardware in anyway. That step is handled in the driver-specific
320init function. Remember that we are only registering the device here, we are
321not checking its state or doing random probing.