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