[v9,1/7] dt-bindings: add documentation of xilinx clocking wizard

Add the devicetree binding for the xilinx clocking wizard.

Signed-off-by: Shubhrajyoti Datta <shubhrajyoti.datta@xilinx.com>
---
v6:
Fix a yaml warning
v7:
Add vendor prefix speed-grade
v8:
Fix the warnings
v9:
Fix the warnings

 .../bindings/clock/xlnx,clocking-wizard.yaml       | 65 ++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/clock/xlnx,clocking-wizard.yaml

Hi Shubhrajyoti,

Shubhrajyoti Datta <shubhrajyoti.datta@xilinx.com> wrote on Thu, 18 Feb
2021 10:19:45 +0530:

> Add the devicetree binding for the xilinx clocking wizard.
> 
> Signed-off-by: Shubhrajyoti Datta <shubhrajyoti.datta@xilinx.com>
> ---
> v6:
> Fix a yaml warning
> v7:
> Add vendor prefix speed-grade
> v8:
> Fix the warnings
> v9:
> Fix the warnings
> 
>  .../bindings/clock/xlnx,clocking-wizard.yaml       | 65 ++++++++++++++++++++++
>  1 file changed, 65 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/clock/xlnx,clocking-wizard.yaml
> 
> diff --git a/Documentation/devicetree/bindings/clock/xlnx,clocking-wizard.yaml b/Documentation/devicetree/bindings/clock/xlnx,clocking-wizard.yaml
> new file mode 100644
> index 0000000..d209140
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/clock/xlnx,clocking-wizard.yaml
> @@ -0,0 +1,65 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: "http://devicetree.org/schemas/clock/xlnx,clocking-wizard.yaml#"
> +$schema: "http://devicetree.org/meta-schemas/core.yaml#"
> +
> +title: Xilinx clocking wizard
> +
> +maintainers:
> +  - Shubhrajyoti Datta <shubhrajyoti.datta@xilinx.com>
> +
> +description:
> +  The clocking wizard is a soft ip clocking block of Xilinx versal. It
> +  reads required input clock frequencies from the devicetree and acts as clock
> +  clock output.
> +
> +properties:
> +  compatible:
> +    const: xlnx,clocking-wizard
> +
> +  reg:
> +    maxItems: 1
> +
> +  "#clock-cells":
> +    const: 1
> +
> +  clocks:
> +    items:
> +      - description: clock input
> +      - description: axi clock
> +
> +  clock-names:
> +    items:
> +      - const: clk_in1
> +      - const: s_axi_aclk
> +
> +  clock-output-names: true
> +
> +  xlnx,speed-grade:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    enum: [1, 2, 3]
> +    description:
> +      Speed grade of the device.

A bit of explanation of what this describes would be welcome.

Don't forget that binding are not tied to any driver implementation,
these are supposed to be hardware description properties.

> +
> +required:
> +  - compatible
> +  - reg
> +  - "#clock-cells"
> +  - clocks
> +  - clock-names
> +  - xlnx,speed-grade
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    clock-controller  {
> +        compatible = "xlnx,clocking-wizard";
> +        reg = <0xb0000000 0x10000>;
> +        #clock-cells = <1>;
> +        xlnx,speed-grade = <1>;
> +        clock-names = "clk_in1", "s_axi_aclk";
> +        clocks = <&clkc 15>, <&clkc 15>;
> +    };
> +...

Thanks,
Miquèl

On Thu, 18 Feb 2021 10:19:45 +0530, Shubhrajyoti Datta wrote:
> Add the devicetree binding for the xilinx clocking wizard.
> 
> Signed-off-by: Shubhrajyoti Datta <shubhrajyoti.datta@xilinx.com>
> ---
> v6:
> Fix a yaml warning
> v7:
> Add vendor prefix speed-grade
> v8:
> Fix the warnings
> v9:
> Fix the warnings
> 
>  .../bindings/clock/xlnx,clocking-wizard.yaml       | 65 ++++++++++++++++++++++
>  1 file changed, 65 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/clock/xlnx,clocking-wizard.yaml
> 

My bot found errors running 'make dt_binding_check' on your patch:

yamllint warnings/errors:

dtschema/dtc warnings/errors:
Documentation/devicetree/bindings/clock/xlnx,clocking-wizard.example.dts:19.26-26.11: Warning (unit_address_vs_reg): /example-0/clock-controller: node has a reg or ranges property, but no unit name

