[PATCH v2 2/2] dt-bindings: iio: adc: Add DT docs for AD7292

[PATCH v2 2/2] dt-bindings: iio: adc: Add DT docs for AD7292

[Marcelo Schmitt]

Add a device tree binding doc for AD7292 monitor and control system.

Signed-off-by: Marcelo Schmitt <marcelo.schmitt1@gmail.com>
---
 .../bindings/iio/adc/adi,ad7292.yaml          | 107 ++++++++++++++++++
 MAINTAINERS                                   |   1 +
 2 files changed, 108 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml

diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml
new file mode 100644
index 000000000000..40028332d9e2
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml
@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,ad7292.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD7292 10-Bit Monitor and Control System
+
+maintainers:
+  - Marcelo Schmitt <marcelo.schmitt1@gmail.com>
+
+description: |
+  Analog Devices AD7292 10-Bit Monitor and Control System with ADC, DACs,
+  Temperature Sensor, and GPIOs
+
+  Specifications about the part can be found at:
+    https://www.analog.com/media/en/technical-documentation/data-sheets/ad7292.pdf
+
+properties:
+  compatible:
+    enum:
+      - adi,ad7292
+
+  reg:
+    maxItems: 1
+
+  vref-supply:
+    description: |
+      The regulator supply for ADC and DAC reference voltage.
+    maxItems: 1
+
+  spi-cpha:
+    description: |
+      See Documentation/devicetree/bindings/spi/spi-controller.yaml
+    maxItems: 1
+
+  '#address-cells':
+    const: 1
+
+  '#size-cells':
+    const: 0
+
+required:
+  - compatible
+  - reg
+
+patternProperties:
+  "^channel@[0-7]$":
+    type: object
+    description: |
+      Represents the external channels which are connected to the ADC.
+      See Documentation/devicetree/bindings/iio/adc/adc.txt.
+
+    properties:
+      reg:
+        description: |
+          The channel number. It can have up to 8 channels numbered from 0 to 7.
+        maxItems: 1
+
+      diff-channels:
+        description: see Documentation/devicetree/bindings/iio/adc/adc.txt
+        maxItems: 1
+
+    required:
+      - reg
+
+examples:
+  - |
+    spi {
+      #address-cells = <1>;
+      #size-cells = <0>;
+
+      ad7292: ad7292@0 {
+        compatible = "adi,ad7292";
+        reg = <0>;
+
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        spi-max-frequency = <25000000>;
+        vref-supply = <&adc_vref>;
+        spi-cpha;
+
+        channel@0 {
+          reg = <0>;
+          diff-channels = <0 1>;
+        };
+        channel@2 {
+          reg = <2>;
+        };
+        channel@3 {
+          reg = <3>;
+        };
+        channel@4 {
+          reg = <4>;
+        };
+        channel@5 {
+          reg = <5>;
+        };
+        channel@6 {
+          reg = <6>;
+        };
+        channel@7 {
+          reg = <7>;
+        };
+      };
+    }
diff --git a/MAINTAINERS b/MAINTAINERS
index e78317a5f4f1..5941cfc0d6f7 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -819,6 +819,7 @@ L:	linux-iio@vger.kernel.org
 W:	http://ez.analog.com/community/linux-device-drivers
 S:	Supported
 F:	drivers/iio/adc/ad7292.c
+F:	Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml
 
 ANALOG DEVICES INC AD7606 DRIVER
 M:	Stefan Popa <stefan.popa@analog.com>
-- 
2.23.0

Re: [PATCH v2 2/2] dt-bindings: iio: adc: Add DT docs for AD7292

[Rob Herring]

