From: Trevor Gamblin Date: Thu, 9 Jan 2025 18:47:24 +0000 (-0500) Subject: doc: iio: ad4695: describe oversampling support X-Git-Tag: v6.15-rc1~78^2~8^2~155 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=c26b0854eb2b7301dee83ec6c190bc94a364e910;p=thirdparty%2Fkernel%2Flinux.git doc: iio: ad4695: describe oversampling support 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 Tested-by: David Lechner Link: https://patch.msgid.link/20250109-ad4695-oversampling-v2-2-a46ac487082c@baylibre.com Signed-off-by: Jonathan Cameron --- diff --git a/Documentation/iio/ad4695.rst b/Documentation/iio/ad4695.rst index ead0faadff4b5..f40593bcc37da 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. + +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).