[PATCH net-next v2 1/2] dt-bindings: net: realtek,rtl82xx: document RTL8224 packages

[Oskari Lemmela]

RTL8224 packages contain four PHYs at consecutive MDIO addresses,
but the first address need not be a multiple of four. Document how
to describe these packages using the existing ethernet-phy-package
binding so their base address is explicit.

Clarify that child PHY addresses are absolute and that MDI pair
order and polarity properties describe the individual ports. Add
an example with a package starting at address 1.

Signed-off-by: Oskari Lemmela <oskari@xxxxxxxxxxx>
---
 .../bindings/net/realtek,rtl82xx.yaml         | 52 +++++++++++++++++--
 1 file changed, 49 insertions(+), 3 deletions(-)

diff --git a/Documentation/devicetree/bindings/net/realtek,rtl82xx.yaml b/Documentation/devicetree/bindings/net/realtek,rtl82xx.yaml
index 07b39ef1fc62..ca52c3ae19f7 100644
--- a/Documentation/devicetree/bindings/net/realtek,rtl82xx.yaml
+++ b/Documentation/devicetree/bindings/net/realtek,rtl82xx.yaml
@@ -12,7 +12,17 @@ maintainers:
   - Heiner Kallweit <hkallweit1@xxxxxxxxx>
 
 description:
-  Bindings for Realtek RTL82xx PHYs
+  Bindings for Realtek RTL82xx PHYs.
+
+  The RTL8224 contains four PHYs at consecutive MDIO addresses. Its PHY
+  nodes may be grouped under an ethernet-phy-package node as described
+  in ethernet-phy-package.yaml. The package reg must identify the first
+  PHY's MDIO address, even if that PHY has no child node. This address
+  need not be a multiple of four. Each child PHY reg is its absolute
+  MDIO address, not an offset from the package base.
+
+  The enet-phy-pair-order and enet-phy-pair-polarity properties belong
+  to the individual PHY nodes and describe each port's MDI wiring.
 
 properties:
   compatible:
@@ -90,9 +100,45 @@ examples:
         #address-cells = <1>;
         #size-cells = <0>;
 
-        ethphy1: ethernet-phy@1 {
+        ethernet-phy@1 {
             reg = <1>;
-            realtek,clkout-disable;
             realtek,aldps-enable;
+            realtek,clkout-disable;
+        };
+    };
+  - |
+    mdio {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        ethernet-phy-package@1 {
+            reg = <1>;
+            #address-cells = <1>;
+            #size-cells = <0>;
+
+            ethernet-phy@1 {
+                compatible = "ethernet-phy-ieee802.3-c45";
+                reg = <1>;
+                enet-phy-pair-order = <0>;
+            };
+
+            ethernet-phy@2 {
+                compatible = "ethernet-phy-ieee802.3-c45";
+                reg = <2>;
+                enet-phy-pair-order = <0>;
+            };
+
+            ethernet-phy@3 {
+                compatible = "ethernet-phy-ieee802.3-c45";
+                reg = <3>;
+                enet-phy-pair-order = <1>;
+            };
+
+            ethernet-phy@4 {
+                compatible = "ethernet-phy-ieee802.3-c45";
+                reg = <4>;
+                enet-phy-pair-order = <1>;
+                enet-phy-pair-polarity = <0x1>;
+            };
         };
     };
-- 
2.55.0