[PATCH net-next v5 2/6] dt-bindings: net: xlnx,xxv-ethernet: Add Xilinx XXV 10G/25G Ethernet

[Suraj Gupta <suraj.gupta2@amd.com>]

The XXV Ethernet IP integrates a 10G/25G Ethernet MAC with an in-core
PCS/PMA driving a high-speed serial transceiver. Its payload is moved by
an external AXI DMA (or multichannel DMA) controller referenced through
the dmas/dma-names properties. Document the IP in a dedicated schema
file.

Add the "xlnx,xxv-ethernet-1.0" compatible with the 10gbase-r and
25gbase-r phy-modes, the rx_core/drp/s_axi clocks and the AXI DMA
channel properties. The GT transceiver reference clock is described as
an optional fourth "ref" clock, for boards where it is supplied by a
Linux-managed clock provider rather than a fixed oscillator.

Add "xlnx,has-statistics-counters" as well. The statistics counters are
an optional part of the IP, selected by the "Include Statistics Counters"
build option (PG210), and unlike the 1G MAC the subsystem has no ability
register that reports whether they were included, so the devicetree has
to describe it.

Require "xlnx,rxmem". The driver reads it unconditionally at probe time
and fails if it is absent, and the value is what bounds the largest frame
the device accepts, both when validating a new MTU and when deciding
whether jumbo frames can be enabled.

Disallow phy-handle, its deprecated phy and phy-device spellings, and
pcs-handle. All are inherited from ethernet-controller.yaml, so
unevaluatedProperties does not reject them, but the subsystem has no MDIO
bus master and its PCS is in-core, so neither an external PHY nor an
external PCS can be attached. Constrain managed to in-band-status for the
same reason; it stays optional, as the link is always managed in-band.

Signed-off-by: Suraj Gupta <suraj.gupta2@amd.com>
---
 .../bindings/net/xlnx,xxv-ethernet.yaml       | 146 ++++++++++++++++++
 MAINTAINERS                                   |   1 +
 2 files changed, 147 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/net/xlnx,xxv-ethernet.yaml

