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

[Pandey, Radhey Shyam]

> -----Original Message-----
> From: Krzysztof Kozlowski <krzysztof.kozlowski@xxxxxxxxxx>
> Sent: Wednesday, September 21, 2022 1:14 PM
> To: Gaddam, Sarath Babu Naidu <sarath.babu.naidu.gaddam@xxxxxxx>;
> davem@xxxxxxxxxxxxx; edumazet@xxxxxxxxxx; kuba@xxxxxxxxxx;
> pabeni@xxxxxxxxxx; robh+dt@xxxxxxxxxx;
> krzysztof.kozlowski+dt@xxxxxxxxxx; linux@xxxxxxxxxxxxxxx
> Cc: netdev@xxxxxxxxxxxxxxx; devicetree@xxxxxxxxxxxxxxx; linux-arm-
> kernel@xxxxxxxxxxxxxxxxxxx; linux-kernel@xxxxxxxxxxxxxxx; Simek, Michal
> <michal.simek@xxxxxxx>; Pandey, Radhey Shyam
> <radhey.shyam.pandey@xxxxxxx>; Sarangi, Anirudha
> <anirudha.sarangi@xxxxxxx>; Katakam, Harini
> <harini.katakam@xxxxxxx>; git@xxxxxxxxxx; git (AMD-Xilinx)
> <git@xxxxxxx>
> Subject: Re: [RFC V2 PATCH 1/3] dt-bindings: net: xilinx_axienet:convert
> bindings document to yaml
> 
> 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)?

This patch itself is complete but is part of series that is not fully finished. 
It can be merged without waiting for RFC series to be accepted , will 
address the comment on it and send 1/3 as a separate PATCH.

> 
> > ---
> >  .../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

Ok sure . Will address it in next version.
> 
> > +$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.

Will address it in next version.
> 
> > +
> > +maintainers:
> > +  - Radhey Shyam Pandey <radhey.shyam.pandey@xxxxxxxxxx>
> > +
> > +properties:
> > +  compatible:
> > +    oneOf:
> 
> That's not oneOf.
> 
> > +      - items:
> 
> You do not have more than one item.

Will remove it in next version.
> 
> > +          - 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?

Ok will update it in next version.
Ethernet core interrupt is optional. If axistream-connected property is
present DMA node should contains TX/RX DMA interrupts else DMA 
interrupt resources are mentioned on ethernet node.

> 
> > +
> > +  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.

Will fix the indentation in next version.

> x
> 
> Best regards,
> Krzysztof