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.
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
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
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
118 In case neither the Ethernet MAC, nor the PHY are capable of providing the
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
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
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
268     PHY behaviour.
279     XFI and SFI are not PHY interface types in their own right.
292 The PHY does not participate directly in flow control/pause frames except by
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
322 the complex interactions between the PHY and your network device.  If this is
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
370 settings in the PHY.
387 PHY Device Drivers
390 With the PHY Abstraction Layer, adding support for new PHYs is
394 Generic PHY driver
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
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
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
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,
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
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.