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