Re: [PATCH 2/2] doc: iio: ad4695: describe oversampling support

[Jonathan Cameron <jic23@kernel.org>]

On Tue, 17 Dec 2024 16:47:29 -0500
Trevor Gamblin <tgamblin@baylibre.com> wrote:

> Add a section to the ad4695 documentation describing how to use the
> oversampling feature. Also add some clarification on how the
> oversampling ratio influences effective sample rate in the offload
> section.
> 
> Signed-off-by: Trevor Gamblin <tgamblin@baylibre.com>
This describes what I was expecting so all looks good to me.

Obviously need to wait for the spi offload series anyway
so plenty of time for others to take a look.

Thanks

Jonathan

> ---
>  Documentation/iio/ad4695.rst | 36 +++++++++++++++++++++++++++++++++++-
>  1 file changed, 35 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/iio/ad4695.rst b/Documentation/iio/ad4695.rst
> index ead0faadff4b..f40593bcc37d 100644
> --- a/Documentation/iio/ad4695.rst
> +++ b/Documentation/iio/ad4695.rst
> @@ -179,12 +179,38 @@ Gain/offset calibration
>  System calibration is supported using the channel gain and offset registers via
>  the ``calibscale`` and ``calibbias`` attributes respectively.
>  
> +Oversampling
> +------------
> +
> +The chip supports per-channel oversampling when SPI offload is being used, with
> +available oversampling ratios (OSR) of 1 (default), 4, 16, and 64.  Enabling
> +oversampling on a channel raises the effective number of bits of sampled data to
> +17 (OSR == 4), 18 (16), or 19 (64), respectively. This can be set via the
> +``oversampling_ratio`` attribute.
> +
> +Setting the oversampling ratio for a channel also changes the sample rate for
> +that channel, since it requires multiple conversions per 1 sample. Specifically,
> +the new sampling frequency is the PWM sampling frequency divided by the
> +particular OSR. This is set automatically by the driver when setting the
> +``oversampling_ratio`` attribute. For example, if the device's current
> +``sampling_frequency`` is 10000 and an OSR of 4 is set on channel ``voltage0``,
> +the new reported sampling rate for that channel will be 2500 (ignoring PWM API
> +rounding), while all others will remain at 10000.  Subsequently setting the
> +sampling frequency to a higher value on that channel will adjust the CNV trigger
> +period for all channels, e.g. if ``voltage0``'s sampling frequency is adjusted
> +from 2500 (with an OSR of 4) to 10000, the value reported by
> +``in_voltage0_sampling_frequency`` will be 10000, but all other channels will
> +now report 40000.

Ah. I forgot there is another series in flight for this and was going to say
that we needed a statement on the frequencies being a common control.
That is there in the spi offload series so all good!

> +
> +For simplicity, the sampling frequency of the device should be set (considering
> +the highest desired OSR value to be used) first, before configuring oversampling
> +for specific channels.
> +
>  Unimplemented features
>  ----------------------
>  
>  - Additional wiring modes
>  - Threshold events
> -- Oversampling
>  - GPIO support
>  - CRC support
>  
> @@ -233,3 +259,11 @@ words, it is the value of the ``in_voltageY_sampling_frequency`` attribute
>  divided by the number of enabled channels. So if 4 channels are enabled, with
>  the ``in_voltageY_sampling_frequency`` attributes set to 1 MHz, the effective
>  sample rate is 250 kHz.
> +
> +With oversampling enabled, the effective sample rate also depends on the OSR
> +assigned to each channel. For example, if one of the 4 channels mentioned in the
> +previous case is configured with an OSR of 4, the effective sample rate for that
> +channel becomes (1 MHz / 4 ) = 250 kHz. The effective sample rate for all
> +four channels is then 1 / ( (3 / 1 MHz) + ( 1 / 250 kHz) ) ~= 142.9 kHz. Note
> +that in this case "sample" refers to one read of all enabled channels (i.e. one
> +full cycle through the auto-sequencer).
>