[PATCH v2] dt-bindings: misc: xlnx,sd-fec: convert bindings to yaml

[PATCH v2] dt-bindings: misc: xlnx,sd-fec: convert bindings to yaml

[Dragan Cvetic]

Convert AMD (Xilinx) sd-fec bindings to yaml format, so it can validate
dt-entries as well as any future additions to yaml.
Change in clocks is due to IP is itself configurable and
only the first two clocks are in all combinations. The last
6 clocks can be present in some of them. It means order is
not really fixed and any combination is possible.
Interrupt may or may not be present.
The documentation for sd-fec bindings is now YAML, so update the
MAINTAINERS file.
Update the link to the new yaml file in xilinx_sdfec.rst.

Signed-off-by: Dragan Cvetic <dragan.cvetic@amd.com>
---
Changes in v2:
---
Drop clocks description.
Use "contains:" with enum for optional clock-names and update
comment explaining diference from the original DT binding file.
Remove trailing full stops.
Add more details in sdfec-code description.
Set sdfec-code to "string" not "string-array"
---
 .../devicetree/bindings/misc/xlnx,sd-fec.txt  |  58 --------
 .../devicetree/bindings/misc/xlnx,sd-fec.yaml | 136 ++++++++++++++++++
 Documentation/misc-devices/xilinx_sdfec.rst   |   2 +-
 MAINTAINERS                                   |   2 +-
 4 files changed, 138 insertions(+), 60 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/misc/xlnx,sd-fec.txt
 create mode 100644 Documentation/devicetree/bindings/misc/xlnx,sd-fec.yaml

