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@xxxxxxxxxxxx> --- 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. + +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). -- 2.39.5
