Re: [PATCH v4 01/11] dt-bindings: iio: adc: Add AD4170

[Marcelo Schmitt <marcelo.schmitt1@gmail.com>]

On 06/07, Jonathan Cameron wrote:
> On Mon, 2 Jun 2025 08:36:24 -0300
> Marcelo Schmitt <marcelo.schmitt@analog.com> wrote:
> 
> > Add device tree documentation for AD4170 and similar sigma-delta ADCs.
> > The AD4170 is a 24-bit, multichannel, sigma-delta ADC.
> > 
...
> > +
> > +$defs:
> > +  reference-buffer:
> > +    description: |
> > +      Enable precharge buffer, full buffer, or skip reference buffering of
> > +      the positive/negative voltage reference. Because the output impedance
> > +      of the source driving the voltage reference inputs may be dynamic, RC
> 
> RC?

Stands for the combination of resistive and capacitive elements in the path
between the reference supply output and AD4170 REFINn± inputs.

Datasheet Figure 76 shows an example with only capacitive elements, but it could
have resistive elements too.
https://www.analog.com/media/en/technical-documentation/data-sheets/ad4170-4.pdf#unique_75_Connect_42_ID8013

I will rephrase to make that clearer. This is probably too long and detailed
description for a dt property. I can't figure out how to put that in a more
concise and meaningful way, though. 

> 
> > +      combinations of those inputs can cause DC gain errors if the reference
> > +      inputs go unbuffered into the ADC. Enable reference buffering if the
> > +      provided reference source has dynamic high impedance output. Note the
> > +      absolute voltage allowed on REFINn+ and REFINn- inputs is from
> > +      AVSS - 50 mV to AVDD + 50 mV when the reference buffers are disabled
> > +      but narrows to AVSS to AVDD when reference buffering is enabled or in
> > +      precharge mode. The valid options for this property are:
> > +      0: Reference precharge buffer.
> > +      1: Full reference buffering.
> > +      2: Bypass reference buffers (buffering disabled).
> > +    $ref: /schemas/types.yaml#/definitions/uint32
> > +    enum: [0, 1, 2]
> > +    default: 1
> 
...
> > +
> > +      adi,excitation-current-0-microamp:
> > +        description:
> > +          Excitation current in microamperes to be applied to pin specified in
> > +          adi,excitation-pin-0 while this channel is active.
> > +        enum: [0, 10, 50, 100, 250, 500, 1000, 1500]
> 
> What motivated mix of using $ref and here where there is a lot of repetition?
> I don't mind which approach is used, but a mix seems the worst option.
> 

Because 
$defs:
  ...
  adi,excitation-current-n-microamp:
    description:
      Excitation current in microamperes to be applied to pin specified in
      adi,excitation-pin-0 while this channel is active.
    enum: [0, 10, 50, 100, 250, 500, 1000, 1500]
    default: 0

patternProperties:
  ...
      adi,excitation-current-0-microamp:
        $ref: '#/$defs/adi,excitation-current-n-microamp'


triggers dt_binding_check warn:
	patternProperties:^channel@[0-9a-f]$:properties:adi,excitation-current-0-microamp: '$ref' should not be valid under {'const': '$ref'}
	hint: Standard unit suffix properties don't need a type $ref


Thanks,
Marcelo