diff --git a/Documentation/devicetree/bindings/misc/xlnx,sd-fec.txt b/Documentation/devicetree/bindings/misc/xlnx,sd-fec.txt
deleted file mode 100644
index e3289634fa30..000000000000
--- a/Documentation/devicetree/bindings/misc/xlnx,sd-fec.txt
+++ /dev/null
@@ -1,58 +0,0 @@
-* Xilinx SDFEC(16nm) IP *
-
-The Soft Decision Forward Error Correction (SDFEC) Engine is a Hard IP block
-which provides high-throughput LDPC and Turbo Code implementations.
-The LDPC decode & encode functionality is capable of covering a range of
-customer specified Quasi-cyclic (QC) codes. The Turbo decode functionality
-principally covers codes used by LTE. The FEC Engine offers significant
-power and area savings versus implementations done in the FPGA fabric.
-
-
-Required properties:
-- compatible: Must be "xlnx,sd-fec-1.1"
-- clock-names : List of input clock names from the following:
-    - "core_clk", Main processing clock for processing core (required)
-    - "s_axi_aclk", AXI4-Lite memory-mapped slave interface clock (required)
-    - "s_axis_din_aclk", DIN AXI4-Stream Slave interface clock (optional)
-    - "s_axis_din_words-aclk", DIN_WORDS AXI4-Stream Slave interface clock (optional)
-    - "s_axis_ctrl_aclk",  Control input AXI4-Stream Slave interface clock (optional)
-    - "m_axis_dout_aclk", DOUT AXI4-Stream Master interface clock (optional)
-    - "m_axis_dout_words_aclk", DOUT_WORDS AXI4-Stream Master interface clock (optional)
-    - "m_axis_status_aclk", Status output AXI4-Stream Master interface clock (optional)
-- clocks : Clock phandles (see clock_bindings.txt for details).
-- reg: Should contain Xilinx SDFEC 16nm Hardened IP block registers
-  location and length.
-- xlnx,sdfec-code : Should contain "ldpc" or "turbo" to describe the codes
-  being used.
-- xlnx,sdfec-din-words : A value 0 indicates that the DIN_WORDS interface is
-  driven with a fixed value and is not present on the device, a value of 1
-  configures the DIN_WORDS to be block based, while a value of 2 configures the
-  DIN_WORDS input to be supplied for each AXI transaction.
-- xlnx,sdfec-din-width : Configures the DIN AXI stream where a value of 1
-  configures a width of "1x128b", 2 a width of "2x128b" and 4 configures a width
-  of "4x128b".
-- xlnx,sdfec-dout-words : A value 0 indicates that the DOUT_WORDS interface is
-  driven with a fixed value and is not present on the device, a value of 1
-  configures the DOUT_WORDS to be block based, while a value of 2 configures the
-  DOUT_WORDS input to be supplied for each AXI transaction.
-- xlnx,sdfec-dout-width : Configures the DOUT AXI stream where a value of 1
-  configures a width of "1x128b", 2 a width of "2x128b" and 4 configures a width
-  of "4x128b".
-Optional properties:
-- interrupts: should contain SDFEC interrupt number
-
-Example
----------------------------------------
-	sd_fec_0: sd-fec@a0040000 {
-		compatible = "xlnx,sd-fec-1.1";
-		clock-names = "core_clk","s_axi_aclk","s_axis_ctrl_aclk","s_axis_din_aclk","m_axis_status_aclk","m_axis_dout_aclk";
-		clocks = <&misc_clk_2>,<&misc_clk_0>,<&misc_clk_1>,<&misc_clk_1>,<&misc_clk_1>, <&misc_clk_1>;
-		reg = <0x0 0xa0040000 0x0 0x40000>;
-		interrupt-parent = <&axi_intc>;
-		interrupts = <1 0>;
-		xlnx,sdfec-code = "ldpc";
-		xlnx,sdfec-din-words = <0>;
-		xlnx,sdfec-din-width = <2>;
-		xlnx,sdfec-dout-words = <0>;
-		xlnx,sdfec-dout-width = <1>;
-	};
diff --git a/Documentation/devicetree/bindings/misc/xlnx,sd-fec.yaml b/Documentation/devicetree/bindings/misc/xlnx,sd-fec.yaml
new file mode 100644
index 000000000000..8534beac042d
--- /dev/null
+++ b/Documentation/devicetree/bindings/misc/xlnx,sd-fec.yaml
@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/misc/xlnx,sd-fec.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Xilinx SDFEC(16nm) IP
+
+maintainers:
+  - Cvetic, Dragan <dragan.cvetic@amd.com>
+  - Erim, Salih <salih.erim@amd.com>
+
+description: |
+  The Soft Decision Forward Error Correction (SDFEC) Engine is a Hard IP block
+  which provides high-throughput LDPC and Turbo Code implementations.
+  The LDPC decode & encode functionality is capable of covering a range of
+  customer specified Quasi-cyclic (QC) codes. The Turbo decode functionality
+  principally covers codes used by LTE. The FEC Engine offers significant
+  power and area savings versus implementations done in the FPGA fabric.
+
+properties:
+  compatible:
+    const: xlnx,sd-fec-1.1
+
+  reg:
+    maxItems: 1
+
+  clocks:
+    minItems: 2
+    maxItems: 8
+    additionalItems: true
+    items:
+      - description: Main processing clock for processing core
+      - description: AXI4-Lite memory-mapped slave interface clock
+      - description: Control input AXI4-Stream Slave interface clock
+      - description: DIN AXI4-Stream Slave interface clock
+      - description: Status output AXI4-Stream Master interface clock
+      - description: DOUT AXI4-Stream Master interface clock
+      - description: DIN_WORDS AXI4-Stream Slave interface clock
+      - description: DOUT_WORDS AXI4-Stream Master interface clock
+
+  clock-names:
+    minItems: 2
+    maxItems: 8
+    additionalItems: true
+    items:
+      - const: core_clk
+      - const: s_axi_aclk
+    contains:
+      enum:
+        - s_axis_ctrl_aclk
+        - s_axis_din_aclk
+        - m_axis_status_aclk
+        - m_axis_dout_aclk
+        - s_axis_din_words_aclk
+        - m_axis_dout_words_aclk
+
+  interrupts:
+    maxItems: 1
+
+  xlnx,sdfec-code:
+    description: |
+      The SD-FEC integrated block supports Low Density Parity Check (LDPC)
+      decoding and encoding and Turbo code decoding. The LDPC codes used are
+      highly configurable, and the specific code used can be specified on
+      a codeword-by-codeword basis. The Turbo code decoding is required by LTE
+      standard.
+    $ref: /schemas/types.yaml#/definitions/string
+    items:
+      enum: [ ldpc, turbo ]
+
+  xlnx,sdfec-din-width:
+    description: |
+      Configures the DIN AXI stream where a value of 1
+      configures a width of "1x128b", 2 a width of "2x128b" and 4 configures a width
+      of "4x128b".
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum: [ 1, 2, 4 ]
+
+  xlnx,sdfec-din-words:
+    description: |
+      A value 0 indicates that the DIN_WORDS interface is
+      driven with a fixed value and is not present on the device, a value of 1
+      configures the DIN_WORDS to be block based, while a value of 2 configures the
+      DIN_WORDS input to be supplied for each AXI transaction.
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum: [ 0, 1, 2 ]
+
+  xlnx,sdfec-dout-width:
+    description: |
+      Configures the DOUT AXI stream where a value of 1 configures a width of "1x128b",
+      2 a width of "2x128b" and 4 configures a width of "4x128b".
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum: [ 1, 2, 4 ]
+
+  xlnx,sdfec-dout-words:
+    description: |
+      A value 0 indicates that the DOUT_WORDS interface is
+      driven with a fixed value and is not present on the device, a value of 1
+      configures the DOUT_WORDS to be block based, while a value of 2 configures the
+      DOUT_WORDS input to be supplied for each AXI transaction.
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum: [ 0, 1, 2 ]
+
+
+required:
+  - compatible
+  - reg
+  - clocks
+  - clock-names
+  - xlnx,sdfec-code
+  - xlnx,sdfec-din-width
+  - xlnx,sdfec-din-words
+  - xlnx,sdfec-dout-width
+  - xlnx,sdfec-dout-words
+
+additionalProperties: false
+
+examples:
+  - |
+    sd-fec@a0040000 {
+        compatible = "xlnx,sd-fec-1.1";
+        reg = <0xa0040000 0x40000>;
+        clocks = <&misc_clk_2>, <&misc_clk_0>, <&misc_clk_1>, <&misc_clk_1>,
+                 <&misc_clk_1>, <&misc_clk_1>;
+        clock-names = "core_clk", "s_axi_aclk", "s_axis_ctrl_aclk",
+                      "s_axis_din_aclk", "m_axis_status_aclk",
+                      "m_axis_dout_aclk";
+        interrupts = <1 IRQ_TYPE_LEVEL_HIGH>;
+        xlnx,sdfec-code = "ldpc";
+        xlnx,sdfec-din-width = <2>;
+        xlnx,sdfec-din-words = <0>;
+        xlnx,sdfec-dout-width = <1>;
+        xlnx,sdfec-dout-words = <0>;
+    };
+
diff --git a/Documentation/misc-devices/xilinx_sdfec.rst b/Documentation/misc-devices/xilinx_sdfec.rst
index 8c8a289d69a3..698e6630f3a7 100644
--- a/Documentation/misc-devices/xilinx_sdfec.rst
+++ b/Documentation/misc-devices/xilinx_sdfec.rst
@@ -29,7 +29,7 @@ follows:
   - Does not support shared LDPC code table wraparound
 
 The device tree entry is described in:
