Commit 742f74b5 authored by David S. Miller's avatar David S. Miller

Merge branch 'phy-doc-improvements'

Florian Fainelli says:

====================
Documentation: net: phy: Improve documentation

This patch series addresses discussions and feedback that was recently received
on the mailing-list in the area of: flow control/pause frames, interpretation of
phy_interface_t and finally add some links to useful standards documents.

Changes in v3:

- add Timur's feedback into patch 3

Changes in v2:

- clarify a few things in the RGMII section, add a paragraph about common issues
  with RGMII delay mismatches
====================
Signed-off-by: default avatarDavid S. Miller <davem@davemloft.net>
parents 5edef2f2 cc911116
...@@ -65,6 +65,83 @@ The MDIO bus ...@@ -65,6 +65,83 @@ The MDIO bus
drivers/net/ethernet/freescale/fsl_pq_mdio.c and an associated DTS file drivers/net/ethernet/freescale/fsl_pq_mdio.c and an associated DTS file
for one of the users. (e.g. "git grep fsl,.*-mdio arch/powerpc/boot/dts/") for one of the users. (e.g. "git grep fsl,.*-mdio arch/powerpc/boot/dts/")
(RG)MII/electrical interface considerations
The Reduced Gigabit Medium Independent Interface (RGMII) is a 12-pin
electrical signal interface using a synchronous 125Mhz clock signal and several
data lines. Due to this design decision, a 1.5ns to 2ns delay must be added
between the clock line (RXC or TXC) and the data lines to let the PHY (clock
sink) have enough setup and hold times to sample the data lines correctly. The
PHY library offers different types of PHY_INTERFACE_MODE_RGMII* values to let
the PHY driver and optionally the MAC driver, implement the required delay. The
values of phy_interface_t must be understood from the perspective of the PHY
device itself, leading to the following:
* PHY_INTERFACE_MODE_RGMII: the PHY is not responsible for inserting any
internal delay by itself, it assumes that either the Ethernet MAC (if capable
or the PCB traces) insert the correct 1.5-2ns delay
* PHY_INTERFACE_MODE_RGMII_TXID: the PHY should insert an internal delay
for the transmit data lines (TXD[3:0]) processed by the PHY device
* PHY_INTERFACE_MODE_RGMII_RXID: the PHY should insert an internal delay
for the receive data lines (RXD[3:0]) processed by the PHY device
* PHY_INTERFACE_MODE_RGMII_ID: the PHY should insert internal delays for
both transmit AND receive data lines from/to the PHY device
Whenever possible, use the PHY side RGMII delay for these reasons:
* PHY devices may offer sub-nanosecond granularity in how they allow a
receiver/transmitter side delay (e.g: 0.5, 1.0, 1.5ns) to be specified. Such
precision may be required to account for differences in PCB trace lengths
* PHY devices are typically qualified for a large range of applications
(industrial, medical, automotive...), and they provide a constant and
reliable delay across temperature/pressure/voltage ranges
* PHY device drivers in PHYLIB being reusable by nature, being able to
configure correctly a specified delay enables more designs with similar delay
requirements to be operate correctly
For cases where the PHY is not capable of providing this delay, but the
Ethernet MAC driver is capable of doing so, the correct phy_interface_t value
should be PHY_INTERFACE_MODE_RGMII, and the Ethernet MAC driver should be
configured correctly in order to provide the required transmit and/or receive
side delay from the perspective of the PHY device. Conversely, if the Ethernet
MAC driver looks at the phy_interface_t value, for any other mode but
PHY_INTERFACE_MODE_RGMII, it should make sure that the MAC-level delays are
disabled.
In case neither the Ethernet MAC, nor the PHY are capable of providing the
required delays, as defined per the RGMII standard, several options may be
available:
* Some SoCs may offer a pin pad/mux/controller capable of configuring a given
set of pins'strength, delays, and voltage; and it may be a suitable
option to insert the expected 2ns RGMII delay.
* Modifying the PCB design to include a fixed delay (e.g: using a specifically
designed serpentine), which may not require software configuration at all.
Common problems with RGMII delay mismatch
When there is a RGMII delay mismatch between the Ethernet MAC and the PHY, this
will most likely result in the clock and data line signals to be unstable when
the PHY or MAC take a snapshot of these signals to translate them into logical
1 or 0 states and reconstruct the data being transmitted/received. Typical
symptoms include:
* Transmission/reception partially works, and there is frequent or occasional
packet loss observed
* Ethernet MAC may report some or all packets ingressing with a FCS/CRC error,
or just discard them all
* Switching to lower speeds such as 10/100Mbits/sec makes the problem go away
(since there is enough setup/hold time in that case)
Connecting to a PHY Connecting to a PHY
Sometime during startup, the network driver needs to establish a connection Sometime during startup, the network driver needs to establish a connection
...@@ -127,8 +204,9 @@ Letting the PHY Abstraction Layer do Everything ...@@ -127,8 +204,9 @@ Letting the PHY Abstraction Layer do Everything
values pruned from them which don't make sense for your controller (a 10/100 values pruned from them which don't make sense for your controller (a 10/100
controller may be connected to a gigabit capable PHY, so you would need to controller may be connected to a gigabit capable PHY, so you would need to
mask off SUPPORTED_1000baseT*). See include/linux/ethtool.h for definitions mask off SUPPORTED_1000baseT*). See include/linux/ethtool.h for definitions
for these bitfields. Note that you should not SET any bits, or the PHY may for these bitfields. Note that you should not SET any bits, except the
get put into an unsupported state. SUPPORTED_Pause and SUPPORTED_AsymPause bits (see below), or the PHY may get
put into an unsupported state.
Lastly, once the controller is ready to handle network traffic, you call Lastly, once the controller is ready to handle network traffic, you call
phy_start(phydev). This tells the PAL that you are ready, and configures the phy_start(phydev). This tells the PAL that you are ready, and configures the
...@@ -139,6 +217,19 @@ Letting the PHY Abstraction Layer do Everything ...@@ -139,6 +217,19 @@ Letting the PHY Abstraction Layer do Everything
When you want to disconnect from the network (even if just briefly), you call When you want to disconnect from the network (even if just briefly), you call
phy_stop(phydev). phy_stop(phydev).
Pause frames / flow control
The PHY does not participate directly in flow control/pause frames except by
making sure that the SUPPORTED_Pause and SUPPORTED_AsymPause bits are set in
MII_ADVERTISE to indicate towards the link partner that the Ethernet MAC
controller supports such a thing. Since flow control/pause frames generation
involves the Ethernet MAC driver, it is recommended that this driver takes care
of properly indicating advertisement and support for such features by setting
the SUPPORTED_Pause and SUPPORTED_AsymPause bits accordingly. This can be done
either before or after phy_connect() and/or as a result of implementing the
ethtool::set_pauseparam feature.
Keeping Close Tabs on the PAL Keeping Close Tabs on the PAL
It is possible that the PAL's built-in state machine needs a little help to It is possible that the PAL's built-in state machine needs a little help to
...@@ -251,39 +342,8 @@ Writing a PHY driver ...@@ -251,39 +342,8 @@ Writing a PHY driver
PHY_BASIC_FEATURES, but you can look in include/mii.h for other PHY_BASIC_FEATURES, but you can look in include/mii.h for other
features. features.
Each driver consists of a number of function pointers: Each driver consists of a number of function pointers, documented
in include/linux/phy.h under the phy_driver structure.
soft_reset: perform a PHY software reset
config_init: configures PHY into a sane state after a reset.
For instance, a Davicom PHY requires descrambling disabled.
probe: Allocate phy->priv, optionally refuse to bind.
PHY may not have been reset or had fixups run yet.
suspend/resume: power management
config_aneg: Changes the speed/duplex/negotiation settings
aneg_done: Determines the auto-negotiation result
read_status: Reads the current speed/duplex/negotiation settings
ack_interrupt: Clear a pending interrupt
did_interrupt: Checks if the PHY generated an interrupt
config_intr: Enable or disable interrupts
remove: Does any driver take-down
ts_info: Queries about the HW timestamping status
match_phy_device: used for Clause 45 capable PHYs to match devices
in package and ensure they are compatible
hwtstamp: Set the PHY HW timestamping configuration
rxtstamp: Requests a receive timestamp at the PHY level for a 'skb'
txtsamp: Requests a transmit timestamp at the PHY level for a 'skb'
set_wol: Enable Wake-on-LAN at the PHY level
get_wol: Get the Wake-on-LAN status at the PHY level
link_change_notify: called to inform the core is about to change the
link state, can be used to work around bogus PHY between state changes
read_mmd_indirect: Read PHY MMD indirect register
write_mmd_indirect: Write PHY MMD indirect register
module_info: Get the size and type of an EEPROM contained in an plug-in
module
module_eeprom: Get EEPROM information of a plug-in module
get_sset_count: Get number of strings sets that get_strings will count
get_strings: Get strings from requested objects (statistics)
get_stats: Get the extended statistics from the PHY device
Of these, only config_aneg and read_status are required to be Of these, only config_aneg and read_status are required to be
assigned by the driver code. The rest are optional. Also, it is assigned by the driver code. The rest are optional. Also, it is
...@@ -347,3 +407,13 @@ Board Fixups ...@@ -347,3 +407,13 @@ Board Fixups
The stubs set one of the two matching criteria, and set the other one to The stubs set one of the two matching criteria, and set the other one to
match anything. match anything.
Standards
IEEE Standard 802.3: CSMA/CD Access Method and Physical Layer Specifications, Section Two:
http://standards.ieee.org/getieee802/download/802.3-2008_section2.pdf
RGMII v1.3:
http://web.archive.org/web/20160303212629/http://www.hp.com/rnd/pdfs/RGMIIv1_3.pdf
RGMII v2.0:
http://web.archive.org/web/20160303171328/http://www.hp.com/rnd/pdfs/RGMIIv2_0_final_hp.pdf
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment