Re: [RFC V2 PATCH 1/3] dt-bindings: net: xilinx_axienet:convert bindings document to yaml

From: Krzysztof Kozlowski
Date: Wed Sep 21 2022 - 03:43:57 EST


On 20/09/2022 07:57, Sarath Babu Naidu Gaddam wrote:
> From: Radhey Shyam Pandey <radhey.shyam.pandey@xxxxxxxxxx>
>
> Convert the bindings document for Xilinx AXI Ethernet Subsystem
> from txt to yaml. No changes to existing binding description.
>
> Signed-off-by: Radhey Shyam Pandey <radhey.shyam.pandey@xxxxxxxxxx>
> Signed-off-by: Sarath Babu Naidu Gaddam <sarath.babu.naidu.gaddam@xxxxxxx>
> ---
> Changes in V2:
> 1) remove .txt and change the name of file to xlnx,axiethernet.yaml.
> 2) Fix DT check warning('device_type' does not match any of the regexes:
> 'pinctrl-[0-9]+' From schema: Documentation/devicetree/bindings/net
> /xilinx_axienet.yaml).

Why this is RFC? This would mean you do not expect full review (e.g. it
is not finished, not ready)?

> ---
> .../devicetree/bindings/net/xilinx_axienet.txt | 99 -------------
> .../devicetree/bindings/net/xlnx,axiethernet.yaml | 152 ++++++++++++++++++++
> MAINTAINERS | 1 +
> 3 files changed, 153 insertions(+), 99 deletions(-)
> delete mode 100644 Documentation/devicetree/bindings/net/xilinx_axienet.txt
> create mode 100644 Documentation/devicetree/bindings/net/xlnx,axiethernet.yaml
>
> diff --git a/Documentation/devicetree/bindings/net/xilinx_axienet.txt b/Documentation/devicetree/bindings/net/xilinx_axienet.txt
> deleted file mode 100644
> index 1aa4c60..0000000
> --- a/Documentation/devicetree/bindings/net/xilinx_axienet.txt
> +++ /dev/null
> @@ -1,99 +0,0 @@
> -XILINX AXI ETHERNET Device Tree Bindings
> ---------------------------------------------------------
> -
> -Also called AXI 1G/2.5G Ethernet Subsystem, the xilinx axi ethernet IP core
> -provides connectivity to an external ethernet PHY supporting different
> -interfaces: MII, GMII, RGMII, SGMII, 1000BaseX. It also includes two
> -segments of memory for buffering TX and RX, as well as the capability of
> -offloading TX/RX checksum calculation off the processor.
> -
> -Management configuration is done through the AXI interface, while payload is
> -sent and received through means of an AXI DMA controller. This driver
> -includes the DMA driver code, so this driver is incompatible with AXI DMA
> -driver.
> -
> -For more details about mdio please refer phy.txt file in the same directory.
> -
> -Required properties:
> -- compatible : Must be one of "xlnx,axi-ethernet-1.00.a",
> - "xlnx,axi-ethernet-1.01.a", "xlnx,axi-ethernet-2.01.a"
> -- reg : Address and length of the IO space, as well as the address
> - and length of the AXI DMA controller IO space, unless
> - axistream-connected is specified, in which case the reg
> - attribute of the node referenced by it is used.
> -- interrupts : Should be a list of 2 or 3 interrupts: TX DMA, RX DMA,
> - and optionally Ethernet core. If axistream-connected is
> - specified, the TX/RX DMA interrupts should be on that node
> - instead, and only the Ethernet core interrupt is optionally
> - specified here.
> -- phy-handle : Should point to the external phy device if exists. Pointing
> - this to the PCS/PMA PHY is deprecated and should be avoided.
> - See ethernet.txt file in the same directory.
> -- xlnx,rxmem : Set to allocated memory buffer for Rx/Tx in the hardware
> -
> -Optional properties:
> -- phy-mode : See ethernet.txt
> -- xlnx,phy-type : Deprecated, do not use, but still accepted in preference
> - to phy-mode.
> -- xlnx,txcsum : 0 or empty for disabling TX checksum offload,
> - 1 to enable partial TX checksum offload,
> - 2 to enable full TX checksum offload
> -- xlnx,rxcsum : Same values as xlnx,txcsum but for RX checksum offload
> -- xlnx,switch-x-sgmii : Boolean to indicate the Ethernet core is configured to
> - support both 1000BaseX and SGMII modes. If set, the phy-mode
> - should be set to match the mode selected on core reset (i.e.
> - by the basex_or_sgmii core input line).
> -- clock-names: Tuple listing input clock names. Possible clocks:
> - s_axi_lite_clk: Clock for AXI register slave interface
> - axis_clk: AXI4-Stream clock for TXD RXD TXC and RXS interfaces
> - ref_clk: Ethernet reference clock, used by signal delay
> - primitives and transceivers
> - mgt_clk: MGT reference clock (used by optional internal
> - PCS/PMA PHY)
> -
> - Note that if s_axi_lite_clk is not specified by name, the
> - first clock of any name is used for this. If that is also not
> - specified, the clock rate is auto-detected from the CPU clock
> - (but only on platforms where this is possible). New device
> - trees should specify all applicable clocks by name - the
> - fallbacks to an unnamed clock or to CPU clock are only for
> - backward compatibility.
> -- clocks: Phandles to input clocks matching clock-names. Refer to common
> - clock bindings.
> -- axistream-connected: Reference to another node which contains the resources
> - for the AXI DMA controller used by this device.
> - If this is specified, the DMA-related resources from that
> - device (DMA registers and DMA TX/RX interrupts) rather
> - than this one will be used.
> - - mdio : Child node for MDIO bus. Must be defined if PHY access is
> - required through the core's MDIO interface (i.e. always,
> - unless the PHY is accessed through a different bus).
> -
> - - pcs-handle: Phandle to the internal PCS/PMA PHY in SGMII or 1000Base-X
> - modes, where "pcs-handle" should be used to point
> - to the PCS/PMA PHY, and "phy-handle" should point to an
> - external PHY if exists.
> -
> -Example:
> - axi_ethernet_eth: ethernet@40c00000 {
> - compatible = "xlnx,axi-ethernet-1.00.a";
> - device_type = "network";
> - interrupt-parent = <&microblaze_0_axi_intc>;
> - interrupts = <2 0 1>;
> - clock-names = "s_axi_lite_clk", "axis_clk", "ref_clk", "mgt_clk";
> - clocks = <&axi_clk>, <&axi_clk>, <&pl_enet_ref_clk>, <&mgt_clk>;
> - phy-mode = "mii";
> - reg = <0x40c00000 0x40000 0x50c00000 0x40000>;
> - xlnx,rxcsum = <0x2>;
> - xlnx,rxmem = <0x800>;
> - xlnx,txcsum = <0x2>;
> - phy-handle = <&phy0>;
> - axi_ethernetlite_0_mdio: mdio {
> - #address-cells = <1>;
> - #size-cells = <0>;
> - phy0: phy@0 {
> - device_type = "ethernet-phy";
> - reg = <1>;
> - };
> - };
> - };
> diff --git a/Documentation/devicetree/bindings/net/xlnx,axiethernet.yaml b/Documentation/devicetree/bindings/net/xlnx,axiethernet.yaml
> new file mode 100644
> index 0000000..780edf3
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/net/xlnx,axiethernet.yaml
> @@ -0,0 +1,152 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/net/xlnx,axiethernet.yaml#

