[PATCH v3 1/2] dt-bindings: iio: adc: ti,ads7038: Add description for ADS7038

[PATCH v3 1/2] dt-bindings: iio: adc: ti,ads7038: Add description for ADS7038

[werneazc]

From: Andre Werner <andre.werner@systec-electronic.com>

Add basic description for ADS7038 ADC devices.
The devicetree adds the following device specific options:

- average-samples: Program device's programmable average filter.
- crc-enabled: Enable the CRC check for SPI transfers. Sadly, this
  option has currently no effect in the driver.
- status-enabled: Enable the appending of the device's status on the
  measure value transmission.
- gpio-controller: Sadly function not implemented yet in the driver.

Signed-off-by: Andre Werner <andre.werner@systec-electronic.com>
---
v3:
- Delete ADS7138 compatible and comments.
- Add options for CRC, status and average samples as well as
  gpio-controller.
- Update example.
---
 .../bindings/iio/adc/ti,ads7038.yaml          | 84 +++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml

diff --git a/Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml b/Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml
new file mode 100644
index 000000000000..323f86c5e682
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml
@@ -0,0 +1,84 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/ti,ads7038.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments ADS7038 and similar ADCs
+
+maintainers:
+  - Andre Werner <andre.werner@systec-electronic.com>
+
+description: |
+  Family of 7 channel, 12 bit ADCs with SPI interface.
+
+  Datasheet: https://www.ti.com/lit/gpn/ads7038
+
+properties:
+  compatible:
+    enum:
+      - ti,ads7038
+
+  reg:
+    maxItems: 1
+
+  spi-max-frequency:
+    maximum: 60000000
+
+  avdd-supply:
+    description: Analog supply voltage, also used as the reference voltage to the ADC.
+
+  dvdd-supply:
+    description: Digital I/O supply voltage.
+
+  average-samples:
+    description: |
+      If specified ADC is configured for avaraging measurements (OSR_CFG Register).
+      This effects output format for measurement and sampling time.
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum: [0,1,2,3,4,5,6,7]
+
+  status-enabled:
+    description: |
+      If specified ADC transmits chip status (DATA_CFG Register).
+
+  crc-enabled:
+    description: |
+      Checking the integrity of the data bits exchanged over
+      SPI interface (GENERAL_CFG Register).
+
+  gpio-controller:
+    const: true
+    decription: Marks the device node as a GPIO controller.
+
+  "#gpio-cells":
+    const: 2
+    description: Should be 2. See gpio.txt in this directory for a
+                 description of the cells format.
+
+required:
+  - compatible
+  - reg
+  - avdd-supply
+  - dvdd-supply
+  - gpio-controller
+  - #gpio-cells
+
+additionalProperties: false
+
+examples:
+  - |
+    spi {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        adc@0 {
+            compatible = "ti,ads7038";
+            reg = <0>;
+            avdd-supply = <&refin_avdd_supply>;
+            avdd-supply = <&refin_dvdd_supply>;
+            spi-max-frequency = <10000000>;
+            gpio-controller;
+            #gpio-cells = <2>;
+        };
+    };
-- 
2.42.0

Re: [PATCH v3 1/2] dt-bindings: iio: adc: ti,ads7038: Add description for ADS7038

[Rob Herring]

On Sun, 15 Oct 2023 20:32:20 +0200, werneazc@gmail.com wrote:
> From: Andre Werner <andre.werner@systec-electronic.com>
> 
> Add basic description for ADS7038 ADC devices.
> The devicetree adds the following device specific options:
> 
> - average-samples: Program device's programmable average filter.
> - crc-enabled: Enable the CRC check for SPI transfers. Sadly, this
>   option has currently no effect in the driver.
> - status-enabled: Enable the appending of the device's status on the
>   measure value transmission.
> - gpio-controller: Sadly function not implemented yet in the driver.
> 
> Signed-off-by: Andre Werner <andre.werner@systec-electronic.com>
> ---
> v3:
> - Delete ADS7138 compatible and comments.
> - Add options for CRC, status and average samples as well as
>   gpio-controller.
> - Update example.
> ---
>  .../bindings/iio/adc/ti,ads7038.yaml          | 84 +++++++++++++++++++
>  1 file changed, 84 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/iio/adc/ti,ads7038.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:
./Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml:39:14: [warning] too few spaces after comma (commas)
./Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml:39:16: [warning] too few spaces after comma (commas)
./Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml:39:18: [warning] too few spaces after comma (commas)
./Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml:39:20: [warning] too few spaces after comma (commas)
./Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml:39:22: [warning] too few spaces after comma (commas)
./Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml:39:24: [warning] too few spaces after comma (commas)
./Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml:39:26: [warning] too few spaces after comma (commas)
./Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml:65:6: [error] missing starting space in comment (comments)

