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.
40 registered as a distinct device.
47    mii_id is the address on the bus for the PHY, and regnum is the register
63 #. The bus must also be declared somewhere as a device, and registered.
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
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
80 device itself, leading to the following:
82 * PHY_INTERFACE_MODE_RGMII: the PHY is not responsible for inserting any
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
101 * PHY devices are typically qualified for a large range of applications
105 * PHY device drivers in PHYLIB being reusable by nature, being able to
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
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:
165 #. The PAL serves only as a library of functions, with the network device
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_MAC_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
246     This defines the 1000BASE-X single-lane serdes link as defined by the
249     data rate of 1Gbps.  Embedded in the data stream is a 16-bit control
251     remote end.  This does not include "up-clocked" variants such as 2.5Gbps
255     This defines a variant of 1000BASE-X which is clocked 2.5 times as fast
259     This is used for Cisco SGMII, which is a modification of 1000BASE-X
264     The 802.3 control word is re-purposed to send the negotiated speed and
266     receipt.  This does not include "up-clocked" variants such as 2.5Gbps
269     Note: mismatched SGMII vs 1000BASE-X configuration on a link can
270     successfully pass data in some circumstances, but the 16-bit control
273     PHY behaviour.
276     This is the IEEE 802.3 Clause 129 defined 5GBASE-R protocol. It is
277     identical to the 10GBASE-R protocol defined in Clause 49, with the
282     This is the IEEE 802.3 Clause 49 defined 10GBASE-R protocol used with
286     Note: 10GBASE-R is just one protocol that can be used with XFI and SFI.
290     XFI and SFI are not PHY interface types in their own right.
293     This is the IEEE 802.3 Clause 49 defined 10GBASE-R with Clause 73
297     Note: due to legacy usage, some 10GBASE-R usage incorrectly makes
301     This is the IEEE 802.3 PCS Clause 107 defined 25GBASE-R protocol.
302     The PCS is identical to 10GBASE-R, i.e. 64B/66B encoded
315     only the port id, but also so-called "extensions". The only documented
316     extension so-far in the specification is the inclusion of timestamps, for
317     PTP-enabled PHYs. This mode isn't compatible with QSGMII, but offers the
321     This is 1000BASE-X as defined by IEEE 802.3 Clause 36 with Clause 73
323     contrast with the 1000BASE-X phy mode used for Clause 38 and 39 PMDs, this
333 The PHY does not participate directly in flow control/pause frames except by
347 It is possible that the PAL's built-in state machine needs a little help to
348 keep your network device and the PHY properly in sync.  If so, you can
349 register a helper function when connecting to the PHY, which will be called
362 There's a remote chance that the PAL's built-in state machine cannot track
363 the complex interactions between the PHY and your network device.  If this is
365 phy_prepare_link().  This will mean that phydev->state is entirely yours to
370 accessed without the state-machine running, and most of these functions are
371 descended from functions which did not interact with a complex state-machine.
386 A convenience function to print out the PHY status neatly.
391 Requests the IRQ for the PHY interrupts.
397 Attaches a network device to a particular PHY, binding the PHY to a generic
410 Fills the phydev structure with up-to-date information about the current
411 settings in the PHY.
428 PHY Device Drivers
431 With the PHY Abstraction Layer, adding support for new PHYs is
433 many PHYs require a little hand-holding to get up-and-running.
435 Generic PHY driver
436 ------------------
438 If the desired PHY doesn't have any errata, quirks, or special
440 support, and let the PHY Abstraction Layer's Generic PHY Driver
443 Writing a PHY driver
444 --------------------
446 If you do need to write a PHY driver, the first thing to do is
447 make sure it can be matched with an appropriate PHY device.
448 This is done during bus initialization by reading the device's
461 etc) your PHY device and driver support.  Most PHYs support
466 in include/linux/phy.h under the phy_driver structure.
470 preferred to use the generic phy driver's versions of these two
478 drivers/net/phy/ for examples (the lxt and qsemi drivers have
481 The PHY's MMD register accesses are handled by the PAL framework
482 by default, but can be overridden by a specific PHY driver if
483 required. This could be the case if a PHY was released for
484 manufacturing before the MMD PHY register definitions were
486 the generic PAL framework for accessing the PHY's MMD registers.
489 registers for EEE query and configuration if the PHY supports
490 the IEEE standard access mechanisms, or can use the PHY's specific
491 access interfaces if overridden by the specific PHY driver. See
492 the Micrel driver in drivers/net/phy/ for an example of how this
498 Sometimes the specific interaction between the platform and the PHY requires
499 special handling.  For instance, to change where the PHY's clock input is,
501 to support such contingencies, the PHY Layer allows platform code to register
502 fixups to be run when the PHY is brought up (or subsequently reset).
504 When the PHY Layer brings up a PHY it checks to see if there are any fixups
505 registered for it, matching based on UID (contained in the PHY device's phy_id
506 field) and the bus identifier (contained in phydev->dev.bus_id).  Both must
510 When a match is found, the PHY layer will invoke the run function associated
512 interest.  It should therefore only operate on that PHY.
545 http://standards.ieee.org/getieee802/download/802.3-2008_section2.pdf