Add dtschema for the MDIO controller found in the RTL9300 SoCs. The
controller is slightly unusual in that direct MDIO communication is not
possible. Instead, the SMI bus and PHY address are associated with a
switch port and the port number is used when talking to the PHY.

Signed-off-by: Chris Packham <chris.packham@alliedtelesis.co.nz>
---

Notes:
    Changes in v2:
    - None

 .../bindings/net/realtek,rtl9301-mdio.yaml    | 82 +++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/net/realtek,rtl9301-mdio.yaml

diff --git a/Documentation/devicetree/bindings/net/realtek,rtl9301-mdio.yaml b/Documentation/devicetree/bindings/net/realtek,rtl9301-mdio.yaml
new file mode 100644
index 000000000000..95ed77ff8dcc
--- /dev/null
+++ b/Documentation/devicetree/bindings/net/realtek,rtl9301-mdio.yaml
@@ -0,0 +1,82 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/net/realtek,rtl9301-mdio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Realtek RTL9300 MDIO Controller
+
+maintainers:
+  - Chris Packham <chris.packham@alliedtelesis.co.nz>
+
+allOf:
+  - $ref: mdio.yaml#
+
+properties:
+  compatible:
+    oneOf:
+      - items:
+          - enum:
+              - realtek,rtl9302b-mdio
+              - realtek,rtl9302c-mdio
+              - realtek,rtl9303-mdio
+          - const: realtek,rtl9301-mdio
+      - const: realtek,rtl9301-mdio
+
+  '#address-cells':
+    const: 1
+
+  '#size-cells':
+    const: 0
+
+  reg:
+    maxItems: 1
+
+patternProperties:
+  '^ethernet-phy(@[a-f0-9]+)?':
+    type: object
+    $ref: ethernet-phy.yaml#
+
+    properties:
+      reg:
+        description:
+          The MDIO communication on the RTL9300 is abstracted by the switch. At
+          the software level communication uses the switch port to address the
+          PHY with the actual MDIO bus and address having been setup via the
+          realtek,smi-address property.
+
+      realtek,smi-address:
+        $ref: /schemas/types.yaml#/definitions/uint32-array
+        description: SMI interface and address for the connected PHY
+        items:
+          - description: SMI interface number associated with the port.
+          - description: SMI address of the PHY for the port.
+
+    unevaluatedProperties: false
+
+required:
+  - compatible
+  - reg
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    mdio@ca00 {
+        compatible = "realtek,rtl9301-mdio";
+        reg = <0xca00 0x200>;
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        ethernet-phy@0 {
+            compatible = "ethernet-phy-ieee802.3-c45";
+            reg = <0>;
+            realtek,smi-address = <0 1>;
+        };
+
+        ethernet-phy@8 {
+            compatible = "ethernet-phy-ieee802.3-c45";
+            reg = <8>;
+            realtek,smi-address = <1 1>;
+        };
+    };
-- 
2.47.1

On Mon, Dec 16, 2024 at 04:13:43PM +1300, Chris Packham wrote:
> Add dtschema for the MDIO controller found in the RTL9300 SoCs. The
> controller is slightly unusual in that direct MDIO communication is not
> possible. Instead, the SMI bus and PHY address are associated with a
> switch port and the port number is used when talking to the PHY.
> 
> Signed-off-by: Chris Packham <chris.packham@alliedtelesis.co.nz>
> +      realtek,smi-address:
> +        $ref: /schemas/types.yaml#/definitions/uint32-array
> +        description: SMI interface and address for the connected PHY
> +        items:
> +          - description: SMI interface number associated with the port.
> +          - description: SMI address of the PHY for the port.


I don't really understand this property, but I also don't understand the
MDIO bus, so with that caveat
Reviewed-by: Conor Dooley <conor.dooley@microchip.com>

Cheers,
Conor.

On 17/12/2024 07:52, Conor Dooley wrote:
> On Mon, Dec 16, 2024 at 04:13:43PM +1300, Chris Packham wrote:
>> Add dtschema for the MDIO controller found in the RTL9300 SoCs. The
>> controller is slightly unusual in that direct MDIO communication is not
>> possible. Instead, the SMI bus and PHY address are associated with a
>> switch port and the port number is used when talking to the PHY.
>>
>> Signed-off-by: Chris Packham <chris.packham@alliedtelesis.co.nz>
>> +      realtek,smi-address:
>> +        $ref: /schemas/types.yaml#/definitions/uint32-array
>> +        description: SMI interface and address for the connected PHY
>> +        items:
>> +          - description: SMI interface number associated with the port.
>> +          - description: SMI address of the PHY for the port.
>
> I don't really understand this property, but I also don't understand the
> MDIO bus, so with that caveat
> Reviewed-by: Conor Dooley <conor.dooley@microchip.com>

I'll try to clarify here as it may be of relevance to other reviewers, 
if any of this should go in the commit message or the binding let me know.

The MDIO bus is used to manage one or more network PHYs. Sometimes there 
is an MDIO interface as part of a NIC controller but it's become 
increasingly common to have a the MDIO controller separated from the 
Ethernet controller, particularly when there are multiple Ethernet 
controllers in a SoC. In the device trees there is a usually a node for 
the MDIO controller and the attached PHYs are child nodes. The Ethernet 
interface has phandle property which references the attached PHY.

The RTL9300 (and similar Realtek Ethernet switches) don't directly 
expose the MDIO interface to us. There seems to be an internal PHY 
polling mechanism and the user access to the PHYs works in conjunction 
with that. So rather than being able to reference PHYs and MDIO 
interfaces directly we need to work with switch port numbers instead. 
The actual hardware MDIO bus and PHY address is captured in the 
"realtek,smi-address" property.