See https://patchwork.ozlabs.org/patch/1441521

This check can fail if there are any dependencies. The base for a patch
series is generally the most recent rc1.

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.

Quoting Miquel Raynal (2021-02-18 00:28:04)
> Hi Shubhrajyoti,
> 
> Shubhrajyoti Datta <shubhrajyoti.datta@xilinx.com> wrote on Thu, 18 Feb
> 2021 10:19:45 +0530:
> 
> > Add the devicetree binding for the xilinx clocking wizard.
> > 
> > Signed-off-by: Shubhrajyoti Datta <shubhrajyoti.datta@xilinx.com>
> > ---
> > v6:
> > Fix a yaml warning
> > v7:
> > Add vendor prefix speed-grade
> > v8:
> > Fix the warnings
> > v9:
> > Fix the warnings
> > 
> >  .../bindings/clock/xlnx,clocking-wizard.yaml       | 65 ++++++++++++++++++++++
> >  1 file changed, 65 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/clock/xlnx,clocking-wizard.yaml
> > 
> > diff --git a/Documentation/devicetree/bindings/clock/xlnx,clocking-wizard.yaml b/Documentation/devicetree/bindings/clock/xlnx,clocking-wizard.yaml
> > new file mode 100644
> > index 0000000..d209140
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/clock/xlnx,clocking-wizard.yaml
> > @@ -0,0 +1,65 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: "http://devicetree.org/schemas/clock/xlnx,clocking-wizard.yaml#"
> > +$schema: "http://devicetree.org/meta-schemas/core.yaml#"
> > +
> > +title: Xilinx clocking wizard
> > +
> > +maintainers:
> > +  - Shubhrajyoti Datta <shubhrajyoti.datta@xilinx.com>
> > +
> > +description:
> > +  The clocking wizard is a soft ip clocking block of Xilinx versal. It
> > +  reads required input clock frequencies from the devicetree and acts as clock
> > +  clock output.
> > +
> > +properties:
> > +  compatible:
> > +    const: xlnx,clocking-wizard
> > +
> > +  reg:
> > +    maxItems: 1
> > +
> > +  "#clock-cells":
> > +    const: 1
> > +
> > +  clocks:
> > +    items:
> > +      - description: clock input
> > +      - description: axi clock
> > +
> > +  clock-names:
> > +    items:
> > +      - const: clk_in1
> > +      - const: s_axi_aclk
> > +
> > +  clock-output-names: true
> > +
> > +  xlnx,speed-grade:
> > +    $ref: /schemas/types.yaml#/definitions/uint32
> > +    enum: [1, 2, 3]
> > +    description:
> > +      Speed grade of the device.
> 
> A bit of explanation of what this describes would be welcome.
> 
> Don't forget that binding are not tied to any driver implementation,
> these are supposed to be hardware description properties.

Would opp tables work for this?