dtschema/dtc warnings/errors:
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml: required:5: None is not of type 'string'
	from schema $id: http://json-schema.org/draft-07/schema#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml: properties:gpio-controller:const: True is not of type 'integer', 'string'
	from schema $id: http://devicetree.org/meta-schemas/keywords.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml: properties:gpio-controller: 'anyOf' conditional failed, one must be fixed:
	'decription' is not one of ['$ref', 'additionalItems', 'additionalProperties', 'allOf', 'anyOf', 'const', 'contains', 'default', 'dependencies', 'dependentRequired', 'dependentSchemas', 'deprecated', 'description', 'else', 'enum', 'exclusiveMaximum', 'exclusiveMinimum', 'items', 'if', 'minItems', 'minimum', 'maxItems', 'maximum', 'multipleOf', 'not', 'oneOf', 'pattern', 'patternProperties', 'properties', 'required', 'then', 'typeSize', 'unevaluatedProperties', 'uniqueItems']
	'type' was expected
	from schema $id: http://devicetree.org/meta-schemas/keywords.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml: properties:gpio-controller: Additional properties are not allowed ('const', 'decription' were unexpected)
	from schema $id: http://devicetree.org/meta-schemas/boolean.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml: ignoring, error in schema: required: 5
Documentation/devicetree/bindings/iio/adc/ti,ads7038.example.dts:25.17-52: ERROR (duplicate_property_names): /example-0/spi/adc@0:avdd-supply: Duplicate property name
ERROR: Input tree has errors, aborting (use -f to force output)
make[2]: *** [scripts/Makefile.lib:419: Documentation/devicetree/bindings/iio/adc/ti,ads7038.example.dtb] Error 2
make[2]: *** Waiting for unfinished jobs....
make[1]: *** [/builds/robherring/dt-review-ci/linux/Makefile:1427: dt_binding_check] Error 2
make: *** [Makefile:234: __sub-make] Error 2

doc reference errors (make refcheckdocs):

See https://patchwork.ozlabs.org/project/devicetree-bindings/patch/20231015184517.3582-1-andre.werner@systec-electronic.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.

[PATCH v3 1/2] dt-bindings: iio: adc: ti,ads7038: Add description for ADS7038

[werneazc]

From: Andre Werner <andre.werner@systec-electronic.com>

Add basic description for ADS7038 ADC devices.
The devicetree adds the following device specific options:

- average-samples: Program device's programmable average filter.
- crc-enabled: Enable the CRC check for SPI transfers. Sadly, this
  option has currently no effect in the driver.
- status-enabled: Enable the appending of the device's status on the
  measure value transmission.
- gpio-controller: Sadly function not implemented yet in the driver.

Signed-off-by: Andre Werner <andre.werner@systec-electronic.com>
---
v3
- Delete ADS7138 compatible and comments.
- Add options for CRC, status and average samples as well as
  gpio-controller.
- Update example.
- add regulator for digital IO voltage.
---
 .../bindings/iio/adc/ti,ads7038.yaml          | 83 +++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml

diff --git a/Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml b/Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml
new file mode 100644
index 000000000000..fc1054ca93f7
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml
@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/ti,ads7038.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments ADS7038 and similar ADCs
+
+maintainers:
+  - Andre Werner <andre.werner@systec-electronic.com>
+
+description: |
+  Family of 7 channel, 12 bit ADCs with SPI interface.
+
+  Datasheet: https://www.ti.com/lit/gpn/ads7038
+
+properties:
+  compatible:
+    enum:
+      - ti,ads7038
+
+  reg:
+    maxItems: 1
+
+  spi-max-frequency:
+    maximum: 60000000
+
+  avdd-supply:
+    description: Analog supply voltage, also used as the reference voltage to the ADC.
+
+  dvdd-supply:
+    description: Digital I/O supply voltage.
+
+  average-samples:
+    description: |
+      If specified ADC is configured for avaraging measurements (OSR_CFG Register).
+      This effects output format for measurement and sampling time.
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum: [0, 1, 2, 3, 4, 5, 6, 7]
+
+  status-enabled:
+    description: |
+      If specified ADC transmits chip status (DATA_CFG Register).
+
+  crc-enabled:
+    description: |
+      Checking the integrity of the data bits exchanged over
+      SPI interface (GENERAL_CFG Register).
+
+  gpio-controller: true
+
+  "#gpio-cells":
+    const: 2
+    description: |
+      Should be 2. See gpio.txt in this directory for a
+      description of the cells format.
+
+required:
+  - compatible
+  - reg
+  - avdd-supply
+  - dvdd-supply
+  - gpio-controller
+  - "#gpio-cells"
+
+additionalProperties: false
+
+examples:
+  - |
+    spi {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        adc@0 {
+            compatible = "ti,ads7038";
+            reg = <0>;
+            avdd-supply = <&refin_avdd_supply>;
+            dvdd-supply = <&refin_dvdd_supply>;
+            spi-max-frequency = <10000000>;
+            gpio-controller;
+            #gpio-cells = <2>;
+        };
+    };
-- 
2.42.0