Filename matching compatibles, at least their common part:
xlnx,axi-ethernet.yaml

> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: AXI 1G/2.5G Ethernet Subsystem
> +
> +description: |
> + Also called AXI 1G/2.5G Ethernet Subsystem, the xilinx axi ethernet IP core
> + provides connectivity to an external ethernet PHY supporting different
> + interfaces: MII, GMII, RGMII, SGMII, 1000BaseX. It also includes two
> + segments of memory for buffering TX and RX, as well as the capability of
> + offloading TX/RX checksum calculation off the processor.
> +
> + Management configuration is done through the AXI interface, while payload is
> + sent and received through means of an AXI DMA controller. This driver
> + includes the DMA driver code, so this driver is incompatible with AXI DMA
> + driver.
> +
> +
> +allOf:
> + - $ref: "ethernet-controller.yaml#"

Drop quotes.

> +
> +maintainers:
> + - Radhey Shyam Pandey <radhey.shyam.pandey@xxxxxxxxxx>
> +
> +properties:
> + compatible:
> + oneOf:

That's not oneOf.

> + - items:

You do not have more than one item.

> + - enum:
> + - xlnx,axi-ethernet-1.00.a
> + - xlnx,axi-ethernet-1.01.a
> + - xlnx,axi-ethernet-2.01.a
> +
> + reg:
> + description:
> + Address and length of the IO space, as well as the address
> + and length of the AXI DMA controller IO space, unless
> + axistream-connected is specified, in which case the reg
> + attribute of the node referenced by it is used.
> + maxItems: 2
> +
> + interrupts:
> + description:
> + Can point to at most 3 interrupts. TX DMA, RX DMA, and optionally Ethernet
> + core. If axistream-connected is specified, the TX/RX DMA interrupts should
> + be on that node instead, and only the Ethernet core interrupt is optionally
> + specified here.
> + maxItems: 3