-`linux-xlnx/Documentation/devicetree/bindings/misc/xlnx,sd-fec.txt <https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/misc/xlnx%2Csd-fec.txt>`_
+`linux-xlnx/Documentation/devicetree/bindings/misc/xlnx,sd-fec.yaml <https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/misc/xlnx%2Csd-fec.yaml>`_
 
 
 Modes of Operation
diff --git a/MAINTAINERS b/MAINTAINERS
index 8999497011a2..d62e04322e19 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -24157,7 +24157,7 @@ XILINX SD-FEC IP CORES
 M:	Derek Kiernan <derek.kiernan@amd.com>
 M:	Dragan Cvetic <dragan.cvetic@amd.com>
 S:	Maintained
-F:	Documentation/devicetree/bindings/misc/xlnx,sd-fec.txt
+F:	Documentation/devicetree/bindings/misc/xlnx,sd-fec.yaml
 F:	Documentation/misc-devices/xilinx_sdfec.rst
 F:	drivers/misc/Kconfig
 F:	drivers/misc/Makefile
-- 
2.34.1

Re: [PATCH v2] dt-bindings: misc: xlnx,sd-fec: convert bindings to yaml

[Rob Herring]

On Mon, 29 Jan 2024 17:18:51 +0000, Dragan Cvetic wrote:
> Convert AMD (Xilinx) sd-fec bindings to yaml format, so it can validate
> dt-entries as well as any future additions to yaml.
> Change in clocks is due to IP is itself configurable and
> only the first two clocks are in all combinations. The last
> 6 clocks can be present in some of them. It means order is
> not really fixed and any combination is possible.
> Interrupt may or may not be present.
> The documentation for sd-fec bindings is now YAML, so update the
> MAINTAINERS file.
> Update the link to the new yaml file in xilinx_sdfec.rst.
> 
> Signed-off-by: Dragan Cvetic <dragan.cvetic@amd.com>
> ---
> Changes in v2:
> ---
> Drop clocks description.
> Use "contains:" with enum for optional clock-names and update
> comment explaining diference from the original DT binding file.
> Remove trailing full stops.
> Add more details in sdfec-code description.
> Set sdfec-code to "string" not "string-array"
> ---
>  .../devicetree/bindings/misc/xlnx,sd-fec.txt  |  58 --------
>  .../devicetree/bindings/misc/xlnx,sd-fec.yaml | 136 ++++++++++++++++++
>  Documentation/misc-devices/xilinx_sdfec.rst   |   2 +-
>  MAINTAINERS                                   |   2 +-
>  4 files changed, 138 insertions(+), 60 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/misc/xlnx,sd-fec.txt
>  create mode 100644 Documentation/devicetree/bindings/misc/xlnx,sd-fec.yaml
> 

