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

From: Pandey, Radhey Shyam
Date: Wed Sep 21 2022 - 05:43:24 EST


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