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

[Jonathan Cameron <jic23@kernel.org>]

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
>