My bot found errors running 'make DT_CHECKER_FLAGS=-m dt_binding_check'
on your patch (DT_CHECKER_FLAGS is new in v5.13):

yamllint warnings/errors:

dtschema/dtc warnings/errors:
Error: Documentation/devicetree/bindings/misc/xlnx,sd-fec.example.dts:32.29-30 syntax error
FATAL ERROR: Unable to parse input tree
make[2]: *** [scripts/Makefile.lib:419: Documentation/devicetree/bindings/misc/xlnx,sd-fec.example.dtb] Error 1
make[2]: *** Waiting for unfinished jobs....
make[1]: *** [/builds/robherring/dt-review-ci/linux/Makefile:1428: dt_binding_check] Error 2
make: *** [Makefile:240: __sub-make] Error 2

doc reference errors (make refcheckdocs):

See https://patchwork.ozlabs.org/project/devicetree-bindings/patch/20240129171854.3570055-1-dragan.cvetic@amd.com

The base for the series is generally the latest rc1. A different dependency
should be noted in *this* patch.

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure 'yamllint' is installed and dt-schema is up to
date:

pip3 install dtschema --upgrade

Please check and re-submit after running the above command yourself. Note
that DT_SCHEMA_FILES can be set to your schema file to speed up checking
your schema. However, it must be unset to test all examples with your schema.

RE: [PATCH v2] dt-bindings: misc: xlnx,sd-fec: convert bindings to yaml

[Cvetic, Dragan]

Hi Rob, 

