Root/
1 | |
2 | ------- |
3 | PHY Abstraction Layer |
4 | (Updated 2008-04-08) |
5 | |
6 | Purpose |
7 | |
8 | Most network devices consist of set of registers which provide an interface |
9 | to a MAC layer, which communicates with the physical connection through a |
10 | PHY. The PHY concerns itself with negotiating link parameters with the link |
11 | partner on the other side of the network connection (typically, an ethernet |
12 | cable), and provides a register interface to allow drivers to determine what |
13 | settings were chosen, and to configure what settings are allowed. |
14 | |
15 | While these devices are distinct from the network devices, and conform to a |
16 | standard layout for the registers, it has been common practice to integrate |
17 | the PHY management code with the network driver. This has resulted in large |
18 | amounts of redundant code. Also, on embedded systems with multiple (and |
19 | sometimes quite different) ethernet controllers connected to the same |
20 | management bus, it is difficult to ensure safe use of the bus. |
21 | |
22 | Since the PHYs are devices, and the management busses through which they are |
23 | accessed are, in fact, busses, the PHY Abstraction Layer treats them as such. |
24 | In doing so, it has these goals: |
25 | |
26 | 1) Increase code-reuse |
27 | 2) Increase overall code-maintainability |
28 | 3) Speed development time for new network drivers, and for new systems |
29 | |
30 | Basically, this layer is meant to provide an interface to PHY devices which |
31 | allows network driver writers to write as little code as possible, while |
32 | still providing a full feature set. |
33 | |
34 | The MDIO bus |
35 | |
36 | Most network devices are connected to a PHY by means of a management bus. |
37 | Different devices use different busses (though some share common interfaces). |
38 | In order to take advantage of the PAL, each bus interface needs to be |
39 | registered as a distinct device. |
40 | |
41 | 1) read and write functions must be implemented. Their prototypes are: |
42 | |
43 | int write(struct mii_bus *bus, int mii_id, int regnum, u16 value); |
44 | int read(struct mii_bus *bus, int mii_id, int regnum); |
45 | |
46 | mii_id is the address on the bus for the PHY, and regnum is the register |
47 | number. These functions are guaranteed not to be called from interrupt |
48 | time, so it is safe for them to block, waiting for an interrupt to signal |
49 | the operation is complete |
50 | |
51 | 2) A reset function is necessary. This is used to return the bus to an |
52 | initialized state. |
53 | |
54 | 3) A probe function is needed. This function should set up anything the bus |
55 | driver needs, setup the mii_bus structure, and register with the PAL using |
56 | mdiobus_register. Similarly, there's a remove function to undo all of |
57 | that (use mdiobus_unregister). |
58 | |
59 | 4) Like any driver, the device_driver structure must be configured, and init |
60 | exit functions are used to register the driver. |
61 | |
62 | 5) The bus must also be declared somewhere as a device, and registered. |
63 | |
64 | As an example for how one driver implemented an mdio bus driver, see |
65 | drivers/net/gianfar_mii.c and arch/ppc/syslib/mpc85xx_devices.c |
66 | |
67 | Connecting to a PHY |
68 | |
69 | Sometime during startup, the network driver needs to establish a connection |
70 | between the PHY device, and the network device. At this time, the PHY's bus |
71 | and drivers need to all have been loaded, so it is ready for the connection. |
72 | At this point, there are several ways to connect to the PHY: |
73 | |
74 | 1) The PAL handles everything, and only calls the network driver when |
75 | the link state changes, so it can react. |
76 | |
77 | 2) The PAL handles everything except interrupts (usually because the |
78 | controller has the interrupt registers). |
79 | |
80 | 3) The PAL handles everything, but checks in with the driver every second, |
81 | allowing the network driver to react first to any changes before the PAL |
82 | does. |
83 | |
84 | 4) The PAL serves only as a library of functions, with the network device |
85 | manually calling functions to update status, and configure the PHY |
86 | |
87 | |
88 | Letting the PHY Abstraction Layer do Everything |
89 | |
90 | If you choose option 1 (The hope is that every driver can, but to still be |
91 | useful to drivers that can't), connecting to the PHY is simple: |
92 | |
93 | First, you need a function to react to changes in the link state. This |
94 | function follows this protocol: |
95 | |
96 | static void adjust_link(struct net_device *dev); |
97 | |
98 | Next, you need to know the device name of the PHY connected to this device. |
99 | The name will look something like, "0:00", where the first number is the |
100 | bus id, and the second is the PHY's address on that bus. Typically, |
101 | the bus is responsible for making its ID unique. |
102 | |
103 | Now, to connect, just call this function: |
104 | |
105 | phydev = phy_connect(dev, phy_name, &adjust_link, flags, interface); |
106 | |
107 | phydev is a pointer to the phy_device structure which represents the PHY. If |
108 | phy_connect is successful, it will return the pointer. dev, here, is the |
109 | pointer to your net_device. Once done, this function will have started the |
110 | PHY's software state machine, and registered for the PHY's interrupt, if it |
111 | has one. The phydev structure will be populated with information about the |
112 | current state, though the PHY will not yet be truly operational at this |
113 | point. |
114 | |
115 | flags is a u32 which can optionally contain phy-specific flags. |
116 | This is useful if the system has put hardware restrictions on |
117 | the PHY/controller, of which the PHY needs to be aware. |
118 | |
119 | interface is a u32 which specifies the connection type used |
120 | between the controller and the PHY. Examples are GMII, MII, |
121 | RGMII, and SGMII. For a full list, see include/linux/phy.h |
122 | |
123 | Now just make sure that phydev->supported and phydev->advertising have any |
124 | values pruned from them which don't make sense for your controller (a 10/100 |
125 | controller may be connected to a gigabit capable PHY, so you would need to |
126 | mask off SUPPORTED_1000baseT*). See include/linux/ethtool.h for definitions |
127 | for these bitfields. Note that you should not SET any bits, or the PHY may |
128 | get put into an unsupported state. |
129 | |
130 | Lastly, once the controller is ready to handle network traffic, you call |
131 | phy_start(phydev). This tells the PAL that you are ready, and configures the |
132 | PHY to connect to the network. If you want to handle your own interrupts, |
133 | just set phydev->irq to PHY_IGNORE_INTERRUPT before you call phy_start. |
134 | Similarly, if you don't want to use interrupts, set phydev->irq to PHY_POLL. |
135 | |
136 | When you want to disconnect from the network (even if just briefly), you call |
137 | phy_stop(phydev). |
138 | |
139 | Keeping Close Tabs on the PAL |
140 | |
141 | It is possible that the PAL's built-in state machine needs a little help to |
142 | keep your network device and the PHY properly in sync. If so, you can |
143 | register a helper function when connecting to the PHY, which will be called |
144 | every second before the state machine reacts to any changes. To do this, you |
145 | need to manually call phy_attach() and phy_prepare_link(), and then call |
146 | phy_start_machine() with the second argument set to point to your special |
147 | handler. |
148 | |
149 | Currently there are no examples of how to use this functionality, and testing |
150 | on it has been limited because the author does not have any drivers which use |
151 | it (they all use option 1). So Caveat Emptor. |
152 | |
153 | Doing it all yourself |
154 | |
155 | There's a remote chance that the PAL's built-in state machine cannot track |
156 | the complex interactions between the PHY and your network device. If this is |
157 | so, you can simply call phy_attach(), and not call phy_start_machine or |
158 | phy_prepare_link(). This will mean that phydev->state is entirely yours to |
159 | handle (phy_start and phy_stop toggle between some of the states, so you |
160 | might need to avoid them). |
161 | |
162 | An effort has been made to make sure that useful functionality can be |
163 | accessed without the state-machine running, and most of these functions are |
164 | descended from functions which did not interact with a complex state-machine. |
165 | However, again, no effort has been made so far to test running without the |
166 | state machine, so tryer beware. |
167 | |
168 | Here is a brief rundown of the functions: |
169 | |
170 | int phy_read(struct phy_device *phydev, u16 regnum); |
171 | int phy_write(struct phy_device *phydev, u16 regnum, u16 val); |
172 | |
173 | Simple read/write primitives. They invoke the bus's read/write function |
174 | pointers. |
175 | |
176 | void phy_print_status(struct phy_device *phydev); |
177 | |
178 | A convenience function to print out the PHY status neatly. |
179 | |
180 | int phy_start_interrupts(struct phy_device *phydev); |
181 | int phy_stop_interrupts(struct phy_device *phydev); |
182 | |
183 | Requests the IRQ for the PHY interrupts, then enables them for |
184 | start, or disables then frees them for stop. |
185 | |
186 | struct phy_device * phy_attach(struct net_device *dev, const char *phy_id, |
187 | u32 flags, phy_interface_t interface); |
188 | |
189 | Attaches a network device to a particular PHY, binding the PHY to a generic |
190 | driver if none was found during bus initialization. Passes in |
191 | any phy-specific flags as needed. |
192 | |
193 | int phy_start_aneg(struct phy_device *phydev); |
194 | |
195 | Using variables inside the phydev structure, either configures advertising |
196 | and resets autonegotiation, or disables autonegotiation, and configures |
197 | forced settings. |
198 | |
199 | static inline int phy_read_status(struct phy_device *phydev); |
200 | |
201 | Fills the phydev structure with up-to-date information about the current |
202 | settings in the PHY. |
203 | |
204 | int phy_ethtool_sset(struct phy_device *phydev, struct ethtool_cmd *cmd); |
205 | int phy_ethtool_gset(struct phy_device *phydev, struct ethtool_cmd *cmd); |
206 | |
207 | Ethtool convenience functions. |
208 | |
209 | int phy_mii_ioctl(struct phy_device *phydev, |
210 | struct mii_ioctl_data *mii_data, int cmd); |
211 | |
212 | The MII ioctl. Note that this function will completely screw up the state |
213 | machine if you write registers like BMCR, BMSR, ADVERTISE, etc. Best to |
214 | use this only to write registers which are not standard, and don't set off |
215 | a renegotiation. |
216 | |
217 | |
218 | PHY Device Drivers |
219 | |
220 | With the PHY Abstraction Layer, adding support for new PHYs is |
221 | quite easy. In some cases, no work is required at all! However, |
222 | many PHYs require a little hand-holding to get up-and-running. |
223 | |
224 | Generic PHY driver |
225 | |
226 | If the desired PHY doesn't have any errata, quirks, or special |
227 | features you want to support, then it may be best to not add |
228 | support, and let the PHY Abstraction Layer's Generic PHY Driver |
229 | do all of the work. |
230 | |
231 | Writing a PHY driver |
232 | |
233 | If you do need to write a PHY driver, the first thing to do is |
234 | make sure it can be matched with an appropriate PHY device. |
235 | This is done during bus initialization by reading the device's |
236 | UID (stored in registers 2 and 3), then comparing it to each |
237 | driver's phy_id field by ANDing it with each driver's |
238 | phy_id_mask field. Also, it needs a name. Here's an example: |
239 | |
240 | static struct phy_driver dm9161_driver = { |
241 | .phy_id = 0x0181b880, |
242 | .name = "Davicom DM9161E", |
243 | .phy_id_mask = 0x0ffffff0, |
244 | ... |
245 | } |
246 | |
247 | Next, you need to specify what features (speed, duplex, autoneg, |
248 | etc) your PHY device and driver support. Most PHYs support |
249 | PHY_BASIC_FEATURES, but you can look in include/mii.h for other |
250 | features. |
251 | |
252 | Each driver consists of a number of function pointers: |
253 | |
254 | config_init: configures PHY into a sane state after a reset. |
255 | For instance, a Davicom PHY requires descrambling disabled. |
256 | probe: Does any setup needed by the driver |
257 | suspend/resume: power management |
258 | config_aneg: Changes the speed/duplex/negotiation settings |
259 | read_status: Reads the current speed/duplex/negotiation settings |
260 | ack_interrupt: Clear a pending interrupt |
261 | config_intr: Enable or disable interrupts |
262 | remove: Does any driver take-down |
263 | |
264 | Of these, only config_aneg and read_status are required to be |
265 | assigned by the driver code. The rest are optional. Also, it is |
266 | preferred to use the generic phy driver's versions of these two |
267 | functions if at all possible: genphy_read_status and |
268 | genphy_config_aneg. If this is not possible, it is likely that |
269 | you only need to perform some actions before and after invoking |
270 | these functions, and so your functions will wrap the generic |
271 | ones. |
272 | |
273 | Feel free to look at the Marvell, Cicada, and Davicom drivers in |
274 | drivers/net/phy/ for examples (the lxt and qsemi drivers have |
275 | not been tested as of this writing) |
276 | |
277 | Board Fixups |
278 | |
279 | Sometimes the specific interaction between the platform and the PHY requires |
280 | special handling. For instance, to change where the PHY's clock input is, |
281 | or to add a delay to account for latency issues in the data path. In order |
282 | to support such contingencies, the PHY Layer allows platform code to register |
283 | fixups to be run when the PHY is brought up (or subsequently reset). |
284 | |
285 | When the PHY Layer brings up a PHY it checks to see if there are any fixups |
286 | registered for it, matching based on UID (contained in the PHY device's phy_id |
287 | field) and the bus identifier (contained in phydev->dev.bus_id). Both must |
288 | match, however two constants, PHY_ANY_ID and PHY_ANY_UID, are provided as |
289 | wildcards for the bus ID and UID, respectively. |
290 | |
291 | When a match is found, the PHY layer will invoke the run function associated |
292 | with the fixup. This function is passed a pointer to the phy_device of |
293 | interest. It should therefore only operate on that PHY. |
294 | |
295 | The platform code can either register the fixup using phy_register_fixup(): |
296 | |
297 | int phy_register_fixup(const char *phy_id, |
298 | u32 phy_uid, u32 phy_uid_mask, |
299 | int (*run)(struct phy_device *)); |
300 | |
301 | Or using one of the two stubs, phy_register_fixup_for_uid() and |
302 | phy_register_fixup_for_id(): |
303 | |
304 | int phy_register_fixup_for_uid(u32 phy_uid, u32 phy_uid_mask, |
305 | int (*run)(struct phy_device *)); |
306 | int phy_register_fixup_for_id(const char *phy_id, |
307 | int (*run)(struct phy_device *)); |
308 | |
309 | The stubs set one of the two matching criteria, and set the other one to |
310 | match anything. |
311 | |
312 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9