From: Thierry Reding <treding@xxxxxxxxxx>
Convert the Synopsis/DesignWare Ethernet QOS device tree bindings from
free-form text format to json-schema.
Signed-off-by: Thierry Reding <treding@xxxxxxxxxx>
---
.../bindings/net/snps,dwc-qos-ethernet.txt | 168 ----------
.../bindings/net/snps,dwc-qos-ethernet.yaml | 308 ++++++++++++++++++
2 files changed, 308 insertions(+), 168 deletions(-)
delete mode 100644 Documentation/devicetree/bindings/net/snps,dwc-qos-ethernet.txt
create mode 100644 Documentation/devicetree/bindings/net/snps,dwc-qos-ethernet.yaml
diff --git a/Documentation/devicetree/bindings/net/snps,dwc-qos-ethernet.txt b/Documentation/devicetree/bindings/net/snps,dwc-qos-ethernet.txt
deleted file mode 100644
index ad3c6e109ce1..000000000000
--- a/Documentation/devicetree/bindings/net/snps,dwc-qos-ethernet.txt
+++ /dev/null
@@ -1,168 +0,0 @@
-* Synopsys DWC Ethernet QoS IP version 4.10 driver (GMAC)
-
-This binding is deprecated, but it continues to be supported, but new
-features should be preferably added to the stmmac binding document.
-
-This binding supports the Synopsys Designware Ethernet QoS (Quality Of Service)
-IP block. The IP supports multiple options for bus type, clocking and reset
-structure, and feature list. Consequently, a number of properties and list
-entries in properties are marked as optional, or only required in specific HW
-configurations.
-
-Required properties:
-- compatible: One of:
- - "axis,artpec6-eqos", "snps,dwc-qos-ethernet-4.10"
- Represents the IP core when integrated into the Axis ARTPEC-6 SoC.
- - "nvidia,tegra186-eqos", "snps,dwc-qos-ethernet-4.10"
- Represents the IP core when integrated into the NVIDIA Tegra186 SoC.
- - "snps,dwc-qos-ethernet-4.10"
- This combination is deprecated. It should be treated as equivalent to
- "axis,artpec6-eqos", "snps,dwc-qos-ethernet-4.10". It is supported to be
- compatible with earlier revisions of this binding.
-- reg: Address and length of the register set for the device
-- clocks: Phandle and clock specifiers for each entry in clock-names, in the
- same order. See ../clock/clock-bindings.txt.
-- clock-names: May contain any/all of the following depending on the IP
- configuration, in any order:
- - "tx"
- The EQOS transmit path clock. The HW signal name is clk_tx_i.
- In some configurations (e.g. GMII/RGMII), this clock also drives the PHY TX
- path. In other configurations, other clocks (such as tx_125, rmii) may
- drive the PHY TX path.
- - "rx"
- The EQOS receive path clock. The HW signal name is clk_rx_i.
- In some configurations (e.g. GMII/RGMII), this clock is derived from the
- PHY's RX clock output. In other configurations, other clocks (such as
- rx_125, rmii) may drive the EQOS RX path.
- In cases where the PHY clock is directly fed into the EQOS receive path
- without intervening logic, the DT need not represent this clock, since it
- is assumed to be fully under the control of the PHY device/driver. In
- cases where SoC integration adds additional logic to this path, such as a
- SW-controlled clock gate, this clock should be represented in DT.
- - "slave_bus"
- The CPU/slave-bus (CSR) interface clock. This applies to any bus type;
- APB, AHB, AXI, etc. The HW signal name is hclk_i (AHB) or clk_csr_i (other
- buses).
- - "master_bus"
- The master bus interface clock. Only required in configurations that use a
- separate clock for the master and slave bus interfaces. The HW signal name
- is hclk_i (AHB) or aclk_i (AXI).
- - "ptp_ref"
- The PTP reference clock. The HW signal name is clk_ptp_ref_i.
- - "phy_ref_clk"
- This clock is deprecated and should not be used by new compatible values.
- It is equivalent to "tx".
- - "apb_pclk"
- This clock is deprecated and should not be used by new compatible values.
- It is equivalent to "slave_bus".
-
- Note: Support for additional IP configurations may require adding the
- following clocks to this list in the future: clk_rx_125_i, clk_tx_125_i,
- clk_pmarx_0_i, clk_pmarx1_i, clk_rmii_i, clk_revmii_rx_i, clk_revmii_tx_i.
- Configurations exist where multiple similar clocks are used at once, e.g. all
- of clk_rx_125_i, clk_pmarx_0_i, clk_pmarx1_i. For this reason it is best to
- extend the binding with a separate clock-names entry for each of those RX
- clocks, rather than repurposing the existing "rx" clock-names entry as a
- generic/logical clock in a similar fashion to "master_bus" and "slave_bus".
- This will allow easy support for configurations that support multiple PHY
- interfaces using a mux, and hence need to have explicit control over
- specific RX clocks.
-
- The following compatible values require the following set of clocks:
- - "nvidia,tegra186-eqos", "snps,dwc-qos-ethernet-4.10":
- - "slave_bus"
- - "master_bus"
- - "rx"
- - "tx"
- - "ptp_ref"
- - "axis,artpec6-eqos", "snps,dwc-qos-ethernet-4.10":
- - "slave_bus"
- - "master_bus"
- - "tx"
- - "ptp_ref"
- - "snps,dwc-qos-ethernet-4.10" (deprecated):
- - "phy_ref_clk"
- - "apb_clk"
-- interrupts: Should contain the core's combined interrupt signal
-- phy-mode: See ethernet.txt file in the same directory
-- resets: Phandle and reset specifiers for each entry in reset-names, in the
- same order. See ../reset/reset.txt.
-- reset-names: May contain any/all of the following depending on the IP
- configuration, in any order:
- - "eqos". The reset to the entire module. The HW signal name is hreset_n
- (AHB) or aresetn_i (AXI).
-
- The following compatible values require the following set of resets:
- (the reset properties may be omitted if empty)
- - "nvidia,tegra186-eqos", "snps,dwc-qos-ethernet-4.10":
- - "eqos".
- - "axis,artpec6-eqos", "snps,dwc-qos-ethernet-4.10":
- - None.
- - "snps,dwc-qos-ethernet-4.10" (deprecated):
- - None.
-
-Optional properties:
-- dma-coherent: Present if dma operations are coherent
-- phy-reset-gpios: Phandle and specifier for any GPIO used to reset the PHY.
- See ../gpio/gpio.txt.
-- snps,en-lpi: If present it enables use of the AXI low-power interface
-- snps,write-requests: Number of write requests that the AXI port can issue.
- It depends on the SoC configuration.
-- snps,read-requests: Number of read requests that the AXI port can issue.
- It depends on the SoC configuration.
-- snps,burst-map: Bitmap of allowed AXI burst lengts, with the LSB
- representing 4, then 8 etc.
-- snps,txpbl: DMA Programmable burst length for the TX DMA
-- snps,rxpbl: DMA Programmable burst length for the RX DMA
-- snps,en-tx-lpi-clockgating: Enable gating of the MAC TX clock during
- TX low-power mode.
-- phy-handle: See ethernet.txt file in the same directory
-- mdio device tree subnode: When the GMAC has a phy connected to its local
- mdio, there must be device tree subnode with the following
- required properties:
- - compatible: Must be "snps,dwc-qos-ethernet-mdio".
- - #address-cells: Must be <1>.
- - #size-cells: Must be <0>.
-
- For each phy on the mdio bus, there must be a node with the following
- fields:
-
- - reg: phy id used to communicate to phy.
- - device_type: Must be "ethernet-phy".
- - fixed-mode device tree subnode: see fixed-link.txt in the same directory
-
-The MAC address will be determined using the optional properties
-defined in ethernet.txt.
-
-Examples:
-ethernet2@40010000 {
- clock-names = "phy_ref_clk", "apb_pclk";
- clocks = <&clkc 17>, <&clkc 15>;
- compatible = "snps,dwc-qos-ethernet-4.10";
- interrupt-parent = <&intc>;
- interrupts = <0x0 0x1e 0x4>;
- reg = <0x40010000 0x4000>;
- phy-handle = <&phy2>;
- phy-mode = "gmii";
- phy-reset-gpios = <&gpioctlr 43 GPIO_ACTIVE_LOW>;
-
- snps,en-tx-lpi-clockgating;
- snps,en-lpi;
- snps,write-requests = <2>;
- snps,read-requests = <16>;
- snps,burst-map = <0x7>;
- snps,txpbl = <8>;
- snps,rxpbl = <2>;
-
- dma-coherent;
-
- mdio {
- #address-cells = <0x1>;
- #size-cells = <0x0>;
- phy2: phy@1 {
- compatible = "ethernet-phy-ieee802.3-c22";
- device_type = "ethernet-phy";
- reg = <0x1>;
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/net/snps,dwc-qos-ethernet.yaml b/Documentation/devicetree/bindings/net/snps,dwc-qos-ethernet.yaml
new file mode 100644
index 000000000000..252f11affd6b
--- /dev/null
+++ b/Documentation/devicetree/bindings/net/snps,dwc-qos-ethernet.yaml
@@ -0,0 +1,308 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/net/snps,dwc-qos-ethernet.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Synopsys DWC Ethernet QoS IP version 4.10 driver (GMAC)
+
+maintainers:
+ - Thierry Reding <thierry.reding@xxxxxxxxx>
+ - Alexandre Torgue <alexandre.torgue@xxxxxx>
+ - Giuseppe Cavallaro <peppe.cavallaro@xxxxxx>
+ - Jose Abreu <joabreu@xxxxxxxxxxxx>
+
+description: |
+ This binding is deprecated, but it continues to be supported, but new
+ features should be preferably added to the stmmac binding document.
+
+ This binding supports the Synopsys Designware Ethernet QoS (Quality Of
+ Service) IP block. The IP supports multiple options for bus type, clocking
+ and reset structure, and feature list. Consequently, a number of properties
+ and list entries in properties are marked as optional, or only required in
+ specific HW configurations.
+
+properties:
+ compatible:
+ oneOf:
+ - description: Represents the IP core when integrated into the Axis
+ ARTPEC-6 SoC.
+ items:
+ - const: axis,artpec6-eqos
+ - const: snps,dwc-qos-ethernet-4.10
+
+ - description: Represents the IP core when integrated into the NVIDIA
+ Tegra186 SoC.
+ items:
+ - const: nvidia,tegra186-eqos
+ - const: snps,dwc-qos-ethernet-4.10
+
+ - description: Represents the IP core when integrated into the NVIDIA
+ Tegra194 SoC.
+ items:
+ - const: nvidia,tegra194-eqos
+ - const: nvidia,tegra186-eqos
+ - const: snps,dwc-qos-ethernet-4.10
+
+ - description: This combination is deprecated. It should be treated as
+ equivalent to "axis,artpec6-eqos", "snps,dwc-qos-ethernet-4.10". It
+ is supported to be compatible with earlier revisions of this binding.
+ items:
+ - const: snps,dwc-qos-ethernet-4.10
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ description: |
+ A phandle and specifier pair for each entry in the clock-names property.
+
+ Note: Support for additional IP configurations may require adding the
+ following clocks to this list in the future: clk_rx_125_i, clk_tx_125_i,
+ clk_pmarx_0_i, clk_pmarx1_i, clk_rmii_i, clk_revmii_rx_i,
+ clk_revmii_tx_i. Configurations exist where multiple similar clocks are
+ used at once, e.g. all of clk_rx_125_i, clk_pmarx_0_i, clk_pmarx1_i. For
+ this reason it is best to extend the binding with a separate clock-names
+ entry for each of those RX clocks, rather than repurposing the existing
+ "rx" clock-names entry as a generic/logical clock in a similar fashion
+ to "master_bus" and "slave_bus". This will allow easy support for
+ configurations that support multiple PHY interfaces using a mux, and
+ hence need to have explicit control over specific RX clocks.
+
+ interrupts:
+ description: Should contain the core's combined interrupt signal.
+
+ resets:
+ description: A phandle and reset specifier for each entry in reset-names,
+ in the same order.
+
+ reset-names:
+ description: A list of names corresponding to each entry in the resets
+ property.
+
+ dma-coherent:
+ description: Present if DMA operations are coherent.
+ $ref: "/schemas/types.yaml#/definitions/flag"
+
+ iommus:
+ $ref: "/schemas/types.yaml#/definitions/phandle-array"
+
+ phy-reset-gpios:
+ description: A list of phandle and specifier for any GPIO used to reset
+ the PHY. See ../gpio/gpio.txt.
+ $ref: "/schemas/types.yaml#/definitions/phandle-array"
+
+ snps,en-lpi:
+ description: If present it enables use of the AXI low-power interface.
+ $ref: "/schemas/types.yaml#/definitions/flag"
+
+ snps,write-requests:
+ description: Number of write requests that the AXI port can issue. It
+ depends on the SoC configuration.
+ $ref: "/schemas/types.yaml#/definitions/uint32"
+
+ snps,read-requests:
+ description: Number of read requests that the AXI port can issue. It
+ depends on the SoC configuration.
+ $ref: "/schemas/types.yaml#/definitions/uint32"
+
+ snps,burst-map:
+ description: Bitmap of allowed AXI burst lengts, with the LSB representing
+ 4, then 8 etc.
+ $ref: "/schemas/types.yaml#/definitions/uint32"
+
+ snps,txpbl:
+ description: DMA Programmable burst length for the TX DMA.
+ $ref: "/schemas/types.yaml#/definitions/uint32"
+
+ snps,rxpbl:
+ description: DMA Programmable burst length for the RX DMA.
+ $ref: "/schemas/types.yaml#/definitions/uint32"
+
+ snps,en-tx-lpi-clockgating:
+ description: Enable gating of the MAC TX clock during TX low-power mode.
+ $ref: "/schemas/types.yaml#/definitions/flag"
+
+ mdio:
+ description: A subnode representing the GMAC's MDIO bus.
+ type: object
+
+ properties:
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ patternProperties:
+ "^phy@[0-9a-f]+$":
+ $ref: "ethernet-phy.yaml"
+ description: Each PHY on the MDIO bus is represented by one of these
+ nodes.
+
+ required:
+ - "#address-cells"
+ - "#size-cells"
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - interrupts
+ - phy-mode
+
+allOf:
+ - $ref: "ethernet-controller.yaml"
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: nvidia,tegra186-eqos
+ then:
+ properties:
+ reset-names:
+ items:
+ - description: The reset to the entire module. The HW signal name
+ is hreset_n (AHB) or aresetn_i (AXI).
+ const: eqos
+
+ clocks:
+ items:
+ - description: The master bus interface clock. Only required in
+ configurations that use a separate clock for the master and
+ slave bus interfaces. The HW signal name is hclk_i (AHB) or
+ aclk_i (AXI).
+
+ - description: The CPU/slave-bus (CSR) interface clock. This
+ applies to any bus type; APB, AHB, AXI, etc. The HW signal
+ name is hclk_i (AHB) or clk_csr_i (other buses).
+
+ - description: The EQOS receive path clock. The HW signal name is
+ clk_rx_i. In some configurations (e.g. GMII/RGMII), this clock
+ is derived from the PHY's RX clock output. In other
+ configurations, other clocks (such as rx_125, rmii) may drive
+ the EQOS RX path. In cases where the PHY clock is directly fed
+ into the EQOS receive path without intervening logic, the DT
+ need not represent this clock, since it is assumed to be fully
+ under the control of the PHY device or driver. In cases where
+ SoC integration adds additional logic to this path, such as a
+ SW-controlled clock gate, this clock should be represented in
+ DT.
+
+ - description: The EQOS transmit path clock. The HW signal name is
+ clk_tx_i. In some configurations (e.g. GMII/RGMII), this clock
+ also drives the PHY TX path. In other configurations, other
+ clocks (such as tx_125, rmii) may drive the PHY TX path.
+
+ - description: The PTP reference clock. The HW signal name is
+ clk_ptp_ref_i.
+
+ clock-names:
+ items:
+ - const: master_bus
+ - const: slave_bus
+ - const: rx
+ - const: tx
+ - const: ptp_ref
+
+ required:
+ - resets
+ - reset-names
+
+ - if:
+ properties:
+ compatible:
+ allOf:
+ - const: axis,artpec6-eqos
+ - const: snps,dwc-qos-ethernet-4.10
+ then:
+ properties:
+ clocks:
+ items:
+ - description: The CPU/slave-bus (CSR) interface clock. This
+ applies to any bus type; APB, AHB, AXI, etc. The HW signal
+ name is hclk_i (AHB) or clk_csr_i (other buses).
+
+ - description: The master bus interface clock. Only required in
+ configurations that use a separate clock for the master and
+ slave bus interfaces. The HW signal name is hclk_i (AHB) or
+ aclk_i (AXI).
+
+ - description: The EQOS transmit path clock. The HW signal name is
+ clk_tx_i. In some configurations (e.g. GMII/RGMII), this clock
+ also drives the PHY TX path. In other configurations, other
+ clocks (such as tx_125, rmii) may drive the PHY TX path.
+
+ - description: The PTP reference clock. The HW signal name is
+ clk_ptp_ref_i.
+
+ clock-names:
+ items:
+ - const: slave_bus
+ - const: master_bus
+ - const: tx
+ - const: ptp_ref
+
+ - if:
+ properties:
+ compatible:
+ const: snps,dwc-qos-ethernet-4.10
+ then:
+ properties:
+ clocks:
+ items:
+ - description: The EQOS transmit path clock. The HW signal name is
+ clk_tx_i. In some configurations (e.g. GMII/RGMII), this clock
+ also drives the PHY TX path. In other configurations, other
+ clocks (such as tx_125, rmii) may drive the PHY TX path.
+
+ - description: The CPU/slave-bus (CSR) interface clock. This
+ applies to any bus type; APB, AHB, AXI, etc. The HW signal
+ name is hclk_i (AHB) or clk_csr_i (other buses).
+
+ clock-names:
+ items:
+ - const: phy_ref_clk
+ - const: apb_pclk
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ ethernet@40010000 {
+ clock-names = "phy_ref_clk", "apb_pclk";
+ clocks = <&clkc 17>, <&clkc 15>;
+ compatible = "snps,dwc-qos-ethernet-4.10";
+ interrupt-parent = <&intc>;
+ interrupts = <0x0 0x1e 0x4>;
+ reg = <0x40010000 0x4000>;
+ phy-handle = <&phy2>;
+ phy-mode = "gmii";
+ phy-reset-gpios = <&gpioctlr 43 GPIO_ACTIVE_LOW>;
+
+ snps,en-tx-lpi-clockgating;
+ snps,en-lpi;
+ snps,write-requests = <2>;
+ snps,read-requests = <16>;
+ snps,burst-map = <0x7>;
+ snps,txpbl = <8>;
+ snps,rxpbl = <2>;
+
+ dma-coherent;
+
+ mdio {
+ #address-cells = <0x1>;
+ #size-cells = <0x0>;
+ phy2: phy@1 {
+ compatible = "ethernet-phy-ieee802.3-c22";
+ device_type = "ethernet-phy";
+ #phy-cells = <0>;
+ reg = <0x1>;
+ };
+ };
+ };
--
2.24.1
