README.drivers.eth 7.1 KB

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