ethernet.rst 12 KB

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