Documentation/networking/phy.rst

2 PHY Abstraction Layer
10 PHY.  The PHY concerns itself with negotiating link parameters with the link
17 the PHY management code with the network driver.  This has resulted in large
23 accessed are, in fact, busses, the PHY Abstraction Layer treats them as such.
26 #. Increase code-reuse
27 #. Increase overall code-maintainability
30 Basically, this layer is meant to provide an interface to PHY devices which
37 Most network devices are connected to a PHY by means of a management bus.
47    mii_id is the address on the bus for the PHY, and regnum is the register
67 for one of the users. (e.g. "git grep fsl,.*-mdio arch/powerpc/boot/dts/")
72 The Reduced Gigabit Medium Independent Interface (RGMII) is a 12-pin
74 data lines. Due to this design decision, a 1.5ns to 2ns delay must be added
75 between the clock line (RXC or TXC) and the data lines to let the PHY (clock
77 PHY library offers different types of PHY_INTERFACE_MODE_RGMII* values to let
78 the PHY driver and optionally the MAC driver, implement the required delay. The
79 values of phy_interface_t must be understood from the perspective of the PHY
82 * PHY_INTERFACE_MODE_RGMII: the PHY is not responsible for inserting any
83   internal delay by itself, it assumes that either the Ethernet MAC (if capable
84   or the PCB traces) insert the correct 1.5-2ns delay
86 * PHY_INTERFACE_MODE_RGMII_TXID: the PHY should insert an internal delay
87   for the transmit data lines (TXD[3:0]) processed by the PHY device
89 * PHY_INTERFACE_MODE_RGMII_RXID: the PHY should insert an internal delay
90   for the receive data lines (RXD[3:0]) processed by the PHY device
92 * PHY_INTERFACE_MODE_RGMII_ID: the PHY should insert internal delays for
93   both transmit AND receive data lines from/to the PHY device
95 Whenever possible, use the PHY side RGMII delay for these reasons:
97 * PHY devices may offer sub-nanosecond granularity in how they allow a
98   receiver/transmitter side delay (e.g: 0.5, 1.0, 1.5ns) to be specified. Such
101 * PHY devices are typically qualified for a large range of applications
103   reliable delay across temperature/pressure/voltage ranges
105 * PHY device drivers in PHYLIB being reusable by nature, being able to
106   configure correctly a specified delay enables more designs with similar delay
109 For cases where the PHY is not capable of providing this delay, but the
113 side delay from the perspective of the PHY device. Conversely, if the Ethernet
115 PHY_INTERFACE_MODE_RGMII, it should make sure that the MAC-level delays are
118 In case neither the Ethernet MAC, nor the PHY are capable of providing the
124   option to insert the expected 2ns RGMII delay.
126 * Modifying the PCB design to include a fixed delay (e.g: using a specifically
129 Common problems with RGMII delay mismatch
130 -----------------------------------------
132 When there is a RGMII delay mismatch between the Ethernet MAC and the PHY, this
134 the PHY or MAC take a snapshot of these signals to translate them into logical
147 Connecting to a PHY
151 between the PHY device, and the network device.  At this time, the PHY's bus
153 At this point, there are several ways to connect to the PHY:
166    manually calling functions to update status, and configure the PHY
169 Letting the PHY Abstraction Layer do Everything
173 useful to drivers that can't), connecting to the PHY is simple:
180 Next, you need to know the device name of the PHY connected to this device.
182 bus id, and the second is the PHY's address on that bus.  Typically,
189 *phydev* is a pointer to the phy_device structure which represents the PHY.
192 PHY's software state machine, and registered for the PHY's interrupt, if it
194 current state, though the PHY will not yet be truly operational at this
197 PHY-specific flags should be set in phydev->dev_flags prior to the call
198 to phy_connect() such that the underlying PHY driver can check for flags
201 the PHY/controller, of which the PHY needs to be aware.
204 between the controller and the PHY.  Examples are GMII, MII,
205 RGMII, and SGMII.  See "PHY interface mode" below.  For a full
206 list, see include/linux/phy.h
208 Now just make sure that phydev->supported and phydev->advertising have any
210 controller may be connected to a gigabit capable PHY, so you would need to
213 SUPPORTED_Pause and SUPPORTED_AsymPause bits (see below), or the PHY may get
218 PHY to connect to the network. If the MAC interrupt of your network driver
219 also handles PHY status changes, just set phydev->irq to PHY_IGNORE_INTERRUPT
221 driver. If you don't want to use interrupts, set phydev->irq to PHY_POLL.
222 phy_start() enables the PHY interrupts (if applicable) and starts the
227 disables PHY interrupts.
229 PHY interface modes
232 The PHY interface mode supplied in the phy_connect() family of functions
233 defines the initial operating mode of the PHY interface.  This is not
241     This defines the 1000BASE-X single-lane serdes link as defined by the
244     data rate of 1Gbps.  Embedded in the data stream is a 16-bit control
246     remote end.  This does not include "up-clocked" variants such as 2.5Gbps
250     This defines a variant of 1000BASE-X which is clocked 2.5 times as fast
254     This is used for Cisco SGMII, which is a modification of 1000BASE-X
259     The 802.3 control word is re-purposed to send the negotiated speed and
261     receipt.  This does not include "up-clocked" variants such as 2.5Gbps
264     Note: mismatched SGMII vs 1000BASE-X configuration on a link can
265     successfully pass data in some circumstances, but the 16-bit control
268     PHY behaviour.
271     This is the IEEE 802.3 Clause 49 defined 10GBASE-R protocol used with
275     Note: 10GBASE-R is just one protocol that can be used with XFI and SFI.
279     XFI and SFI are not PHY interface types in their own right.
282     This is the IEEE 802.3 Clause 49 defined 10GBASE-R with Clause 73
286     Note: due to legacy usage, some 10GBASE-R usage incorrectly makes
292 The PHY does not participate directly in flow control/pause frames except by
306 It is possible that the PAL's built-in state machine needs a little help to
307 keep your network device and the PHY properly in sync.  If so, you can
308 register a helper function when connecting to the PHY, which will be called
321 There's a remote chance that the PAL's built-in state machine cannot track
322 the complex interactions between the PHY and your network device.  If this is
324 phy_prepare_link().  This will mean that phydev->state is entirely yours to
329 accessed without the state-machine running, and most of these functions are
330 descended from functions which did not interact with a complex state-machine.
345 A convenience function to print out the PHY status neatly.
350 Requests the IRQ for the PHY interrupts.
356 Attaches a network device to a particular PHY, binding the PHY to a generic
369 Fills the phydev structure with up-to-date information about the current
370 settings in the PHY.
387 PHY Device Drivers
390 With the PHY Abstraction Layer, adding support for new PHYs is
392 many PHYs require a little hand-holding to get up-and-running.
394 Generic PHY driver
395 ------------------
397 If the desired PHY doesn't have any errata, quirks, or special
399 support, and let the PHY Abstraction Layer's Generic PHY Driver
402 Writing a PHY driver
403 --------------------
405 If you do need to write a PHY driver, the first thing to do is
406 make sure it can be matched with an appropriate PHY device.
420 etc) your PHY device and driver support.  Most PHYs support
425 in include/linux/phy.h under the phy_driver structure.
429 preferred to use the generic phy driver's versions of these two
437 drivers/net/phy/ for examples (the lxt and qsemi drivers have
440 The PHY's MMD register accesses are handled by the PAL framework
441 by default, but can be overridden by a specific PHY driver if
442 required. This could be the case if a PHY was released for
443 manufacturing before the MMD PHY register definitions were
445 the generic PAL framework for accessing the PHY's MMD registers.
448 registers for EEE query and configuration if the PHY supports
449 the IEEE standard access mechanisms, or can use the PHY's specific
450 access interfaces if overridden by the specific PHY driver. See
451 the Micrel driver in drivers/net/phy/ for an example of how this
457 Sometimes the specific interaction between the platform and the PHY requires
458 special handling.  For instance, to change where the PHY's clock input is,
459 or to add a delay to account for latency issues in the data path.  In order
460 to support such contingencies, the PHY Layer allows platform code to register
461 fixups to be run when the PHY is brought up (or subsequently reset).
463 When the PHY Layer brings up a PHY it checks to see if there are any fixups
464 registered for it, matching based on UID (contained in the PHY device's phy_id
465 field) and the bus identifier (contained in phydev->dev.bus_id).  Both must
469 When a match is found, the PHY layer will invoke the run function associated
471 interest.  It should therefore only operate on that PHY.
504 http://standards.ieee.org/getieee802/download/802.3-2008_section2.pdf