Re: [PATCH v3 1/2] dt-bindings: iio: adc: ti,ads7038: Add description for ADS7038

[Krzysztof Kozlowski]

On 16/10/2023 09:02, werneazc@gmail.com wrote:
> From: Andre Werner <andre.werner@systec-electronic.com>
> 
> Add basic description for ADS7038 ADC devices.
> The devicetree adds the following device specific options:
> 
> - average-samples: Program device's programmable average filter.
> - crc-enabled: Enable the CRC check for SPI transfers. Sadly, this
>   option has currently no effect in the driver.
> - status-enabled: Enable the appending of the device's status on the
>   measure value transmission.
> - gpio-controller: Sadly function not implemented yet in the driver.
> 
> Signed-off-by: Andre Werner <andre.werner@systec-electronic.com>
> ---
> v3
> - Delete ADS7138 compatible and comments.
> - Add options for CRC, status and average samples as well as
>   gpio-controller.
> - Update example.
> - add regulator for digital IO voltage.

You received several build errors before. Did you really test it now,
because looks like not.

> ---
>  .../bindings/iio/adc/ti,ads7038.yaml          | 83 +++++++++++++++++++
>  1 file changed, 83 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml
> 
> diff --git a/Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml b/Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml
> new file mode 100644
> index 000000000000..fc1054ca93f7
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml
> @@ -0,0 +1,83 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/iio/adc/ti,ads7038.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Texas Instruments ADS7038 and similar ADCs
> +
> +maintainers:
> +  - Andre Werner <andre.werner@systec-electronic.com>
> +
> +description: |
> +  Family of 7 channel, 12 bit ADCs with SPI interface.
> +
> +  Datasheet: https://www.ti.com/lit/gpn/ads7038
> +
> +properties:
> +  compatible:
> +    enum:
> +      - ti,ads7038
> +
> +  reg:
> +    maxItems: 1
> +
> +  spi-max-frequency:
> +    maximum: 60000000
> +
> +  avdd-supply:
> +    description: Analog supply voltage, also used as the reference voltage to the ADC.
> +
> +  dvdd-supply:
> +    description: Digital I/O supply voltage.
> +
> +  average-samples:
> +    description: |
> +      If specified ADC is configured for avaraging measurements (OSR_CFG Register).
> +      This effects output format for measurement and sampling time.
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    enum: [0, 1, 2, 3, 4, 5, 6, 7]
> +
> +  status-enabled:
> +    description: |

Do not need '|' unless you need to preserve formatting.

> +      If specified ADC transmits chip status (DATA_CFG Register).

Missing type.

You described the desired Linux feature or behavior, not the actual
hardware. The bindings are about the latter, so instead you need to
rephrase the property and its description to match actual hardware
capabilities/features/configuration etc. Why this is a property of a board?

> +
> +  crc-enabled:
> +    description: |
> +      Checking the integrity of the data bits exchanged over
> +      SPI interface (GENERAL_CFG Register).

Same comment.



Best regards,
Krzysztof

Re: [PATCH v3 1/2] dt-bindings: iio: adc: ti,ads7038: Add description for ADS7038

[Jonathan Cameron]

On Mon, 16 Oct 2023 09:18:46 +0200
Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> wrote:

