Re: [PATCH v11 6/6] docs: iio: adc: ad4691: add driver documentation

[sashiko-bot@kernel.org]

Thank you for your contribution! Sashiko AI review found 2 potential issue(s) to consider:
- [High] IIO ABI violation and architectural anti-pattern regarding per-channel attributes implicitly mutating shared global hardware state.
- [Low] Documentation inaccurately attributes the handling of the `reset-gpios` property to the reset controller framework.
--

commit 503be5723d887e52797574aecacc47811e35f4b5
Author: Radu Sabau <radu.sabau@analog.com>

docs: iio: adc: ad4691: add driver documentation

This commit adds RST documentation for the AD4691 family ADC driver,
covering supported devices, IIO channels, operating modes, oversampling,
reference voltage, LDO supply, reset, GP pins, SPI offload support,
and buffer data format.

> diff --git a/Documentation/iio/ad4691.rst b/Documentation/iio/ad4691.rst
> new file mode 100644
> index 0000000000000..84492ef7a5d61
> --- /dev/null
> +++ b/Documentation/iio/ad4691.rst
[ ... ]
> +Oversampling
> +============
> +
> +In CNV Burst Mode each channel has an independent hardware accumulator that
> +averages a configurable number of successive conversions. The result is always
> +returned as a 16-bit mean, so ``realbits`` and ``storagebits`` are unaffected
> +by the oversampling ratio. Valid ratios are 1, 2, 4, 8, 16 and 32; the default
> +is 1 (no averaging). Oversampling is not supported in Manual Mode.
[ ... ]
> +Writing ``oversampling_ratio`` stores the new depth for that channel and
> +snaps the internal oscillator to the largest valid table entry that is both
> +less than or equal to ``old_effective_rate × new_osr`` and evenly divisible
> +by ``new_osr``. This preserves an integer read-back of
> +``in_voltageN_sampling_frequency`` after the change and keeps the oscillator
> +as close as possible to the previous effective rate.
> +
> +All channels share one internal oscillator. Writing ``sampling_frequency`` for
> +any channel updates the oscillator and therefore affects the effective rate
> +read back from all other channels.

Does this break IIO ABI semantics? Attributes that control shared hardware
state must be exposed as shared attributes, such as shared_by_type, rather
than per-channel attributes.

If per-channel attributes implicitly mutate a global clock, could this
break deterministic configuration? Userspace initialization scripts
attempting to configure channels sequentially will experience unpredictable
side-effects, as configuring one channel's OSR or frequency will silently
overwrite the shared oscillator state configured by a previous channel.

[ ... ]
> +Reset
> +=====
> +
> +The driver supports two reset mechanisms:
> +
> +* **Hardware reset** (``reset-gpios`` in device tree): asserted at probe by
> +  the reset controller framework.

Is this description accurate regarding the reset controller framework?

The reset-gpios property is parsed and handled by the GPIO subsystem, while
the reset controller framework manages the resets property. Could this
conflate the two subsystems and mislead users about which bindings are used?

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260515-ad4692-multichannel-sar-adc-driver-v11-0-eab27d852ac2@analog.com?part=6