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