diff --git a/Documentation/devicetree/bindings/net/xlnx,xxv-ethernet.yaml b/Documentation/devicetree/bindings/net/xlnx,xxv-ethernet.yaml
new file mode 100644
index 000000000000..caf582c72a8d
--- /dev/null
+++ b/Documentation/devicetree/bindings/net/xlnx,xxv-ethernet.yaml
@@ -0,0 +1,146 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/net/xlnx,xxv-ethernet.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Xilinx XXV 10G/25G Ethernet Subsystem
+
+maintainers:
+  - Radhey Shyam Pandey <radhey.shyam.pandey@amd.com>
+  - Suraj Gupta <suraj.gupta2@amd.com>
+
+description:
+  The Xilinx XXV Ethernet Subsystem implements a 10G/25G Ethernet MAC with an
+  in-core PCS/PMA driving a high-speed serial transceiver. It supports the
+  10GBASE-R and 25GBASE-R line rates, with 25G operation following the 25G
+  Ethernet Consortium specification. Because the PCS/PMA is integrated into
+  the IP, the subsystem has no MDIO bus master and is not managed through an
+  external MDIO PHY; link state is read from the MAC's own status registers.
+  As there is no PHY to manage, the link is always managed in-band.
+  Any SFP module management (e.g. I2C) is handled by separate IP outside this
+  binding. Its payload is moved by an external AXI DMA (or multichannel DMA)
+  controller referenced through the "dmas" property.
+
+properties:
+  compatible:
+    const: xlnx,xxv-ethernet-1.0
+
+  reg:
+    maxItems: 1
+    description: MAC control and status register space.
+
+  clocks:
+    minItems: 3
+    items:
+      - description: RX AXI4-Stream clock.
+      - description: GT helper (dclk) stable clock.
+      - description: AXI4-Lite register clock.
+      - description: GT transceiver reference clock (refclk).
+
+  clock-names:
+    minItems: 3
+    items:
+      - const: rx_core
+      - const: drp
+      - const: s_axi
+      - const: ref
+
+  phy-mode:
+    enum:
+      - 10gbase-r
+      - 25gbase-r
+
+  # The subsystem has no MDIO bus master and its PCS is in-core, so neither
+  # an external PHY nor an external PCS can be attached. phy and phy-device
+  # are the deprecated spellings of phy-handle.
+  phy-handle: false
+  phy: false
+  phy-device: false
+  pcs-handle: false
+
+  managed:
+    const: in-band-status
+
+  xlnx,rxmem:
+    description:
+      Size in bytes of the Rx/Tx packet buffer memory built into the IP. It is
+      fixed by the hardware design and bounds the largest frame (jumbo MTU) the
+      device can accept.
+    $ref: /schemas/types.yaml#/definitions/uint32
+
+  xlnx,has-statistics-counters:
+    description:
+      The statistics counters are an optional part of the IP, selected by the
+      "Include Statistics Counters" build option, and the subsystem does not
+      advertise whether they were included. Present when the design was built
+      with them, in which case the driver reports the MAC counters through
+      ethtool and ndo_get_stats64.
+    type: boolean
+
+  dmas:
+    minItems: 2
+    maxItems: 32
+    description:
+      TX and RX DMA channel phandles, one per entry in "dma-names".
+
+  dma-names:
+    minItems: 2
+    maxItems: 32
+    items:
+      pattern: "^[tr]x_chan([0-9]|1[0-5])$"
+    allOf:
+      - contains:
+          const: tx_chan0
+      - contains:
+          const: rx_chan0
+    description:
+      Should be "tx_chan0", "tx_chan1" ... "tx_chan15" for DMA Tx channel and
+      "rx_chan0", "rx_chan1" ... "rx_chan15" for DMA Rx channel. The first
+      Tx/Rx channel pair ("tx_chan0" and "rx_chan0") is always required. There
+      is one name per entry in "dmas", in the same order.
+
+required:
+  - compatible
+  - reg
+  - clocks
+  - clock-names
+  - phy-mode
+  - xlnx,rxmem
+  - dmas
+  - dma-names
+
+allOf:
+  - $ref: /schemas/net/ethernet-controller.yaml#
+
+unevaluatedProperties: false
+
+examples:
+  # Single AXI DMA channel pair
+  - |
+    ethernet@80000000 {
+        compatible = "xlnx,xxv-ethernet-1.0";
+        reg = <0x80000000 0x10000>;
+        clock-names = "rx_core", "drp", "s_axi";
+        clocks = <&rx_clk>, <&drp_clk>, <&axi_clk>;
+        dma-names = "tx_chan0", "rx_chan0";
+        dmas = <&axi_dma 0>, <&axi_dma 1>;
+        phy-mode = "25gbase-r";
+        managed = "in-band-status";
+        xlnx,rxmem = <0x8000>;
+        xlnx,has-statistics-counters;
+    };
+  # Multichannel DMA (MCDMA) with multiple Tx/Rx channels
+  - |
+    ethernet@80010000 {
+        compatible = "xlnx,xxv-ethernet-1.0";
+        reg = <0x80010000 0x10000>;
+        clock-names = "rx_core", "drp", "s_axi";
+        clocks = <&rx_clk>, <&drp_clk>, <&axi_clk>;
+        dma-names = "tx_chan0", "tx_chan1", "rx_chan0", "rx_chan1";
+        dmas = <&axi_mcdma 0>, <&axi_mcdma 1>,
+               <&axi_mcdma 16>, <&axi_mcdma 17>;
+        phy-mode = "10gbase-r";
+        managed = "in-band-status";
+        xlnx,rxmem = <0x8000>;
+    };
diff --git a/MAINTAINERS b/MAINTAINERS
index 893b0670a7b6..b33fd70d242f 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -30683,6 +30683,7 @@ XILINX AXI ETHERNET DRIVER
 M:	Radhey Shyam Pandey <radhey.shyam.pandey@amd.com>
 S:	Maintained
 F:	Documentation/devicetree/bindings/net/xlnx,axi-ethernet.yaml
+F:	Documentation/devicetree/bindings/net/xlnx,xxv-ethernet.yaml
 F:	drivers/net/ethernet/xilinx/xilinx_axienet*
 
 XILINX CAN DRIVER
-- 
2.25.1