On Tue, Oct 15, 2019 at 11:52:23PM -0300, Marcelo Schmitt wrote:
> Add a device tree binding doc for AD7292 monitor and control system.
> 
> Signed-off-by: Marcelo Schmitt <marcelo.schmitt1@gmail.com>
> ---
>  .../bindings/iio/adc/adi,ad7292.yaml          | 107 ++++++++++++++++++
>  MAINTAINERS                                   |   1 +
>  2 files changed, 108 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml
> 
> diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml
> new file mode 100644
> index 000000000000..40028332d9e2
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml
> @@ -0,0 +1,107 @@
> +# SPDX-License-Identifier: GPL-2.0
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/iio/adc/adi,ad7292.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Analog Devices AD7292 10-Bit Monitor and Control System
> +
> +maintainers:
> +  - Marcelo Schmitt <marcelo.schmitt1@gmail.com>
> +
> +description: |
> +  Analog Devices AD7292 10-Bit Monitor and Control System with ADC, DACs,
> +  Temperature Sensor, and GPIOs
> +
> +  Specifications about the part can be found at:
> +    https://www.analog.com/media/en/technical-documentation/data-sheets/ad7292.pdf
> +
> +properties:
> +  compatible:
> +    enum:
> +      - adi,ad7292
> +
> +  reg:
> +    maxItems: 1
> +
> +  vref-supply:
> +    description: |
> +      The regulator supply for ADC and DAC reference voltage.
> +    maxItems: 1

Not necessary, regulator supplies are always 1 item, so drop maxItems.

> +
> +  spi-cpha:
> +    description: |
> +      See Documentation/devicetree/bindings/spi/spi-controller.yaml
> +    maxItems: 1

This is just wrong because spi-cpha is a boolean. Just 'spi-cpha: true' 
is sufficient. If this device needs this property, then it should 
probably be required.

> +
> +  '#address-cells':
> +    const: 1
> +
> +  '#size-cells':
> +    const: 0
> +
> +required:
> +  - compatible
> +  - reg
> +
> +patternProperties:
> +  "^channel@[0-7]$":
> +    type: object
> +    description: |
> +      Represents the external channels which are connected to the ADC.
> +      See Documentation/devicetree/bindings/iio/adc/adc.txt.
> +
> +    properties:
> +      reg:
> +        description: |
> +          The channel number. It can have up to 8 channels numbered from 0 to 7.
> +        maxItems: 1
> +
> +      diff-channels:
> +        description: see Documentation/devicetree/bindings/iio/adc/adc.txt
> +        maxItems: 1
> +
> +    required:
> +      - reg
> +
> +examples:
> +  - |
> +    spi {
> +      #address-cells = <1>;
> +      #size-cells = <0>;
> +
> +      ad7292: ad7292@0 {

adc@0

> +        compatible = "adi,ad7292";
> +        reg = <0>;
> +
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        spi-max-frequency = <25000000>;
> +        vref-supply = <&adc_vref>;
> +        spi-cpha;
> +
> +        channel@0 {
> +          reg = <0>;
> +          diff-channels = <0 1>;
> +        };
> +        channel@2 {
> +          reg = <2>;
> +        };
> +        channel@3 {
> +          reg = <3>;
> +        };
> +        channel@4 {
> +          reg = <4>;
> +        };
> +        channel@5 {
> +          reg = <5>;
> +        };
> +        channel@6 {
> +          reg = <6>;
> +        };
> +        channel@7 {
> +          reg = <7>;
> +        };
> +      };
> +    }

Missing ';'. Make sure this builds with 'make -k dt_binding_check'. The 
'-k' is due to some other breakage ATM.

Rob

Re: [PATCH v2 2/2] dt-bindings: iio: adc: Add DT docs for AD7292

[Marcelo Schmitt]

Hi Rob

Thanks for the review.

I'm having some trouble with the DTC.
I installed the DT tool from https://github.com/robherring/dt-schema.
Running make -k dt_binding_check goes through all the checks (CHKDT), producing
the .example.dts files but then gives errors like:

  DTC     Documentation/devicetree/bindings/arm/calxeda.example.dt.yaml
FATAL ERROR: Unknown output format "yaml"
make[1]: *** [scripts/Makefile.lib:314: Documentation/devicetree/bindings/arm/calxeda.example.dt.yaml] Error 1
make[1]: *** Deleting file 'Documentation/devicetree/bindings/arm/calxeda.example.dt.yaml'

My pip3 installation has:
jsonschema jsonschema-3.1.2.dev6+g0d827f3
rfc3987 1.3.8

$HOME/.local/bin is listed in my shell's PATH variable.

I was trying to follow the documentation at:
Documentation/devicetree/writing-schema.rst

Are there any other DTC dependencies that I am missing?