maxItems:3 does not match your description. Maybe description needs to
be updated?

> +
> + phy-handle: true
> +
> + xlnx,rxmem:
> + description:
> + Set to allocated memory buffer for Rx/Tx in the hardware.
> + $ref: /schemas/types.yaml#/definitions/uint32
> +
> + phy-mode: true
> +
> + xlnx,phy-type:
> + description:
> + Do not use, but still accepted in preference to phy-mode.
> + deprecated: true
> + $ref: /schemas/types.yaml#/definitions/uint32
> +
> + xlnx,txcsum:
> + description:
> + TX checksum offload. 0 or empty for disabling TX checksum offload,
> + 1 to enable partial TX checksum offload and 2 to enable full TX
> + checksum offload.
> + $ref: /schemas/types.yaml#/definitions/uint32
> + enum: [0, 1, 2]
> +
> + xlnx,rxcsum:
> + description:
> + RX checksum offload. 0 or empty for disabling RX checksum offload,
> + 1 to enable partial RX checksum offload and 2 to enable full RX
> + checksum offload.
> + $ref: /schemas/types.yaml#/definitions/uint32
> + enum: [0, 1, 2]
> +
> + xlnx,switch-x-sgmii:
> + type: boolean
> + description:
> + Indicate the Ethernet core is configured to support both 1000BaseX and
> + SGMII modes. If set, the phy-mode should be set to match the mode
> + selected on core reset (i.e. by the basex_or_sgmii core input line).
> +
> + clocks:
> + items:
> + - description: Clock for AXI register slave interface.
> + - description: AXI4-Stream clock for TXD RXD TXC and RXS interfaces.
> + - description: Ethernet reference clock, used by signal delay primitives
> + and transceivers.
> + - description: MGT reference clock (used by optional internal PCS/PMA PHY)
> +
> + clock-names:
> + items:
> + - const: s_axi_lite_clk
> + - const: axis_clk
> + - const: ref_clk
> + - const: mgt_clk
> +
> + axistream-connected:
> + type: object
> + description: Reference to another node which contains the resources
> + for the AXI DMA controller used by this device. If this is specified,
> + the DMA-related resources from that device (DMA registers and DMA
> + TX/RX interrupts) rather than this one will be used.
> +
> + mdio: true
> +
> + pcs-handle:
> + description: Phandle to the internal PCS/PMA PHY in SGMII or 1000Base-X
> + modes, where "pcs-handle" should be used to point to the PCS/PMA PHY,
> + and "phy-handle" should point to an external PHY if exists.
> + $ref: /schemas/types.yaml#/definitions/phandle
> +
> +required:
> + - compatible
> + - interrupts
> + - reg
> + - xlnx,rxmem
> + - phy-handle
> +
> +additionalProperties: false
> +
> +examples:
> + - |
> + axi_ethernet_eth: ethernet@40c00000 {
> + compatible = "xlnx,axi-ethernet-1.00.a";
> + interrupt-parent = <&microblaze_0_axi_intc>;
> + interrupts = <2>, <0>, <1>;
> + clock-names = "s_axi_lite_clk", "axis_clk", "ref_clk", "mgt_clk";
> + clocks = <&axi_clk>, <&axi_clk>, <&pl_enet_ref_clk>, <&mgt_clk>;
> + phy-mode = "mii";
> + reg = <0x40c00000 0x40000>,<0x50c00000 0x40000>;
> + xlnx,rxcsum = <0x2>;
> + xlnx,rxmem = <0x800>;
> + xlnx,txcsum = <0x2>;
> + phy-handle = <&phy0>;
> + axi_ethernetlite_0_mdio: mdio {
> + #address-cells = <1>;
> + #size-cells = <0>;
> + phy0: ethernet-phy@1 {
> + device_type = "ethernet-phy";
> + reg = <1>;
> + };

Messed up indentation.
x

Best regards,
Krzysztof