> -----Original Message-----
> From: Rob Herring <robh@kernel.org>
> Sent: Monday, January 29, 2024 10:21 PM
> To: Cvetic, Dragan <dragan.cvetic@amd.com>
> Cc: Krzysztof Kozlowski <krzysztof.kozlowski+dt@linaro.org>; Rob Herring
> <robh+dt@kernel.org>; Simek, Michal <michal.simek@amd.com>; open
> list:OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS
> <devicetree@vger.kernel.org>; Jonathan Corbet <corbet@lwn.net>; Kiernan,
> Derek <derek.kiernan@amd.com>; moderated list:ARM/ZYNQ ARCHITECTURE
> <linux-arm-kernel@lists.infradead.org>; open list:DOCUMENTATION <linux-
> doc@vger.kernel.org>; open list <linux-kernel@vger.kernel.org>; Erim, Salih
> <Salih.Erim@amd.com>; Conor Dooley <conor+dt@kernel.org>
> Subject: Re: [PATCH v2] dt-bindings: misc: xlnx,sd-fec: convert bindings to
> yaml
> 
> 
> On Mon, 29 Jan 2024 17:18:51 +0000, Dragan Cvetic wrote:
> > Convert AMD (Xilinx) sd-fec bindings to yaml format, so it can validate
> > dt-entries as well as any future additions to yaml.
> > Change in clocks is due to IP is itself configurable and
> > only the first two clocks are in all combinations. The last
> > 6 clocks can be present in some of them. It means order is
> > not really fixed and any combination is possible.
> > Interrupt may or may not be present.
> > The documentation for sd-fec bindings is now YAML, so update the
> > MAINTAINERS file.
> > Update the link to the new yaml file in xilinx_sdfec.rst.
> >
> > Signed-off-by: Dragan Cvetic <dragan.cvetic@amd.com>
> > ---
> > Changes in v2:
> > ---
> > Drop clocks description.
> > Use "contains:" with enum for optional clock-names and update
> > comment explaining diference from the original DT binding file.
> > Remove trailing full stops.
> > Add more details in sdfec-code description.
> > Set sdfec-code to "string" not "string-array"
> > ---
> >  .../devicetree/bindings/misc/xlnx,sd-fec.txt  |  58 --------
> >  .../devicetree/bindings/misc/xlnx,sd-fec.yaml | 136 ++++++++++++++++++
> >  Documentation/misc-devices/xilinx_sdfec.rst   |   2 +-
> >  MAINTAINERS                                   |   2 +-
> >  4 files changed, 138 insertions(+), 60 deletions(-)
> >  delete mode 100644 Documentation/devicetree/bindings/misc/xlnx,sd-
> fec.txt
> >  create mode 100644 Documentation/devicetree/bindings/misc/xlnx,sd-
> fec.yaml
> >
> 
> My bot found errors running 'make DT_CHECKER_FLAGS=-m
> dt_binding_check'


Accepted, will do it.


> on your patch (DT_CHECKER_FLAGS is new in v5.13):
> 
> yamllint warnings/errors:
> 
> dtschema/dtc warnings/errors:
> Error: Documentation/devicetree/bindings/misc/xlnx,sd-
> fec.example.dts:32.29-30 syntax error
> FATAL ERROR: Unable to parse input tree
> make[2]: *** [scripts/Makefile.lib:419:
> Documentation/devicetree/bindings/misc/xlnx,sd-fec.example.dtb] Error 1
> make[2]: *** Waiting for unfinished jobs....
> make[1]: *** [/builds/robherring/dt-review-ci/linux/Makefile:1428:
> dt_binding_check] Error 2
> make: *** [Makefile:240: __sub-make] Error 2
> 
> doc reference errors (make refcheckdocs):
> 
> See https://patchwork.ozlabs.org/project/devicetree-
> bindings/patch/20240129171854.3570055-1-dragan.cvetic@amd.com
> 
> The base for the series is generally the latest rc1. A different dependency
> should be noted in *this* patch.
> 
> If you already ran 'make dt_binding_check' and didn't see the above
> error(s), then make sure 'yamllint' is installed and dt-schema is up to
> date:
> 
> pip3 install dtschema --upgrade
> 
> Please check and re-submit after running the above command yourself. Note
> that DT_SCHEMA_FILES can be set to your schema file to speed up checking
> your schema. However, it must be unset to test all examples with your
> schema.