On 10/17, Rob Herring wrote:
> On Tue, Oct 15, 2019 at 11:52:23PM -0300, Marcelo Schmitt wrote:
> > Add a device tree binding doc for AD7292 monitor and control system.
> > 
> > Signed-off-by: Marcelo Schmitt <marcelo.schmitt1@gmail.com>
> > ---
> >  .../bindings/iio/adc/adi,ad7292.yaml          | 107 ++++++++++++++++++
> >  MAINTAINERS                                   |   1 +
> >  2 files changed, 108 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml
> > 
> > diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml
> > new file mode 100644
> > index 000000000000..40028332d9e2
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml
> > @@ -0,0 +1,107 @@
> > +# SPDX-License-Identifier: GPL-2.0
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/iio/adc/adi,ad7292.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Analog Devices AD7292 10-Bit Monitor and Control System
> > +
> > +maintainers:
> > +  - Marcelo Schmitt <marcelo.schmitt1@gmail.com>
> > +
> > +description: |
> > +  Analog Devices AD7292 10-Bit Monitor and Control System with ADC, DACs,
> > +  Temperature Sensor, and GPIOs
> > +
> > +  Specifications about the part can be found at:
> > +    https://www.analog.com/media/en/technical-documentation/data-sheets/ad7292.pdf
> > +
> > +properties:
> > +  compatible:
> > +    enum:
> > +      - adi,ad7292
> > +
> > +  reg:
> > +    maxItems: 1
> > +
> > +  vref-supply:
> > +    description: |
> > +      The regulator supply for ADC and DAC reference voltage.
> > +    maxItems: 1
> 
> Not necessary, regulator supplies are always 1 item, so drop maxItems.
> 
> > +
> > +  spi-cpha:
> > +    description: |
> > +      See Documentation/devicetree/bindings/spi/spi-controller.yaml
> > +    maxItems: 1
> 
> This is just wrong because spi-cpha is a boolean. Just 'spi-cpha: true' 
> is sufficient. If this device needs this property, then it should 
> probably be required.
> 
> > +
> > +  '#address-cells':
> > +    const: 1
> > +
> > +  '#size-cells':
> > +    const: 0
> > +
> > +required:
> > +  - compatible
> > +  - reg
> > +
> > +patternProperties:
> > +  "^channel@[0-7]$":
> > +    type: object
> > +    description: |
> > +      Represents the external channels which are connected to the ADC.
> > +      See Documentation/devicetree/bindings/iio/adc/adc.txt.
> > +
> > +    properties:
> > +      reg:
> > +        description: |
> > +          The channel number. It can have up to 8 channels numbered from 0 to 7.
> > +        maxItems: 1
> > +
> > +      diff-channels:
> > +        description: see Documentation/devicetree/bindings/iio/adc/adc.txt
> > +        maxItems: 1
> > +
> > +    required:
> > +      - reg
> > +
> > +examples:
> > +  - |
> > +    spi {
> > +      #address-cells = <1>;
> > +      #size-cells = <0>;
> > +
> > +      ad7292: ad7292@0 {
> 
> adc@0
> 
> > +        compatible = "adi,ad7292";
> > +        reg = <0>;
> > +
> > +        #address-cells = <1>;
> > +        #size-cells = <0>;
> > +
> > +        spi-max-frequency = <25000000>;
> > +        vref-supply = <&adc_vref>;
> > +        spi-cpha;
> > +
> > +        channel@0 {
> > +          reg = <0>;
> > +          diff-channels = <0 1>;
> > +        };
> > +        channel@2 {
> > +          reg = <2>;
> > +        };
> > +        channel@3 {
> > +          reg = <3>;
> > +        };
> > +        channel@4 {
> > +          reg = <4>;
> > +        };
> > +        channel@5 {
> > +          reg = <5>;
> > +        };
> > +        channel@6 {
> > +          reg = <6>;
> > +        };
> > +        channel@7 {
> > +          reg = <7>;
> > +        };
> > +      };
> > +    }
> 
> Missing ';'. Make sure this builds with 'make -k dt_binding_check'. The 
> '-k' is due to some other breakage ATM.
> 
> Rob

Re: [PATCH v2 2/2] dt-bindings: iio: adc: Add DT docs for AD7292

[Rob Herring]

