mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/
synced 2025-04-19 20:58:31 +09:00
c26b0854eb
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> Tested-by: David Lechner <dlechner@baylibre.com> Link: https://patch.msgid.link/20250109-ad4695-oversampling-v2-2-a46ac487082c@baylibre.com Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
270 lines
9.4 KiB
ReStructuredText
270 lines
9.4 KiB
ReStructuredText
.. SPDX-License-Identifier: GPL-2.0-only
|
||
|
||
=============
|
||
AD4695 driver
|
||
=============
|
||
|
||
ADC driver for Analog Devices Inc. AD4695 and similar devices. The module name
|
||
is ``ad4695``.
|
||
|
||
|
||
Supported devices
|
||
=================
|
||
|
||
The following chips are supported by this driver:
|
||
|
||
* `AD4695 <https://www.analog.com/AD4695>`_
|
||
* `AD4696 <https://www.analog.com/AD4696>`_
|
||
* `AD4697 <https://www.analog.com/AD4697>`_
|
||
* `AD4698 <https://www.analog.com/AD4698>`_
|
||
|
||
|
||
Supported features
|
||
==================
|
||
|
||
SPI wiring modes
|
||
----------------
|
||
|
||
The driver currently supports the following SPI wiring configuration:
|
||
|
||
4-wire mode
|
||
^^^^^^^^^^^
|
||
|
||
In this mode, CNV and CS are tied together and there is a single SDO line.
|
||
|
||
.. code-block::
|
||
|
||
+-------------+ +-------------+
|
||
| CS |<-+------| CS |
|
||
| CNV |<-+ | |
|
||
| ADC | | HOST |
|
||
| | | |
|
||
| SDI |<--------| SDO |
|
||
| SDO |-------->| SDI |
|
||
| SCLK |<--------| SCLK |
|
||
+-------------+ +-------------+
|
||
|
||
To use this mode, in the device tree, omit the ``cnv-gpios`` and
|
||
``spi-rx-bus-width`` properties.
|
||
|
||
SPI offload wiring
|
||
^^^^^^^^^^^^^^^^^^
|
||
|
||
When used with a SPI offload, the supported wiring configuration is:
|
||
|
||
.. code-block::
|
||
|
||
+-------------+ +-------------+
|
||
| GP0/BUSY |-------->| TRIGGER |
|
||
| CS |<--------| CS |
|
||
| | | |
|
||
| ADC | | SPI |
|
||
| | | |
|
||
| SDI |<--------| SDO |
|
||
| SDO |-------->| SDI |
|
||
| SCLK |<--------| SCLK |
|
||
| | | |
|
||
| | +-------------+
|
||
| CNV |<-----+--| PWM |
|
||
| | +--| GPIO |
|
||
+-------------+ +-------------+
|
||
|
||
In this case, both the ``cnv-gpios`` and ``pwms`` properties are required.
|
||
The ``#trigger-source-cells = <2>`` property is also required to connect back
|
||
to the SPI offload. The SPI offload will have ``trigger-sources`` property
|
||
with cells to indicate the busy signal and which GPx pin is used, e.g
|
||
``<&ad4695 AD4695_TRIGGER_EVENT_BUSY AD4695_TRIGGER_PIN_GP0>``.
|
||
|
||
.. seealso:: `SPI offload support`_
|
||
|
||
Channel configuration
|
||
---------------------
|
||
|
||
Since the chip supports multiple ways to configure each channel, this must be
|
||
described in the device tree based on what is actually wired up to the inputs.
|
||
|
||
There are three typical configurations:
|
||
|
||
An ``INx`` pin is used as the positive input with the ``REFGND``, ``COM`` or
|
||
the next ``INx`` pin as the negative input.
|
||
|
||
Pairing with REFGND
|
||
^^^^^^^^^^^^^^^^^^^
|
||
|
||
Each ``INx`` pin can be used as a pseudo-differential input in conjunction with
|
||
the ``REFGND`` pin. The device tree will look like this:
|
||
|
||
.. code-block::
|
||
|
||
channel@0 {
|
||
reg = <0>; /* IN0 */
|
||
};
|
||
|
||
If no other channel properties are needed (e.g. ``adi,no-high-z``), the channel
|
||
node can be omitted entirely.
|
||
|
||
This will appear on the IIO bus as the ``voltage0`` channel. The processed value
|
||
(*raw × scale*) will be the voltage present on the ``IN0`` pin relative to
|
||
``REFGND``. (Offset is always 0 when pairing with ``REFGND``.)
|
||
|
||
Pairing with COM
|
||
^^^^^^^^^^^^^^^^
|
||
|
||
Each ``INx`` pin can be used as a pseudo-differential input in conjunction with
|
||
the ``COM`` pin. The device tree will look like this:
|
||
|
||
.. code-block::
|
||
|
||
com-supply = <&vref_div_2>;
|
||
|
||
channel@1 {
|
||
reg = <1>; /* IN1 */
|
||
common-mode-channel = <AD4695_COMMON_MODE_COM>;
|
||
bipolar;
|
||
};
|
||
|
||
This will appear on the IIO bus as the ``voltage1`` channel. The processed value
|
||
(*(raw + offset) × scale*) will be the voltage measured on the ``IN1`` pin
|
||
relative to ``REFGND``. (The offset is determined by the ``com-supply`` voltage.)
|
||
|
||
The macro comes from:
|
||
|
||
.. code-block::
|
||
|
||
#include <dt-bindings/iio/adc/adi,ad4695.h>
|
||
|
||
Pairing two INx pins
|
||
^^^^^^^^^^^^^^^^^^^^
|
||
|
||
An even-numbered ``INx`` pin and the following odd-numbered ``INx`` pin can be
|
||
used as a pseudo-differential input. The device tree for using ``IN2`` as the
|
||
positive input and ``IN3`` as the negative input will look like this:
|
||
|
||
.. code-block::
|
||
|
||
in3-supply = <&vref_div_2>;
|
||
|
||
channel@2 {
|
||
reg = <2>; /* IN2 */
|
||
common-mode-channel = <3>; /* IN3 */
|
||
bipolar;
|
||
};
|
||
|
||
This will appear on the IIO bus as the ``voltage2`` channel. The processed value
|
||
(*(raw + offset) × scale*) will be the voltage measured on the ``IN1`` pin
|
||
relative to ``REFGND``. (Offset is determined by the ``in3-supply`` voltage.)
|
||
|
||
VCC supply
|
||
----------
|
||
|
||
The chip supports being powered by an external LDO via the ``VCC`` input or an
|
||
internal LDO via the ``LDO_IN`` input. The driver looks at the device tree to
|
||
determine which is being used. If ``ldo-supply`` is present, then the internal
|
||
LDO is used. If ``vcc-supply`` is present, then the external LDO is used and
|
||
the internal LDO is disabled.
|
||
|
||
Reference voltage
|
||
-----------------
|
||
|
||
The chip supports an external reference voltage via the ``REF`` input or an
|
||
internal buffered reference voltage via the ``REFIN`` input. The driver looks
|
||
at the device tree to determine which is being used. If ``ref-supply`` is
|
||
present, then the external reference voltage is used and the internal buffer is
|
||
disabled. If ``refin-supply`` is present, then the internal buffered reference
|
||
voltage is used.
|
||
|
||
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
|
||
- GPIO support
|
||
- CRC support
|
||
|
||
SPI offload support
|
||
===================
|
||
|
||
To be able to achieve the maximum sample rate, the driver can be used with the
|
||
`AXI SPI Engine`_ to provide SPI offload support.
|
||
|
||
.. _AXI SPI Engine: http://analogdevicesinc.github.io/hdl/projects/ad469x_fmc/index.html
|
||
|
||
.. seealso:: `SPI offload wiring`_
|
||
|
||
When SPI offload is being used, some attributes will be different.
|
||
|
||
* ``trigger`` directory is removed.
|
||
* ``in_voltage0_sampling_frequency`` attributes are added for setting the sample
|
||
rate.
|
||
* ``in_voltage0_sampling_frequency_available`` attributes are added for querying
|
||
the max sample rate.
|
||
* ``timestamp`` channel is removed.
|
||
* Buffer data format may be different compared to when offload is not used,
|
||
e.g. the ``buffer0/in_voltage0_type`` attribute.
|
||
|
||
Device buffers
|
||
==============
|
||
|
||
This driver supports hardware triggered buffers. This uses the "advanced
|
||
sequencer" feature of the chip to trigger a burst of conversions.
|
||
|
||
Also see :doc:`iio_devbuf` for more general information.
|
||
|
||
Effective sample rate for buffered reads
|
||
----------------------------------------
|
||
|
||
When SPI offload is not used, the sample rate is determined by the trigger that
|
||
is manually configured in userspace. All enabled channels will be read in a
|
||
burst when the trigger is received.
|
||
|
||
When SPI offload is used, the sample rate is configured per channel. All
|
||
channels will have the same rate, so only one ``in_voltageY_sampling_frequency``
|
||
attribute needs to be set. Since this rate determines the delay between each
|
||
individual conversion, the effective sample rate for each sample is actually
|
||
the sum of the periods of each enabled channel in a buffered read. In other
|
||
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).
|