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
331     Represents the 10G-QXGMII PHY-MAC interface as defined by the Cisco USXGMII
339 The PHY does not participate directly in flow control/pause frames except by
353 It is possible that the PAL's built-in state machine needs a little help to
354 keep your network device and the PHY properly in sync.  If so, you can
355 register a helper function when connecting to the PHY, which will be called
368 There's a remote chance that the PAL's built-in state machine cannot track
369 the complex interactions between the PHY and your network device.  If this is
371 phy_prepare_link().  This will mean that phydev->state is entirely yours to
376 accessed without the state-machine running, and most of these functions are
377 descended from functions which did not interact with a complex state-machine.
392 A convenience function to print out the PHY status neatly.
397 Requests the IRQ for the PHY interrupts.
403 Attaches a network device to a particular PHY, binding the PHY to a generic
416 Fills the phydev structure with up-to-date information about the current
417 settings in the PHY.
434 PHY Device Drivers
437 With the PHY Abstraction Layer, adding support for new PHYs is
439 many PHYs require a little hand-holding to get up-and-running.
441 Generic PHY driver
442 ------------------
444 If the desired PHY doesn't have any errata, quirks, or special
446 support, and let the PHY Abstraction Layer's Generic PHY Driver
449 Writing a PHY driver
450 --------------------
452 If you do need to write a PHY driver, the first thing to do is
453 make sure it can be matched with an appropriate PHY device.
454 This is done during bus initialization by reading the device's
467 etc) your PHY device and driver support.  Most PHYs support
472 in include/linux/phy.h under the phy_driver structure.
476 preferred to use the generic phy driver's versions of these two
484 drivers/net/phy/ for examples (the lxt and qsemi drivers have
487 The PHY's MMD register accesses are handled by the PAL framework
488 by default, but can be overridden by a specific PHY driver if
489 required. This could be the case if a PHY was released for
490 manufacturing before the MMD PHY register definitions were
492 the generic PAL framework for accessing the PHY's MMD registers.
495 registers for EEE query and configuration if the PHY supports
496 the IEEE standard access mechanisms, or can use the PHY's specific
497 access interfaces if overridden by the specific PHY driver. See
498 the Micrel driver in drivers/net/phy/ for an example of how this
504 Sometimes the specific interaction between the platform and the PHY requires
505 special handling.  For instance, to change where the PHY's clock input is,
507 to support such contingencies, the PHY Layer allows platform code to register
508 fixups to be run when the PHY is brought up (or subsequently reset).
510 When the PHY Layer brings up a PHY it checks to see if there are any fixups
511 registered for it, matching based on UID (contained in the PHY device's phy_id
512 field) and the bus identifier (contained in phydev->dev.bus_id).  Both must
516 When a match is found, the PHY layer will invoke the run function associated
518 interest.  It should therefore only operate on that PHY.
551 http://standards.ieee.org/getieee802/download/802.3-2008_section2.pdf