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

[Krzysztof Kozlowski]

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