[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....@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....@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: linu...@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 <stefa...@analog.com>
--
2.23.0

[Rob Herring]

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.

adc@0

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

Rob

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

[Rob Herring]

On Sat, Oct 19, 2019 at 10:07 AM Marcelo Schmitt
<marcelo....@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

[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

[Rob Herring]

On Tue, Oct 22, 2019 at 9:06 AM Marcelo Schmitt
<marcelo....@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

[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

> --
> 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+...@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.