* [PATCH net-next 0/4] Documentation: net: phy: Improve documentation
@ 2016-11-27 6:01 Florian Fainelli
2016-11-27 6:01 ` [PATCH net-next 1/4] Documentation: net: phy: remove description of function pointers Florian Fainelli
` (4 more replies)
0 siblings, 5 replies; 6+ messages in thread
From: Florian Fainelli @ 2016-11-27 6:01 UTC (permalink / raw)
To: netdev
Cc: davem, andrew, sf84, martin.blumenstingl, mans, alexandre.torgue,
peppe.cavallaro, timur, jbrunet, Florian Fainelli
Hi all,
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.
Florian Fainelli (4):
Documentation: net: phy: remove description of function pointers
Documentation: net: phy: Add a paragraph about pause frames/flow
control
Documentation: net: phy: Add blurb about RGMII
Documentation: net: phy: Add links to several standards documents
Documentation/networking/phy.txt | 119 +++++++++++++++++++++++++++------------
1 file changed, 84 insertions(+), 35 deletions(-)
--
2.9.3
^ permalink raw reply [flat|nested] 6+ messages in thread
* [PATCH net-next 1/4] Documentation: net: phy: remove description of function pointers
2016-11-27 6:01 [PATCH net-next 0/4] Documentation: net: phy: Improve documentation Florian Fainelli
@ 2016-11-27 6:01 ` Florian Fainelli
2016-11-27 6:01 ` [PATCH net-next 2/4] Documentation: net: phy: Add a paragraph about pause frames/flow control Florian Fainelli
` (3 subsequent siblings)
4 siblings, 0 replies; 6+ messages in thread
From: Florian Fainelli @ 2016-11-27 6:01 UTC (permalink / raw)
To: netdev
Cc: davem, andrew, sf84, martin.blumenstingl, mans, alexandre.torgue,
peppe.cavallaro, timur, jbrunet, Florian Fainelli
Remove the function pointers documentation which duplicates information
found in include/linux/phy.h. Maintaining documentation about two
different locations just does not work, but the code is less likely to
be outdated.
Signed-off-by: Florian Fainelli <f.fainelli@gmail.com>
---
Documentation/networking/phy.txt | 35 ++---------------------------------
1 file changed, 2 insertions(+), 33 deletions(-)
diff --git a/Documentation/networking/phy.txt b/Documentation/networking/phy.txt
index 7ab9404a8412..4b25c0f24201 100644
--- a/Documentation/networking/phy.txt
+++ b/Documentation/networking/phy.txt
@@ -251,39 +251,8 @@ Writing a PHY driver
PHY_BASIC_FEATURES, but you can look in include/mii.h for other
features.
- Each driver consists of a number of function pointers:
-
- 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
+ Each driver consists of a number of function pointers, documented
+ in include/linux/phy.h under the phy_driver structure.
Of these, only config_aneg and read_status are required to be
assigned by the driver code. The rest are optional. Also, it is
--
2.9.3
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH net-next 2/4] Documentation: net: phy: Add a paragraph about pause frames/flow control
2016-11-27 6:01 [PATCH net-next 0/4] Documentation: net: phy: Improve documentation Florian Fainelli
2016-11-27 6:01 ` [PATCH net-next 1/4] Documentation: net: phy: remove description of function pointers Florian Fainelli
@ 2016-11-27 6:01 ` Florian Fainelli
2016-11-27 6:01 ` [PATCH net-next 3/4] Documentation: net: phy: Add blurb about RGMII Florian Fainelli
` (2 subsequent siblings)
4 siblings, 0 replies; 6+ messages in thread
From: Florian Fainelli @ 2016-11-27 6:01 UTC (permalink / raw)
To: netdev
Cc: davem, andrew, sf84, martin.blumenstingl, mans, alexandre.torgue,
peppe.cavallaro, timur, jbrunet, Florian Fainelli
Describe that the Ethernet MAC controller is ultimately responsible for
dealing with proper pause frames/flow control advertisement and
enabling, and that it is therefore allowed to have it change
phydev->supported/advertising with SUPPORTED_Pause and
SUPPORTED_AsymPause.
Signed-off-by: Florian Fainelli <f.fainelli@gmail.com>
---
Documentation/networking/phy.txt | 18 ++++++++++++++++--
1 file changed, 16 insertions(+), 2 deletions(-)
diff --git a/Documentation/networking/phy.txt b/Documentation/networking/phy.txt
index 4b25c0f24201..9a42a9414cea 100644
--- a/Documentation/networking/phy.txt
+++ b/Documentation/networking/phy.txt
@@ -127,8 +127,9 @@ Letting the PHY Abstraction Layer do Everything
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
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
- get put into an unsupported state.
+ for these bitfields. Note that you should not SET any bits, except the
+ 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
phy_start(phydev). This tells the PAL that you are ready, and configures the
@@ -139,6 +140,19 @@ Letting the PHY Abstraction Layer do Everything
When you want to disconnect from the network (even if just briefly), you call
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
It is possible that the PAL's built-in state machine needs a little help to
--
2.9.3
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH net-next 3/4] Documentation: net: phy: Add blurb about RGMII
2016-11-27 6:01 [PATCH net-next 0/4] Documentation: net: phy: Improve documentation Florian Fainelli
2016-11-27 6:01 ` [PATCH net-next 1/4] Documentation: net: phy: remove description of function pointers Florian Fainelli
2016-11-27 6:01 ` [PATCH net-next 2/4] Documentation: net: phy: Add a paragraph about pause frames/flow control Florian Fainelli
@ 2016-11-27 6:01 ` Florian Fainelli
2016-11-27 6:01 ` [PATCH net-next 4/4] Documentation: net: phy: Add links to several standards documents Florian Fainelli
2016-11-27 18:18 ` [PATCH net-next 0/4] Documentation: net: phy: Improve documentation Florian Fainelli
4 siblings, 0 replies; 6+ messages in thread
From: Florian Fainelli @ 2016-11-27 6:01 UTC (permalink / raw)
To: netdev
Cc: davem, andrew, sf84, martin.blumenstingl, mans, alexandre.torgue,
peppe.cavallaro, timur, jbrunet, Florian Fainelli
RGMII is a recurring source of pain for people with Gigabit Ethernet
hardware since it may require PHY driver and MAC driver level
configuration hints. Document what are the expectations from PHYLIB and
what options exist.
Signed-off-by: Florian Fainelli <f.fainelli@gmail.com>
---
Documentation/networking/phy.txt | 56 ++++++++++++++++++++++++++++++++++++++++
1 file changed, 56 insertions(+)
diff --git a/Documentation/networking/phy.txt b/Documentation/networking/phy.txt
index 9a42a9414cea..18e9f518b6f9 100644
--- a/Documentation/networking/phy.txt
+++ b/Documentation/networking/phy.txt
@@ -65,6 +65,62 @@ The MDIO bus
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/")
+(RG)MII/electrical interface considerations
+
+ The Reduced Gigabit Medium Independent Interface (RGMII) is a 12 pins
+ electrical signal 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 sink (PHY or MAC)
+ 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 optionaly 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 be inserting a delay for the
+ transmit data lines (TXD[3:0]) processed by the PHY device
+
+ * PHY_INTERFACE_MODE_RGMII_RXID: the PHY should be inserting a delay for the
+ receive data lines (RXD[3:0]) processed by the PHY device
+
+ * PHY_INTERFACE_MODE_RGMII_ID: the PHY should be inserting a delay for both
+ transmit AND receive data lines from/to the PHY device
+
+ Whenever it is possible, it is preferrable to utilize the PHY side RGMII delay
+ for several 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) etc.
+
+ * PHY devices are typically qualified for a large range of temperatures, 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 enabled
+
+ For cases where the PHY is not capable of providing this delay, but the
+ Ethernet MAC driver is capable of doing it, 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.
+
+ 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's drive 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
+
Connecting to a PHY
Sometime during startup, the network driver needs to establish a connection
--
2.9.3
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH net-next 4/4] Documentation: net: phy: Add links to several standards documents
2016-11-27 6:01 [PATCH net-next 0/4] Documentation: net: phy: Improve documentation Florian Fainelli
` (2 preceding siblings ...)
2016-11-27 6:01 ` [PATCH net-next 3/4] Documentation: net: phy: Add blurb about RGMII Florian Fainelli
@ 2016-11-27 6:01 ` Florian Fainelli
2016-11-27 18:18 ` [PATCH net-next 0/4] Documentation: net: phy: Improve documentation Florian Fainelli
4 siblings, 0 replies; 6+ messages in thread
From: Florian Fainelli @ 2016-11-27 6:01 UTC (permalink / raw)
To: netdev
Cc: davem, andrew, sf84, martin.blumenstingl, mans, alexandre.torgue,
peppe.cavallaro, timur, jbrunet, Florian Fainelli
Add links to the IEEE 802.3-2008 document, and the RGMII v1.3 and v2.0
revisions of the standard.
Signed-off-by: Florian Fainelli <f.fainelli@gmail.com>
---
Documentation/networking/phy.txt | 10 ++++++++++
1 file changed, 10 insertions(+)
diff --git a/Documentation/networking/phy.txt b/Documentation/networking/phy.txt
index 18e9f518b6f9..9908490363d6 100644
--- a/Documentation/networking/phy.txt
+++ b/Documentation/networking/phy.txt
@@ -386,3 +386,13 @@ Board Fixups
The stubs set one of the two matching criteria, and set the other one to
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
--
2.9.3
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH net-next 0/4] Documentation: net: phy: Improve documentation
2016-11-27 6:01 [PATCH net-next 0/4] Documentation: net: phy: Improve documentation Florian Fainelli
` (3 preceding siblings ...)
2016-11-27 6:01 ` [PATCH net-next 4/4] Documentation: net: phy: Add links to several standards documents Florian Fainelli
@ 2016-11-27 18:18 ` Florian Fainelli
4 siblings, 0 replies; 6+ messages in thread
From: Florian Fainelli @ 2016-11-27 18:18 UTC (permalink / raw)
To: netdev
Cc: davem, andrew, sf84, martin.blumenstingl, mans, alexandre.torgue,
peppe.cavallaro, timur, jbrunet
David,
Le 26/11/2016 à 22:01, Florian Fainelli a écrit :
> Hi all,
>
> 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.
I will improve patch 3 a bit since it contains some minor mistakes and
could deserve some more clarifications, stay tuned, thanks!
--
Florian
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2016-11-27 18:19 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2016-11-27 6:01 [PATCH net-next 0/4] Documentation: net: phy: Improve documentation Florian Fainelli
2016-11-27 6:01 ` [PATCH net-next 1/4] Documentation: net: phy: remove description of function pointers Florian Fainelli
2016-11-27 6:01 ` [PATCH net-next 2/4] Documentation: net: phy: Add a paragraph about pause frames/flow control Florian Fainelli
2016-11-27 6:01 ` [PATCH net-next 3/4] Documentation: net: phy: Add blurb about RGMII Florian Fainelli
2016-11-27 6:01 ` [PATCH net-next 4/4] Documentation: net: phy: Add links to several standards documents Florian Fainelli
2016-11-27 18:18 ` [PATCH net-next 0/4] Documentation: net: phy: Improve documentation Florian Fainelli
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).