On Sat, Oct 19, 2019 at 10:07 AM Marcelo Schmitt
<marcelo.schmitt1@gmail.com> wrote:
>
> Hi Rob
>
> Thanks for the review.
>
> I'm having some trouble with the DTC.
> I installed the DT tool from https://github.com/robherring/dt-schema.
> Running make -k dt_binding_check goes through all the checks (CHKDT), producing
> the .example.dts files but then gives errors like:
>
>   DTC     Documentation/devicetree/bindings/arm/calxeda.example.dt.yaml
> FATAL ERROR: Unknown output format "yaml"
> make[1]: *** [scripts/Makefile.lib:314: Documentation/devicetree/bindings/arm/calxeda.example.dt.yaml] Error 1
> make[1]: *** Deleting file 'Documentation/devicetree/bindings/arm/calxeda.example.dt.yaml'
>
> My pip3 installation has:
> jsonschema jsonschema-3.1.2.dev6+g0d827f3
> rfc3987 1.3.8
>
> $HOME/.local/bin is listed in my shell's PATH variable.
>
> I was trying to follow the documentation at:
> Documentation/devicetree/writing-schema.rst
>
> Are there any other DTC dependencies that I am missing?

Yes, libyaml. See Documentation/devicetree/writing-schema.rst.

Rob

Re: [PATCH v2 2/2] dt-bindings: iio: adc: Add DT docs for AD7292

[Marcelo Schmitt]

Hi,

I ran the DTC and CHECK for AD7292 schema however, the target '__build'
did not run due to errors found in regulator/fixed-regulator.yaml and
arm/allwinner,sun4i-a10-csi.yaml.

I recall seeing something about the maxItems requirement over regulator
supplies being changed on the iio mailing list, so I updated my repo
locally, cloned and reinstalled the dt-schema toolset. However, I still
can't make it go through the '__build' target.

Python 3.7.5rc1 is my default python and I got the following pip3
packages installed:

ruamel.yaml        0.16.5
ruamel.yaml.clib   0.2.0
rfc3987            1.3.8
jsonschema         3.0.1
dtschema           0.0.1  at $HOME/<iio repo dir>/dt-schema

Debian Bullseye packages installed:
python3-yaml/testing,now 5.1.2-1
libyaml-dev/testing,now 0.2.2-1

I was only able to run DTC after installing the libyaml-dev package, so
I think it might be worth to add it to the project dependencies at
https://github.com/robherring/dt-schema.

apt-get install libyaml-dev

Thanks,
Marcelo

On 10/20, Rob Herring wrote:
> On Sat, Oct 19, 2019 at 10:07 AM Marcelo Schmitt
> <marcelo.schmitt1@gmail.com> wrote:
> >
> > Hi Rob
> >
> > Thanks for the review.
> >
> > I'm having some trouble with the DTC.
> > I installed the DT tool from https://github.com/robherring/dt-schema.
> > Running make -k dt_binding_check goes through all the checks (CHKDT), producing
> > the .example.dts files but then gives errors like:
> >
> >   DTC     Documentation/devicetree/bindings/arm/calxeda.example.dt.yaml
> > FATAL ERROR: Unknown output format "yaml"
> > make[1]: *** [scripts/Makefile.lib:314: Documentation/devicetree/bindings/arm/calxeda.example.dt.yaml] Error 1
> > make[1]: *** Deleting file 'Documentation/devicetree/bindings/arm/calxeda.example.dt.yaml'
> >
> > My pip3 installation has:
> > jsonschema jsonschema-3.1.2.dev6+g0d827f3
> > rfc3987 1.3.8
> >
> > $HOME/.local/bin is listed in my shell's PATH variable.
> >
> > I was trying to follow the documentation at:
> > Documentation/devicetree/writing-schema.rst
> >
> > Are there any other DTC dependencies that I am missing?
> 
> Yes, libyaml. See Documentation/devicetree/writing-schema.rst.
> 
> Rob

Re: [PATCH v2 2/2] dt-bindings: iio: adc: Add DT docs for AD7292

[Rob Herring]

On Tue, Oct 22, 2019 at 9:06 AM Marcelo Schmitt
<marcelo.schmitt1@gmail.com> wrote:
>
> Hi,
>
> I ran the DTC and CHECK for AD7292 schema however, the target '__build'
> did not run due to errors found in regulator/fixed-regulator.yaml and
> arm/allwinner,sun4i-a10-csi.yaml.

Fixes for those are still pending in -next. Use 'make -k' and ignore those.

