]>
Commit | Line | Data |
---|---|---|
1f1e774e MF |
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 | |
99dbd4ef BW |
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). | |
1f1e774e MF |
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; | |
ecee9324 | 73 | dev->write_hwaddr = ape_write_hwaddr; |
1f1e774e MF |
74 | |
75 | eth_register(dev); | |
76 | ||
77 | #ifdef CONFIG_CMD_MII) | |
78 | miiphy_register(dev->name, ape_mii_read, ape_mii_write); | |
79 | #endif | |
80 | ||
99dbd4ef | 81 | return 1; |
1f1e774e MF |
82 | } |
83 | ||
84 | The exact arguments needed to initialize your device are up to you. If you | |
85 | need to pass more/less arguments, that's fine. You should also add the | |
99dbd4ef BW |
86 | prototype for your new register function to include/netdev.h. |
87 | ||
88 | The return value for this function should be as follows: | |
89 | < 0 - failure (hardware failure, not probe failure) | |
90 | >=0 - number of interfaces detected | |
91 | ||
4946775c | 92 | You might notice that many drivers seem to use xxx_initialize() rather than |
99dbd4ef BW |
93 | xxx_register(). This is the old naming convention and should be avoided as it |
94 | causes confusion with the driver-specific init function. | |
1f1e774e MF |
95 | |
96 | Other than locating the MAC address in dedicated hardware storage, you should | |
97 | not touch the hardware in anyway. That step is handled in the driver-specific | |
98 | init function. Remember that we are only registering the device here, we are | |
99 | not checking its state or doing random probing. | |
100 | ||
101 | ----------- | |
102 | Callbacks | |
103 | ----------- | |
104 | ||
105 | Now that we've registered with the ethernet layer, we can start getting some | |
ecee9324 | 106 | real work done. You will need five functions: |
1f1e774e MF |
107 | 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); | |
ecee9324 | 111 | int ape_write_hwaddr(struct eth_device *dev); |
1f1e774e MF |
112 | |
113 | The init function checks the hardware (probing/identifying) and gets it ready | |
114 | for send/recv operations. You often do things here such as resetting the MAC | |
115 | and/or PHY, and waiting for the link to autonegotiate. You should also take | |
116 | the opportunity to program the device's MAC address with the dev->enetaddr | |
117 | member. This allows the rest of U-Boot to dynamically change the MAC address | |
118 | and have the new settings be respected. | |
119 | ||
120 | The send function does what you think -- transmit the specified packet whose | |
121 | size is specified by length (in bytes). You should not return until the | |
122 | transmission is complete, and you should leave the state such that the send | |
123 | function can be called multiple times in a row. | |
124 | ||
125 | The recv function should process packets as long as the hardware has them | |
126 | readily available before returning. i.e. you should drain the hardware fifo. | |
e5c5d9e0 MF |
127 | For each packet you receive, you should call the NetReceive() function on it |
128 | along with the packet length. The common code sets up packet buffers for you | |
129 | already in the .bss (NetRxPackets), so there should be no need to allocate your | |
130 | own. This doesn't mean you must use the NetRxPackets array however; you're | |
131 | free to call the NetReceive() function with any buffer you wish. So the pseudo | |
132 | code here would look something like: | |
1f1e774e MF |
133 | int 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 | ||
151 | The halt function should turn off / disable the hardware and place it back in | |
e5c5d9e0 MF |
152 | its reset state. It can be called at any time (before any call to the related |
153 | init function), so make sure it can handle this sort of thing. | |
1f1e774e | 154 | |
ecee9324 BW |
155 | The write_hwaddr function should program the MAC address stored in dev->enetaddr |
156 | into the Ethernet controller. | |
157 | ||
1f1e774e MF |
158 | So the call graph at this stage would look something like: |
159 | some 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 | ||
173 | If your device supports banging arbitrary values on the MII bus (pretty much | |
174 | every device does), you should add support for the mii command. Doing so is | |
175 | fairly trivial and makes debugging mii issues a lot easier at runtime. | |
176 | ||
177 | After you have called eth_register() in your driver's register function, add | |
178 | a 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 | ||
183 | And then define the mii_read and mii_write functions if you haven't already. | |
184 | Their 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 | ||
188 | The read function should read the register 'reg' from the phy at address 'addr' | |
189 | and store the result in the pointer 'val'. The implementation for the write | |
190 | function should logically follow. |