> On 16/10/2023 09:02, werneazc@gmail.com wrote:
> > From: Andre Werner <andre.werner@systec-electronic.com>
> > 
> > Add basic description for ADS7038 ADC devices.
> > The devicetree adds the following device specific options:
> > 
> > - average-samples: Program device's programmable average filter.
> > - crc-enabled: Enable the CRC check for SPI transfers. Sadly, this
> >   option has currently no effect in the driver.
> > - status-enabled: Enable the appending of the device's status on the
> >   measure value transmission.
> > - gpio-controller: Sadly function not implemented yet in the driver.
> > 
> > Signed-off-by: Andre Werner <andre.werner@systec-electronic.com>
> > ---
> > v3
> > - Delete ADS7138 compatible and comments.
> > - Add options for CRC, status and average samples as well as
> >   gpio-controller.
> > - Update example.
> > - add regulator for digital IO voltage.  
> 
> You received several build errors before. Did you really test it now,
> because looks like not.
> 
> > ---
> >  .../bindings/iio/adc/ti,ads7038.yaml          | 83 +++++++++++++++++++
> >  1 file changed, 83 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml
> > 
> > diff --git a/Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml b/Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml
> > new file mode 100644
> > index 000000000000..fc1054ca93f7
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml
> > @@ -0,0 +1,83 @@
> > +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/iio/adc/ti,ads7038.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Texas Instruments ADS7038 and similar ADCs
> > +
> > +maintainers:
> > +  - Andre Werner <andre.werner@systec-electronic.com>
> > +
> > +description: |
> > +  Family of 7 channel, 12 bit ADCs with SPI interface.
> > +
> > +  Datasheet: https://www.ti.com/lit/gpn/ads7038
> > +
> > +properties:
> > +  compatible:
> > +    enum:
> > +      - ti,ads7038
> > +
> > +  reg:
> > +    maxItems: 1
> > +
> > +  spi-max-frequency:
> > +    maximum: 60000000
> > +
> > +  avdd-supply:
> > +    description: Analog supply voltage, also used as the reference voltage to the ADC.
> > +
> > +  dvdd-supply:
> > +    description: Digital I/O supply voltage.
> > +
> > +  average-samples:
> > +    description: |
> > +      If specified ADC is configured for avaraging measurements (OSR_CFG Register).
> > +      This effects output format for measurement and sampling time.
> > +    $ref: /schemas/types.yaml#/definitions/uint32
> > +    enum: [0, 1, 2, 3, 4, 5, 6, 7]
> > +
> > +  status-enabled:
> > +    description: |  
> 
> Do not need '|' unless you need to preserve formatting.
> 
> > +      If specified ADC transmits chip status (DATA_CFG Register).  
> 
> Missing type.
> 
> You described the desired Linux feature or behavior, not the actual
> hardware. The bindings are about the latter, so instead you need to
> rephrase the property and its description to match actual hardware
> capabilities/features/configuration etc. Why this is a property of a board?

Agreed - if this information is useful always transmit or enabling when
whatever feature makes it useful is enabled by the driver / userspace interaction.
If it's not useful don't :)

> 
> > +
> > +  crc-enabled:
> > +    description: |
> > +      Checking the integrity of the data bits exchanged over
> > +      SPI interface (GENERAL_CFG Register).  
> 
> Same comment.
Even if you do want to make this controllable from userspace, we will need
a strong argument for why.  People rarely buy CRC capable chips and not
want it turned on.  I'd just always turn it on.

> 
> 
> 
> Best regards,
> Krzysztof
> 

Re: [PATCH v3 1/2] dt-bindings: iio: adc: ti,ads7038: Add description for ADS7038

[Rob Herring]

On Mon, 16 Oct 2023 09:02:04 +0200, werneazc@gmail.com wrote:
> From: Andre Werner <andre.werner@systec-electronic.com>
> 
> Add basic description for ADS7038 ADC devices.
> The devicetree adds the following device specific options:
> 
> - average-samples: Program device's programmable average filter.
> - crc-enabled: Enable the CRC check for SPI transfers. Sadly, this
>   option has currently no effect in the driver.
> - status-enabled: Enable the appending of the device's status on the
>   measure value transmission.
> - gpio-controller: Sadly function not implemented yet in the driver.
> 
> Signed-off-by: Andre Werner <andre.werner@systec-electronic.com>
> ---
> v3
> - Delete ADS7138 compatible and comments.
> - Add options for CRC, status and average samples as well as
>   gpio-controller.
> - Update example.
> - add regulator for digital IO voltage.
> ---
>  .../bindings/iio/adc/ti,ads7038.yaml          | 83 +++++++++++++++++++
>  1 file changed, 83 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/iio/adc/ti,ads7038.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:
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml: status-enabled: missing type definition
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/iio/adc/ti,ads7038.yaml: crc-enabled: missing type definition

doc reference errors (make refcheckdocs):

See https://patchwork.ozlabs.org/project/devicetree-bindings/patch/20231016070318.28355-1-andre.werner@systec-electronic.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.