All comments accepted

Kind Regards
Dragan

Re: [PATCH v2] dt-bindings: misc: xlnx,sd-fec: convert bindings to yaml

[Krzysztof Kozlowski]

On 30/01/2024 12:07, Cvetic, Dragan wrote:
> Hi Rob, 
> 
>> -----Original Message-----
>> From: Rob Herring <robh@kernel.org>
>> Sent: Monday, January 29, 2024 10:21 PM
>> To: Cvetic, Dragan <dragan.cvetic@amd.com>
>> Cc: Krzysztof Kozlowski <krzysztof.kozlowski+dt@linaro.org>; Rob Herring
>> <robh+dt@kernel.org>; Simek, Michal <michal.simek@amd.com>; open
>> list:OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS
>> <devicetree@vger.kernel.org>; Jonathan Corbet <corbet@lwn.net>; Kiernan,
>> Derek <derek.kiernan@amd.com>; moderated list:ARM/ZYNQ ARCHITECTURE
>> <linux-arm-kernel@lists.infradead.org>; open list:DOCUMENTATION <linux-
>> doc@vger.kernel.org>; open list <linux-kernel@vger.kernel.org>; Erim, Salih
>> <Salih.Erim@amd.com>; Conor Dooley <conor+dt@kernel.org>
>> Subject: Re: [PATCH v2] dt-bindings: misc: xlnx,sd-fec: convert bindings to
>> yaml
>>
>>
>> On Mon, 29 Jan 2024 17:18:51 +0000, Dragan Cvetic wrote:
>>> Convert AMD (Xilinx) sd-fec bindings to yaml format, so it can validate
>>> dt-entries as well as any future additions to yaml.
>>> Change in clocks is due to IP is itself configurable and
>>> only the first two clocks are in all combinations. The last
>>> 6 clocks can be present in some of them. It means order is
>>> not really fixed and any combination is possible.
>>> Interrupt may or may not be present.
>>> The documentation for sd-fec bindings is now YAML, so update the
>>> MAINTAINERS file.
>>> Update the link to the new yaml file in xilinx_sdfec.rst.
>>>
>>> Signed-off-by: Dragan Cvetic <dragan.cvetic@amd.com>
>>> ---
>>> Changes in v2:
>>> ---
>>> Drop clocks description.
>>> Use "contains:" with enum for optional clock-names and update
>>> comment explaining diference from the original DT binding file.
>>> Remove trailing full stops.
>>> Add more details in sdfec-code description.
>>> Set sdfec-code to "string" not "string-array"
>>> ---
>>>  .../devicetree/bindings/misc/xlnx,sd-fec.txt  |  58 --------
>>>  .../devicetree/bindings/misc/xlnx,sd-fec.yaml | 136 ++++++++++++++++++
>>>  Documentation/misc-devices/xilinx_sdfec.rst   |   2 +-
>>>  MAINTAINERS                                   |   2 +-
>>>  4 files changed, 138 insertions(+), 60 deletions(-)
>>>  delete mode 100644 Documentation/devicetree/bindings/misc/xlnx,sd-
>> fec.txt
>>>  create mode 100644 Documentation/devicetree/bindings/misc/xlnx,sd-
>> fec.yaml
>>>
>>
>> My bot found errors running 'make DT_CHECKER_FLAGS=-m
>> dt_binding_check'
> 
> 
> Accepted, will do it.

There is nothing to accept here, but instead please test your patches
*before* sending them.

Best regards,
Krzysztof