On Fri, Feb 19, 2021 at 6:54 AM Stephen Boyd <sboyd@kernel.org> wrote:
>
> Quoting Miquel Raynal (2021-02-18 00:28:04)
> > Hi Shubhrajyoti,
> >
> > Shubhrajyoti Datta <shubhrajyoti.datta@xilinx.com> wrote on Thu, 18 Feb
> > 2021 10:19:45 +0530:
> >
> > > Add the devicetree binding for the xilinx clocking wizard.
> > >
> > > Signed-off-by: Shubhrajyoti Datta <shubhrajyoti.datta@xilinx.com>
> > > ---
> > > v6:
> > > Fix a yaml warning
> > > v7:
> > > Add vendor prefix speed-grade
> > > v8:
> > > Fix the warnings
> > > v9:
> > > Fix the warnings
> > >
> > >  .../bindings/clock/xlnx,clocking-wizard.yaml       | 65 ++++++++++++++++++++++
> > >  1 file changed, 65 insertions(+)
> > >  create mode 100644 Documentation/devicetree/bindings/clock/xlnx,clocking-wizard.yaml
> > >
> > > diff --git a/Documentation/devicetree/bindings/clock/xlnx,clocking-wizard.yaml b/Documentation/devicetree/bindings/clock/xlnx,clocking-wizard.yaml
> > > new file mode 100644
> > > index 0000000..d209140
> > > --- /dev/null
> > > +++ b/Documentation/devicetree/bindings/clock/xlnx,clocking-wizard.yaml
> > > @@ -0,0 +1,65 @@
> > > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > > +%YAML 1.2
> > > +---
> > > +$id: "http://devicetree.org/schemas/clock/xlnx,clocking-wizard.yaml#"
> > > +$schema: "http://devicetree.org/meta-schemas/core.yaml#"
> > > +
> > > +title: Xilinx clocking wizard
> > > +
> > > +maintainers:
> > > +  - Shubhrajyoti Datta <shubhrajyoti.datta@xilinx.com>
> > > +
> > > +description:
> > > +  The clocking wizard is a soft ip clocking block of Xilinx versal. It
> > > +  reads required input clock frequencies from the devicetree and acts as clock
> > > +  clock output.
> > > +
> > > +properties:
> > > +  compatible:
> > > +    const: xlnx,clocking-wizard
> > > +
> > > +  reg:
> > > +    maxItems: 1
> > > +
> > > +  "#clock-cells":
> > > +    const: 1
> > > +
> > > +  clocks:
> > > +    items:
> > > +      - description: clock input
> > > +      - description: axi clock
> > > +
> > > +  clock-names:
> > > +    items:
> > > +      - const: clk_in1
> > > +      - const: s_axi_aclk
> > > +
> > > +  clock-output-names: true
> > > +
> > > +  xlnx,speed-grade:
> > > +    $ref: /schemas/types.yaml#/definitions/uint32
> > > +    enum: [1, 2, 3]
> > > +    description:
> > > +      Speed grade of the device.
> >
> > A bit of explanation of what this describes would be welcome.
> >
> > Don't forget that binding are not tied to any driver implementation,
> > these are supposed to be hardware description properties.
>
> Would opp tables work for this?
This is the parameter is for speed of the fabric.

Quoting Shubhrajyoti Datta (2021-02-24 06:10:08)
> On Fri, Feb 19, 2021 at 6:54 AM Stephen Boyd <sboyd@kernel.org> wrote:
> >
> > > > +
> > > > +  xlnx,speed-grade:
> > > > +    $ref: /schemas/types.yaml#/definitions/uint32
> > > > +    enum: [1, 2, 3]
> > > > +    description:
> > > > +      Speed grade of the device.
> > >
> > > A bit of explanation of what this describes would be welcome.
> > >
> > > Don't forget that binding are not tied to any driver implementation,
> > > these are supposed to be hardware description properties.
> >
> > Would opp tables work for this?
> This is the parameter is for speed of the fabric.

Ok. Yes or no? Is it configuring the speed of the fabric? Sounds like
assigned-clock-rates or assigned-interconnect-bandwidth or something
like that.

Hi Stephen,

On Wed, Mar 3, 2021 at 4:37 AM Stephen Boyd <sboyd@kernel.org> wrote:
>
> Quoting Shubhrajyoti Datta (2021-02-24 06:10:08)
> > On Fri, Feb 19, 2021 at 6:54 AM Stephen Boyd <sboyd@kernel.org> wrote:
> > >
> > > > > +
> > > > > +  xlnx,speed-grade:
> > > > > +    $ref: /schemas/types.yaml#/definitions/uint32
> > > > > +    enum: [1, 2, 3]
> > > > > +    description:
> > > > > +      Speed grade of the device.
> > > >
> > > > A bit of explanation of what this describes would be welcome.
> > > >
> > > > Don't forget that binding are not tied to any driver implementation,
> > > > these are supposed to be hardware description properties.
> > >
> > > Would opp tables work for this?
> > This is the parameter is for speed of the fabric.
>
> Ok. Yes or no? Is it configuring the speed of the fabric? Sounds like
> assigned-clock-rates or assigned-interconnect-bandwidth or something
> like that.

I do not think we could use opp tables.
Xilinx has products where we have partly FPGA and patrly PS(hardware
is not programmable) so the ip could be in PL
and the processor  in PS.

The speed grade influences a variety of timing parameters in the FPGA,
including fabric (slice), multiplier/DSP48x, BlockRAM, I/O, and other
resources parameters.

Basically the timing of the fabric is determined by it. Also we are
notifying the speed grade to the driver no configuration is done.
We are telling which speed-grade fabric we are running on.

 There is no correlation between these numbers. It is really a
relative metric of performance within a specific family.