>
> I recall seeing something about the maxItems requirement over regulator
> supplies being changed on the iio mailing list, so I updated my repo
> locally, cloned and reinstalled the dt-schema toolset. However, I still
> can't make it go through the '__build' target.
>
> Python 3.7.5rc1 is my default python and I got the following pip3
> packages installed:
>
> ruamel.yaml        0.16.5
> ruamel.yaml.clib   0.2.0
> rfc3987            1.3.8
> jsonschema         3.0.1
> dtschema           0.0.1  at $HOME/<iio repo dir>/dt-schema
>
> Debian Bullseye packages installed:
> python3-yaml/testing,now 5.1.2-1
> libyaml-dev/testing,now 0.2.2-1
>
> I was only able to run DTC after installing the libyaml-dev package, so
> I think it might be worth to add it to the project dependencies at
> https://github.com/robherring/dt-schema.

Strictly speaking, it's not a dependency for dt-schema. It's
documented in Documentation/devicetree/writing-schema.rst. I've added
a pointer to that in bindings/submitting-patches.txt. I'm not sure how
else to make it more obvious.

BTW, You will get a useful error message if libyaml is missing when
building 'make dtbs_check'. I need to make that work for
dt_binding_check.

> apt-get install libyaml-dev

You need the lib too, but that tends to already be installed. IIRC,
installing the headers doesn't install the lib automatically.

In any case, I wanted to avoid putting in distro specific instructions
in the kernel.

Rob

Re: [PATCH v2 2/2] dt-bindings: iio: adc: Add DT docs for AD7292

[Marcelo Schmitt]

Hi Rob,

OK, thanks for the explanation.

I indeed missed some details from the documentation. I will be more
careful on my next readings.

I see there are other documentation files at Documentation/devicetree/
and Documentation/devicetree/bindings/. Besides these, would you
recommend other documentation and/or material for those who want to
write dt-bindings that validate with dt-schema?

Thanks in advance,

Marcelo

On 10/22, Rob Herring wrote:
> On Tue, Oct 22, 2019 at 9:06 AM Marcelo Schmitt
> <marcelo.schmitt1@gmail.com> wrote:
> >
> > Hi,
> >
> > I ran the DTC and CHECK for AD7292 schema however, the target '__build'
> > did not run due to errors found in regulator/fixed-regulator.yaml and
> > arm/allwinner,sun4i-a10-csi.yaml.
> 
> Fixes for those are still pending in -next. Use 'make -k' and ignore those.
> 
> >
> > I recall seeing something about the maxItems requirement over regulator
> > supplies being changed on the iio mailing list, so I updated my repo
> > locally, cloned and reinstalled the dt-schema toolset. However, I still
> > can't make it go through the '__build' target.
> >
> > Python 3.7.5rc1 is my default python and I got the following pip3
> > packages installed:
> >
> > ruamel.yaml        0.16.5
> > ruamel.yaml.clib   0.2.0
> > rfc3987            1.3.8
> > jsonschema         3.0.1
> > dtschema           0.0.1  at $HOME/<iio repo dir>/dt-schema
> >
> > Debian Bullseye packages installed:
> > python3-yaml/testing,now 5.1.2-1
> > libyaml-dev/testing,now 0.2.2-1
> >
> > I was only able to run DTC after installing the libyaml-dev package, so
> > I think it might be worth to add it to the project dependencies at
> > https://github.com/robherring/dt-schema.
> 
> Strictly speaking, it's not a dependency for dt-schema. It's
> documented in Documentation/devicetree/writing-schema.rst. I've added
> a pointer to that in bindings/submitting-patches.txt. I'm not sure how
> else to make it more obvious.
> 
> BTW, You will get a useful error message if libyaml is missing when
> building 'make dtbs_check'. I need to make that work for
> dt_binding_check.
> 
> > apt-get install libyaml-dev
> 
> You need the lib too, but that tends to already be installed. IIRC,
> installing the headers doesn't install the lib automatically.
> 
> In any case, I wanted to avoid putting in distro specific instructions
> in the kernel.
> 
> Rob
> 
> -- 
> You received this message because you are subscribed to the Google Groups "Kernel USP" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to kernel-usp+unsubscribe@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/kernel-usp/CAL_JsqLf8kpOu0MQN-TAhQkiZCGfMKWmztnHNo%2B2BAVqfX8yGQ%40mail.gmail.com.