^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) PHY Abstraction Layer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) Purpose
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) =======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) Most network devices consist of set of registers which provide an interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) to a MAC layer, which communicates with the physical connection through a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) PHY. The PHY concerns itself with negotiating link parameters with the link
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) partner on the other side of the network connection (typically, an ethernet
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) cable), and provides a register interface to allow drivers to determine what
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) settings were chosen, and to configure what settings are allowed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) While these devices are distinct from the network devices, and conform to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) standard layout for the registers, it has been common practice to integrate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) the PHY management code with the network driver. This has resulted in large
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) amounts of redundant code. Also, on embedded systems with multiple (and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) sometimes quite different) ethernet controllers connected to the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) management bus, it is difficult to ensure safe use of the bus.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) Since the PHYs are devices, and the management busses through which they are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) accessed are, in fact, busses, the PHY Abstraction Layer treats them as such.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) In doing so, it has these goals:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) #. Increase code-reuse
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) #. Increase overall code-maintainability
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) #. Speed development time for new network drivers, and for new systems
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) Basically, this layer is meant to provide an interface to PHY devices which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) allows network driver writers to write as little code as possible, while
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) still providing a full feature set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) The MDIO bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) Most network devices are connected to a PHY by means of a management bus.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) Different devices use different busses (though some share common interfaces).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) In order to take advantage of the PAL, each bus interface needs to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) registered as a distinct device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) #. read and write functions must be implemented. Their prototypes are::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) int write(struct mii_bus *bus, int mii_id, int regnum, u16 value);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) int read(struct mii_bus *bus, int mii_id, int regnum);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) mii_id is the address on the bus for the PHY, and regnum is the register
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) number. These functions are guaranteed not to be called from interrupt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) time, so it is safe for them to block, waiting for an interrupt to signal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) the operation is complete
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) #. A reset function is optional. This is used to return the bus to an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) initialized state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) #. A probe function is needed. This function should set up anything the bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) driver needs, setup the mii_bus structure, and register with the PAL using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) mdiobus_register. Similarly, there's a remove function to undo all of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) that (use mdiobus_unregister).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) #. Like any driver, the device_driver structure must be configured, and init
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) exit functions are used to register the driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) #. The bus must also be declared somewhere as a device, and registered.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) As an example for how one driver implemented an mdio bus driver, see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) drivers/net/ethernet/freescale/fsl_pq_mdio.c and an associated DTS file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) for one of the users. (e.g. "git grep fsl,.*-mdio arch/powerpc/boot/dts/")
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) (RG)MII/electrical interface considerations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) ===========================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) The Reduced Gigabit Medium Independent Interface (RGMII) is a 12-pin
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) electrical signal interface using a synchronous 125Mhz clock signal and several
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) data lines. Due to this design decision, a 1.5ns to 2ns delay must be added
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) between the clock line (RXC or TXC) and the data lines to let the PHY (clock
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) sink) have a large enough setup and hold time to sample the data lines correctly. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) PHY library offers different types of PHY_INTERFACE_MODE_RGMII* values to let
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) the PHY driver and optionally the MAC driver, implement the required delay. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) values of phy_interface_t must be understood from the perspective of the PHY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) device itself, leading to the following:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) * PHY_INTERFACE_MODE_RGMII: the PHY is not responsible for inserting any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) internal delay by itself, it assumes that either the Ethernet MAC (if capable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) or the PCB traces) insert the correct 1.5-2ns delay
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) * PHY_INTERFACE_MODE_RGMII_TXID: the PHY should insert an internal delay
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) for the transmit data lines (TXD[3:0]) processed by the PHY device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) * PHY_INTERFACE_MODE_RGMII_RXID: the PHY should insert an internal delay
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) for the receive data lines (RXD[3:0]) processed by the PHY device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) * PHY_INTERFACE_MODE_RGMII_ID: the PHY should insert internal delays for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) both transmit AND receive data lines from/to the PHY device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) Whenever possible, use the PHY side RGMII delay for these reasons:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) * PHY devices may offer sub-nanosecond granularity in how they allow a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) receiver/transmitter side delay (e.g: 0.5, 1.0, 1.5ns) to be specified. Such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) precision may be required to account for differences in PCB trace lengths
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) * PHY devices are typically qualified for a large range of applications
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) (industrial, medical, automotive...), and they provide a constant and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) reliable delay across temperature/pressure/voltage ranges
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) * PHY device drivers in PHYLIB being reusable by nature, being able to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) configure correctly a specified delay enables more designs with similar delay
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) requirements to be operate correctly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) For cases where the PHY is not capable of providing this delay, but the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) Ethernet MAC driver is capable of doing so, the correct phy_interface_t value
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) should be PHY_INTERFACE_MODE_RGMII, and the Ethernet MAC driver should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) configured correctly in order to provide the required transmit and/or receive
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) side delay from the perspective of the PHY device. Conversely, if the Ethernet
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) MAC driver looks at the phy_interface_t value, for any other mode but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) PHY_INTERFACE_MODE_RGMII, it should make sure that the MAC-level delays are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) disabled.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) In case neither the Ethernet MAC, nor the PHY are capable of providing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) required delays, as defined per the RGMII standard, several options may be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) available:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) * Some SoCs may offer a pin pad/mux/controller capable of configuring a given
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) set of pins'strength, delays, and voltage; and it may be a suitable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) option to insert the expected 2ns RGMII delay.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) * Modifying the PCB design to include a fixed delay (e.g: using a specifically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) designed serpentine), which may not require software configuration at all.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) Common problems with RGMII delay mismatch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) -----------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) When there is a RGMII delay mismatch between the Ethernet MAC and the PHY, this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) will most likely result in the clock and data line signals to be unstable when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) the PHY or MAC take a snapshot of these signals to translate them into logical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) 1 or 0 states and reconstruct the data being transmitted/received. Typical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) symptoms include:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) * Transmission/reception partially works, and there is frequent or occasional
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) packet loss observed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) * Ethernet MAC may report some or all packets ingressing with a FCS/CRC error,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) or just discard them all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) * Switching to lower speeds such as 10/100Mbits/sec makes the problem go away
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) (since there is enough setup/hold time in that case)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) Connecting to a PHY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) ===================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) Sometime during startup, the network driver needs to establish a connection
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) between the PHY device, and the network device. At this time, the PHY's bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) and drivers need to all have been loaded, so it is ready for the connection.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) At this point, there are several ways to connect to the PHY:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) #. The PAL handles everything, and only calls the network driver when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) the link state changes, so it can react.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) #. The PAL handles everything except interrupts (usually because the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) controller has the interrupt registers).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) #. The PAL handles everything, but checks in with the driver every second,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) allowing the network driver to react first to any changes before the PAL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) does.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) #. The PAL serves only as a library of functions, with the network device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) manually calling functions to update status, and configure the PHY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) Letting the PHY Abstraction Layer do Everything
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) ===============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) If you choose option 1 (The hope is that every driver can, but to still be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) useful to drivers that can't), connecting to the PHY is simple:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) First, you need a function to react to changes in the link state. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) function follows this protocol::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) static void adjust_link(struct net_device *dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) Next, you need to know the device name of the PHY connected to this device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) The name will look something like, "0:00", where the first number is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) bus id, and the second is the PHY's address on that bus. Typically,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) the bus is responsible for making its ID unique.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) Now, to connect, just call this function::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) phydev = phy_connect(dev, phy_name, &adjust_link, interface);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) *phydev* is a pointer to the phy_device structure which represents the PHY.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) If phy_connect is successful, it will return the pointer. dev, here, is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) pointer to your net_device. Once done, this function will have started the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) PHY's software state machine, and registered for the PHY's interrupt, if it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) has one. The phydev structure will be populated with information about the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) current state, though the PHY will not yet be truly operational at this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) point.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) PHY-specific flags should be set in phydev->dev_flags prior to the call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) to phy_connect() such that the underlying PHY driver can check for flags
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) and perform specific operations based on them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) This is useful if the system has put hardware restrictions on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) the PHY/controller, of which the PHY needs to be aware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) *interface* is a u32 which specifies the connection type used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) between the controller and the PHY. Examples are GMII, MII,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) RGMII, and SGMII. See "PHY interface mode" below. For a full
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) list, see include/linux/phy.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) Now just make sure that phydev->supported and phydev->advertising have any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) values pruned from them which don't make sense for your controller (a 10/100
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) controller may be connected to a gigabit capable PHY, so you would need to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) mask off SUPPORTED_1000baseT*). See include/linux/ethtool.h for definitions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) for these bitfields. Note that you should not SET any bits, except the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) SUPPORTED_Pause and SUPPORTED_AsymPause bits (see below), or the PHY may get
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) put into an unsupported state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) Lastly, once the controller is ready to handle network traffic, you call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) phy_start(phydev). This tells the PAL that you are ready, and configures the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) PHY to connect to the network. If the MAC interrupt of your network driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) also handles PHY status changes, just set phydev->irq to PHY_IGNORE_INTERRUPT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) before you call phy_start and use phy_mac_interrupt() from the network
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) driver. If you don't want to use interrupts, set phydev->irq to PHY_POLL.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) phy_start() enables the PHY interrupts (if applicable) and starts the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) phylib state machine.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) When you want to disconnect from the network (even if just briefly), you call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) phy_stop(phydev). This function also stops the phylib state machine and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) disables PHY interrupts.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) PHY interface modes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) ===================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) The PHY interface mode supplied in the phy_connect() family of functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) defines the initial operating mode of the PHY interface. This is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) guaranteed to remain constant; there are PHYs which dynamically change
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) their interface mode without software interaction depending on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) negotiation results.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) Some of the interface modes are described below:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) ``PHY_INTERFACE_MODE_1000BASEX``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) This defines the 1000BASE-X single-lane serdes link as defined by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) 802.3 standard section 36. The link operates at a fixed bit rate of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) 1.25Gbaud using a 10B/8B encoding scheme, resulting in an underlying
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) data rate of 1Gbps. Embedded in the data stream is a 16-bit control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) word which is used to negotiate the duplex and pause modes with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) remote end. This does not include "up-clocked" variants such as 2.5Gbps
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) speeds (see below.)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) ``PHY_INTERFACE_MODE_2500BASEX``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) This defines a variant of 1000BASE-X which is clocked 2.5 times as fast
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) as the 802.3 standard, giving a fixed bit rate of 3.125Gbaud.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) ``PHY_INTERFACE_MODE_SGMII``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) This is used for Cisco SGMII, which is a modification of 1000BASE-X
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) as defined by the 802.3 standard. The SGMII link consists of a single
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) serdes lane running at a fixed bit rate of 1.25Gbaud with 10B/8B
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) encoding. The underlying data rate is 1Gbps, with the slower speeds of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) 100Mbps and 10Mbps being achieved through replication of each data symbol.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) The 802.3 control word is re-purposed to send the negotiated speed and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) duplex information from to the MAC, and for the MAC to acknowledge
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) receipt. This does not include "up-clocked" variants such as 2.5Gbps
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) speeds.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) Note: mismatched SGMII vs 1000BASE-X configuration on a link can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) successfully pass data in some circumstances, but the 16-bit control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) word will not be correctly interpreted, which may cause mismatches in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) duplex, pause or other settings. This is dependent on the MAC and/or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) PHY behaviour.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) ``PHY_INTERFACE_MODE_10GBASER``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) This is the IEEE 802.3 Clause 49 defined 10GBASE-R protocol used with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) various different mediums. Please refer to the IEEE standard for a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) definition of this.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) Note: 10GBASE-R is just one protocol that can be used with XFI and SFI.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) XFI and SFI permit multiple protocols over a single SERDES lane, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) also defines the electrical characteristics of the signals with a host
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) compliance board plugged into the host XFP/SFP connector. Therefore,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) XFI and SFI are not PHY interface types in their own right.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) ``PHY_INTERFACE_MODE_10GKR``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) This is the IEEE 802.3 Clause 49 defined 10GBASE-R with Clause 73
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) autonegotiation. Please refer to the IEEE standard for further
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) information.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) Note: due to legacy usage, some 10GBASE-R usage incorrectly makes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) use of this definition.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) Pause frames / flow control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) ===========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) The PHY does not participate directly in flow control/pause frames except by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) making sure that the SUPPORTED_Pause and SUPPORTED_AsymPause bits are set in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) MII_ADVERTISE to indicate towards the link partner that the Ethernet MAC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) controller supports such a thing. Since flow control/pause frames generation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) involves the Ethernet MAC driver, it is recommended that this driver takes care
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) of properly indicating advertisement and support for such features by setting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) the SUPPORTED_Pause and SUPPORTED_AsymPause bits accordingly. This can be done
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) either before or after phy_connect() and/or as a result of implementing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) ethtool::set_pauseparam feature.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) Keeping Close Tabs on the PAL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) =============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) It is possible that the PAL's built-in state machine needs a little help to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) keep your network device and the PHY properly in sync. If so, you can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) register a helper function when connecting to the PHY, which will be called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) every second before the state machine reacts to any changes. To do this, you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) need to manually call phy_attach() and phy_prepare_link(), and then call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) phy_start_machine() with the second argument set to point to your special
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) handler.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) Currently there are no examples of how to use this functionality, and testing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) on it has been limited because the author does not have any drivers which use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) it (they all use option 1). So Caveat Emptor.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) Doing it all yourself
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) There's a remote chance that the PAL's built-in state machine cannot track
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) the complex interactions between the PHY and your network device. If this is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) so, you can simply call phy_attach(), and not call phy_start_machine or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) phy_prepare_link(). This will mean that phydev->state is entirely yours to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) handle (phy_start and phy_stop toggle between some of the states, so you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) might need to avoid them).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) An effort has been made to make sure that useful functionality can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) accessed without the state-machine running, and most of these functions are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) descended from functions which did not interact with a complex state-machine.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) However, again, no effort has been made so far to test running without the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) state machine, so tryer beware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) Here is a brief rundown of the functions::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) int phy_read(struct phy_device *phydev, u16 regnum);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) int phy_write(struct phy_device *phydev, u16 regnum, u16 val);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) Simple read/write primitives. They invoke the bus's read/write function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) pointers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) void phy_print_status(struct phy_device *phydev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) A convenience function to print out the PHY status neatly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) void phy_request_interrupt(struct phy_device *phydev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) Requests the IRQ for the PHY interrupts.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) struct phy_device * phy_attach(struct net_device *dev, const char *phy_id,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) phy_interface_t interface);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) Attaches a network device to a particular PHY, binding the PHY to a generic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) driver if none was found during bus initialization.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) int phy_start_aneg(struct phy_device *phydev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) Using variables inside the phydev structure, either configures advertising
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) and resets autonegotiation, or disables autonegotiation, and configures
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) forced settings.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) static inline int phy_read_status(struct phy_device *phydev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) Fills the phydev structure with up-to-date information about the current
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) settings in the PHY.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) int phy_ethtool_ksettings_set(struct phy_device *phydev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) const struct ethtool_link_ksettings *cmd);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) Ethtool convenience functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) int phy_mii_ioctl(struct phy_device *phydev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) struct mii_ioctl_data *mii_data, int cmd);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) The MII ioctl. Note that this function will completely screw up the state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) machine if you write registers like BMCR, BMSR, ADVERTISE, etc. Best to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) use this only to write registers which are not standard, and don't set off
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) a renegotiation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) PHY Device Drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) With the PHY Abstraction Layer, adding support for new PHYs is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) quite easy. In some cases, no work is required at all! However,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) many PHYs require a little hand-holding to get up-and-running.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) Generic PHY driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) ------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) If the desired PHY doesn't have any errata, quirks, or special
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) features you want to support, then it may be best to not add
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) support, and let the PHY Abstraction Layer's Generic PHY Driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) do all of the work.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) Writing a PHY driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) If you do need to write a PHY driver, the first thing to do is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) make sure it can be matched with an appropriate PHY device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) This is done during bus initialization by reading the device's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) UID (stored in registers 2 and 3), then comparing it to each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) driver's phy_id field by ANDing it with each driver's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) phy_id_mask field. Also, it needs a name. Here's an example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) static struct phy_driver dm9161_driver = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) .phy_id = 0x0181b880,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) .name = "Davicom DM9161E",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) .phy_id_mask = 0x0ffffff0,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) Next, you need to specify what features (speed, duplex, autoneg,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) etc) your PHY device and driver support. Most PHYs support
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) PHY_BASIC_FEATURES, but you can look in include/mii.h for other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) features.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) Each driver consists of a number of function pointers, documented
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) in include/linux/phy.h under the phy_driver structure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) Of these, only config_aneg and read_status are required to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) assigned by the driver code. The rest are optional. Also, it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429) preferred to use the generic phy driver's versions of these two
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) functions if at all possible: genphy_read_status and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) genphy_config_aneg. If this is not possible, it is likely that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432) you only need to perform some actions before and after invoking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) these functions, and so your functions will wrap the generic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) ones.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) Feel free to look at the Marvell, Cicada, and Davicom drivers in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) drivers/net/phy/ for examples (the lxt and qsemi drivers have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438) not been tested as of this writing).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) The PHY's MMD register accesses are handled by the PAL framework
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) by default, but can be overridden by a specific PHY driver if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) required. This could be the case if a PHY was released for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) manufacturing before the MMD PHY register definitions were
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) standardized by the IEEE. Most modern PHYs will be able to use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) the generic PAL framework for accessing the PHY's MMD registers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446) An example of such usage is for Energy Efficient Ethernet support,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) implemented in the PAL. This support uses the PAL to access MMD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) registers for EEE query and configuration if the PHY supports
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449) the IEEE standard access mechanisms, or can use the PHY's specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) access interfaces if overridden by the specific PHY driver. See
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) the Micrel driver in drivers/net/phy/ for an example of how this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) can be implemented.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454) Board Fixups
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457) Sometimes the specific interaction between the platform and the PHY requires
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) special handling. For instance, to change where the PHY's clock input is,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) or to add a delay to account for latency issues in the data path. In order
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) to support such contingencies, the PHY Layer allows platform code to register
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461) fixups to be run when the PHY is brought up (or subsequently reset).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) When the PHY Layer brings up a PHY it checks to see if there are any fixups
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) registered for it, matching based on UID (contained in the PHY device's phy_id
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) field) and the bus identifier (contained in phydev->dev.bus_id). Both must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466) match, however two constants, PHY_ANY_ID and PHY_ANY_UID, are provided as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) wildcards for the bus ID and UID, respectively.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) When a match is found, the PHY layer will invoke the run function associated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470) with the fixup. This function is passed a pointer to the phy_device of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471) interest. It should therefore only operate on that PHY.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) The platform code can either register the fixup using phy_register_fixup()::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) int phy_register_fixup(const char *phy_id,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) u32 phy_uid, u32 phy_uid_mask,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477) int (*run)(struct phy_device *));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479) Or using one of the two stubs, phy_register_fixup_for_uid() and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) phy_register_fixup_for_id()::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) int phy_register_fixup_for_uid(u32 phy_uid, u32 phy_uid_mask,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) int (*run)(struct phy_device *));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484) int phy_register_fixup_for_id(const char *phy_id,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) int (*run)(struct phy_device *));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) The stubs set one of the two matching criteria, and set the other one to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) match anything.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490) When phy_register_fixup() or \*_for_uid()/\*_for_id() is called at module load
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) time, the module needs to unregister the fixup and free allocated memory when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492) it's unloaded.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) Call one of following function before unloading module::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) int phy_unregister_fixup(const char *phy_id, u32 phy_uid, u32 phy_uid_mask);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497) int phy_unregister_fixup_for_uid(u32 phy_uid, u32 phy_uid_mask);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) int phy_register_fixup_for_id(const char *phy_id);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500) Standards
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501) =========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) IEEE Standard 802.3: CSMA/CD Access Method and Physical Layer Specifications, Section Two:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504) http://standards.ieee.org/getieee802/download/802.3-2008_section2.pdf
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506) RGMII v1.3:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507) http://web.archive.org/web/20160303212629/http://www.hp.com/rnd/pdfs/RGMIIv1_3.pdf
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) RGMII v2.0:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510) http://web.archive.org/web/20160303171328/http://www.hp.com/rnd/pdfs/RGMIIv2_0_final_hp.pdf
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags