[PATCH net-next 1/4] dt-bindings: net: ethernet-controller: update descriptions of RGMII modes

[Matthias Schiffer]

As discussed [1], the comments for the different rgmii(-*id) modes do not
accurately describe what these values mean.

As the Device Tree is primarily supposed to describe the hardware and not
its configuration, the different modes need to distinguish board designs
(if a delay is built into the PCB using different trace lengths); whether
a delay is added on the MAC or the PHY side when needed should not matter.

Unfortunately, implementation in MAC drivers is somewhat inconsistent
where a delay is fixed or configurable on the MAC side. As a first step
towards sorting this out, improve the documentation.

Link: https://lore.kernel.org/lkml/d25b1447-c28b-4998-b238-92672434dc28@lunn.ch/ [1]
Signed-off-by: Matthias Schiffer <matthias.schiffer at ew.tq-group.com>
---
 .../bindings/net/ethernet-controller.yaml        | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/Documentation/devicetree/bindings/net/ethernet-controller.yaml b/Documentation/devicetree/bindings/net/ethernet-controller.yaml
index 45819b2358002..2ddc1ce2439a6 100644
--- a/Documentation/devicetree/bindings/net/ethernet-controller.yaml
+++ b/Documentation/devicetree/bindings/net/ethernet-controller.yaml
@@ -74,19 +74,21 @@ properties:
       - rev-rmii
       - moca
 
-      # RX and TX delays are added by the MAC when required
+      # RX and TX delays are part of the board design (through PCB traces). MAC
+      # and PHY must not add delays.
       - rgmii
 
-      # RGMII with internal RX and TX delays provided by the PHY,
-      # the MAC should not add the RX or TX delays in this case
+      # RGMII with internal RX and TX delays provided by the MAC or PHY. No
+      # delays are included in the board design; this is the most common case
+      # in modern designs.
       - rgmii-id
 
-      # RGMII with internal RX delay provided by the PHY, the MAC
-      # should not add an RX delay in this case
+      # RGMII with internal RX delay provided by the MAC or PHY. TX delay is
+      # part of the board design.
       - rgmii-rxid
 
-      # RGMII with internal TX delay provided by the PHY, the MAC
-      # should not add an TX delay in this case
+      # RGMII with internal TX delay provided by the MAC or PHY. RX delay is
+      # part of the board design.
       - rgmii-txid
       - rtbi
       - smii
-- 
TQ-Systems GmbH | Mühlstraße 2, Gut Delling | 82229 Seefeld, Germany
Amtsgericht München, HRB 105018
Geschäftsführer: Detlef Schneider, Rüdiger Stahl, Stefan Schneider
https://www.tq-group.com/