RE: [PATCH net-next V3] dt-bindings: net: xlnx,axi-ethernet: convert bindings document to yaml

[Gaddam, Sarath Babu Naidu]

> -----Original Message-----
> From: Krzysztof Kozlowski <krzysztof.kozlowski@xxxxxxxxxx>
> Sent: Tuesday, November 22, 2022 4:41 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
> Cc: michal.simek@xxxxxxxxxx; radhey.shyam.pandey@xxxxxxxxxx;
> netdev@xxxxxxxxxxxxxxx; devicetree@xxxxxxxxxxxxxxx; linux-arm-
> kernel@xxxxxxxxxxxxxxxxxxx; linux-kernel@xxxxxxxxxxxxxxx; Sarangi,
> Anirudha <anirudha.sarangi@xxxxxxx>; Katakam, Harini
> <harini.katakam@xxxxxxx>; git (AMD-Xilinx) <git@xxxxxxx>
> Subject: Re: [PATCH net-next V3] dt-bindings: net: xlnx,axi-ethernet:
> convert bindings document to yaml
> 
> On 22/11/2022 11:24, 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 V3:
> > 1) Moved RFC to PATCH.
> > 2) Addressed below review comments
> > 	a) Indentation.
> > 	b) maxItems:3 does not match your description.
> > 	c) Filename matching compatibles.
> >
> > 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).
> > ---
> >  .../bindings/net/xilinx_axienet.txt           |  99 ------------
> >  .../bindings/net/xlnx,axi-ethernet.yaml       | 150 ++++++++++++++++++
> >  MAINTAINERS                                   |   1 +
> >  3 files changed, 151 insertions(+), 99 deletions(-)  delete mode
> > 100644 Documentation/devicetree/bindings/net/xilinx_axienet.txt
> >  create mode 100644
> > Documentation/devicetree/bindings/net/xlnx,axi-ethernet.yaml
> >
> > diff --git a/Documentation/devicetree/bindings/net/xilinx_axienet.txt
> > b/Documentation/devicetree/bindings/net/xilinx_axienet.txt
> > deleted file mode 100644
> > index 1aa4c6006cd0..000000000000
> > --- 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,axi-ethernet.yaml
> > b/Documentation/devicetree/bindings/net/xlnx,axi-ethernet.yaml
> > new file mode 100644
> > index 000000000000..5dc41ab7584b
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/net/xlnx,axi-ethernet.yaml
> > @@ -0,0 +1,150 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/net/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#
> > +
> > +maintainers:
> > +  - Radhey Shyam Pandey <radhey.shyam.pandey@xxxxxxxxxx>
> > +
> > +properties:
> > +  compatible:
> > +    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:
> > +      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.
> > +    maxItems: 3
> 
> This does not fully match the old bindings and you did not mention in
> commit msg any changes during conversion. IOW, old binding allowed
> only core interrupt. You do not allow it. Was this your intention?
> 
> This affects both reg and interrupts which otherwise should have
> allOf:if:then constraints.
> 
Thanks for review comments. No, we did not intent to change
 the bindings. There is some format confusion from txt to yaml.
 Will fix and send next version.

Thanks,
Sarath

<<attachment: winmail.dat>>