diff options
Diffstat (limited to 'Documentation/iio')
| -rw-r--r-- | Documentation/iio/ad3552r.rst | 72 | ||||
| -rw-r--r-- | Documentation/iio/ad4000.rst | 91 | ||||
| -rw-r--r-- | Documentation/iio/ad4030.rst | 180 | ||||
| -rw-r--r-- | Documentation/iio/ad4695.rst | 104 | ||||
| -rw-r--r-- | Documentation/iio/ad7191.rst | 119 | ||||
| -rw-r--r-- | Documentation/iio/ad7380.rst | 63 | ||||
| -rw-r--r-- | Documentation/iio/ad7606.rst | 45 | ||||
| -rw-r--r-- | Documentation/iio/ad7944.rst | 24 | ||||
| -rw-r--r-- | Documentation/iio/adis16550.rst | 376 | ||||
| -rw-r--r-- | Documentation/iio/adxl380.rst | 2 | ||||
| -rw-r--r-- | Documentation/iio/iio_adc.rst | 305 | ||||
| -rw-r--r-- | Documentation/iio/iio_devbuf.rst | 2 | ||||
| -rw-r--r-- | Documentation/iio/index.rst | 5 |
13 files changed, 1380 insertions, 8 deletions
diff --git a/Documentation/iio/ad3552r.rst b/Documentation/iio/ad3552r.rst new file mode 100644 index 000000000000..f5d59e4e86c7 --- /dev/null +++ b/Documentation/iio/ad3552r.rst @@ -0,0 +1,72 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +============== +AD3552R driver +============== + +Device driver for Analog Devices Inc. AD35XXR series of DACs. The module name +is ``ad3552r``. +With the same module name, two different driver variants are available, the +``generic spi`` variant, to be used with any classic SPI controllers, and the +``hs`` (high speed) variant, for an ADI ``axi-dac`` (IP core) based controller +that allows to reach the maximum sample rate supported from the DACs, using the +DMA transfer and all the SPI lines available (D/QDSPI).. +The high speed driver variant is intended to be used with the ``adi-axi-dac`` +backend support enabled, that is enabled by default when the driver is selected. + +Supported devices +================= + +* `AD3541R <https://www.analog.com/en/products/ad3541r.html>`_ +* `AD3542R <https://www.analog.com/en/products/ad3542r.html>`_ +* `AD3551R <https://www.analog.com/en/products/ad3551r.html>`_ +* `AD3552R <https://www.analog.com/en/products/ad3552r.html>`_ + +Wiring connections +================== + +Generic SPI +----------- +Use the classic SPI S_CLK/CS/SDO/SDI connection. + +High speed (using axi-dac backend) +---------------------------------- + +:: + + .-----------------. .-------. + | |--- D/QSPI -----| | + | DAC IP CORE |--- SPI S_CLK --| DAC | + | |--- SPI CS -----| | + | |--- LDAC -------| | + | |--- RESET ------| | + |_________________| |_______| + + +High speed features +=================== + +Device attributes +----------------- + +The following table shows the ad35xxr related device debug files, found in the +specific debugfs path ``/sys/kernel/debug/iio/iio:deviceX``. + ++-----------------------+------------------------------------------------------+ +| Debugfs device files | Description | ++-----------------------+------------------------------------------------------+ +| data_source | The used data source, as | +| | ``normal``, ``ramp-16bit``, etc. | ++-----------------------+------------------------------------------------------+ +| data_source_available | The available data sources. | ++-----------------------+------------------------------------------------------+ + +Usage examples +-------------- + +. code-block:: bash + root:/sys/bus/iio/devices/iio:device0# cat data_source + normal + root:/sys/bus/iio/devices/iio:device0# echo -n ramp-16bit > data_source + root:/sys/bus/iio/devices/iio:device0# cat data_source + ramp-16bit diff --git a/Documentation/iio/ad4000.rst b/Documentation/iio/ad4000.rst index de8fd3ae6e62..c1d04d3436d2 100644 --- a/Documentation/iio/ad4000.rst +++ b/Documentation/iio/ad4000.rst @@ -4,7 +4,7 @@ AD4000 driver ============= -Device driver for Analog Devices Inc. AD4000 series of ADCs. +Device driver for Analog Devices Inc. AD4000 series of ADCs and similar devices. Supported devices ================= @@ -25,6 +25,21 @@ Supported devices * `AD4022 <https://www.analog.com/AD4022>`_ * `ADAQ4001 <https://www.analog.com/ADAQ4001>`_ * `ADAQ4003 <https://www.analog.com/ADAQ4003>`_ +* `AD7685 <https://www.analog.com/AD7685>`_ +* `AD7686 <https://www.analog.com/AD7686>`_ +* `AD7687 <https://www.analog.com/AD7687>`_ +* `AD7688 <https://www.analog.com/AD7688>`_ +* `AD7690 <https://www.analog.com/AD7690>`_ +* `AD7691 <https://www.analog.com/AD7691>`_ +* `AD7693 <https://www.analog.com/AD7693>`_ +* `AD7942 <https://www.analog.com/AD7942>`_ +* `AD7946 <https://www.analog.com/AD7946>`_ +* `AD7980 <https://www.analog.com/AD7980>`_ +* `AD7982 <https://www.analog.com/AD7982>`_ +* `AD7983 <https://www.analog.com/AD7983>`_ +* `AD7984 <https://www.analog.com/AD7984>`_ +* `AD7988-1 <https://www.analog.com/AD7988-1>`_ +* `AD7988-5 <https://www.analog.com/AD7988-5>`_ Wiring connections ------------------ @@ -129,3 +144,77 @@ Set ``adi,sdi-pin`` to ``"cs"`` to select this mode. ^ | | +--------------------| SCLK | +-------------+ + +IIO Device characteristics +========================== + +The AD4000 series driver supports differential and pseudo-differential ADCs. + +The span compression feature available in AD4000 series devices can be +enabled/disabled by changing the ``_scale_available`` attribute of the voltage +channel. Note that span compression configuration requires writing to AD4000 +configuration register, which is only possible when the ADC is wired in 3-wire +turbo mode, and the SPI controller is ``SPI_MOSI_IDLE_HIGH`` capable. If those +conditions are not met, no ``_scale_available`` attribute is provided. + +Besides that, differential and pseudo-differential voltage channels present +slightly different sysfs interfaces. + +Pseudo-differential ADCs +------------------------ + +Typical voltage channel attributes of a pseudo-differential AD4000 series device: + ++-------------------------------------------+------------------------------------------+ +| Voltage Channel Attributes | Description | ++===========================================+==========================================+ +| ``in_voltage0_raw`` | Raw ADC output code. | ++-------------------------------------------+------------------------------------------+ +| ``in_voltage0_offset`` | Offset to convert raw value to mV. | ++-------------------------------------------+------------------------------------------+ +| ``in_voltage0_scale`` | Scale factor to convert raw value to mV. | ++-------------------------------------------+------------------------------------------+ +| ``in_voltage0_scale_available`` | Toggles input span compression | ++-------------------------------------------+------------------------------------------+ + +Differential ADCs +----------------- + +Typical voltage channel attributes of a differential AD4000 series device: + ++-------------------------------------------+------------------------------------------+ +| Voltage Channel Attributes | Description | ++===========================================+==========================================+ +| ``in_voltage0-voltage1_raw`` | Raw ADC output code. | ++-------------------------------------------+------------------------------------------+ +| ``in_voltage0-voltage1_scale`` | Scale factor to convert raw value to mV. | ++-------------------------------------------+------------------------------------------+ +| ``in_voltage0-voltage1_scale_available`` | Toggles input span compression | ++-------------------------------------------+------------------------------------------+ + +SPI offload support +------------------- + +To be able to achieve the maximum sample rate, the driver can be used with SPI +offload engines such as the one usually present in `AXI SPI Engine`_, to provide +SPI offload support. + +.. _AXI SPI Engine: http://analogdevicesinc.github.io/hdl/projects/pulsar_adc/index.html + +To keep up with SPI offloading transfer speeds, the ADC must be connected either +in 3-wire turbo mode or in 3-wire without busy indicator mode and have SPI +controller CS line connected to the CNV pin. + +When set for SPI offload support, the IIO device will provide different +interfaces. + +* Either ``in_voltage0_sampling_frequency`` or + ``in_voltage0-voltage1_sampling_frequency`` file is provided to allow setting + the sample rate. +* IIO trigger device is not provided (no ``trigger`` directory). +* ``timestamp`` channel is not provided. + +Also, because the ADC output has a one sample latency (delay) when the device is +wired in "3-wire" mode and only one transfer per sample is done when using SPI +offloading, the first data sample in the buffer is not valid because it contains +the output of an earlier conversion result. diff --git a/Documentation/iio/ad4030.rst b/Documentation/iio/ad4030.rst new file mode 100644 index 000000000000..b57424b650a8 --- /dev/null +++ b/Documentation/iio/ad4030.rst @@ -0,0 +1,180 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +============= +AD4030 driver +============= + +ADC driver for Analog Devices Inc. AD4030 and similar devices. The module name +is ``ad4030``. + + +Supported devices +================= + +The following chips are supported by this driver: + +* `AD4030-24 <https://www.analog.com/AD4030-24>`_ +* `AD4032-24 <https://www.analog.com/AD4032-24>`_ +* `AD4630-16 <https://www.analog.com/AD4630-16>`_ +* `AD4630-24 <https://www.analog.com/AD4630-24>`_ +* `AD4632-16 <https://www.analog.com/AD4632-16>`_ +* `AD4632-24 <https://www.analog.com/AD4632-24>`_ + +IIO channels +============ + +Each "hardware" channel as described in the datasheet is split in 2 IIO +channels: + +- One channel for the differential data +- One channel for the common byte. + +The possible IIO channels depending on the numbers of "hardware" channel are: + ++------------------------------------+------------------------------------+ +| 1 channel ADC | 2 channels ADC | ++====================================+====================================+ +| - voltage0-voltage1 (differential) | - voltage0-voltage1 (differential) | +| - voltage2 (common-mode) | - voltage2-voltage3 (differential) | +| | - voltage4 (common-mode) | +| | - voltage5 (common-mode) | ++------------------------------------+------------------------------------+ + +Labels +------ + +For ease of use, the IIO channels provide a label. For a differential channel, +the label is ``differentialN`` where ``N`` is the "hardware" channel id. For a +common-mode channel, the label is ``common-modeN`` where ``N`` is the +"hardware" channel id. + +The possible labels are: + ++-----------------+-----------------+ +| 1 channel ADC | 2 channels ADC | ++=================+=================+ +| - differential0 | - differential0 | +| - common-mode0 | - differential1 | +| | - common-mode0 | +| | - common-mode1 | ++-----------------+-----------------+ + +Supported features +================== + +SPI wiring modes +---------------- + +The driver currently supports the following SPI wiring configurations: + +One lane mode +^^^^^^^^^^^^^ + +In this mode, each channel has its own SDO line to send the conversion results. +At the moment this mode can only be used on AD4030 which has one channel so only +one SDO line is used. + +.. code-block:: + + +-------------+ +-------------+ + | ADC | | HOST | + | | | | + | CNV |<--------| CNV | + | CS |<--------| CS | + | SDI |<--------| SDO | + | SDO0 |-------->| SDI | + | SCLK |<--------| SCLK | + +-------------+ +-------------+ + +Interleaved mode +^^^^^^^^^^^^^^^^ + +In this mode, both channels conversion results are bit interleaved one SDO line. +As such the wiring is the same as `One lane mode`_. + +SPI Clock mode +-------------- + +Only the SPI clocking mode is supported. + +Output modes +------------ + +There are more exposed IIO channels than channels as describe in the devices +datasheet. This is due to the `Differential data + common-mode`_ encoding +2 types of information in one conversion result. As such a "device" channel +provides 2 IIO channels, one for the differential data and one for the common +byte. + +Differential data +^^^^^^^^^^^^^^^^^ + +This mode is selected when: + +- Only differential channels are enabled in a buffered read +- Oversampling attribute is set to 1 + +Differential data + common-mode +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This mode is selected when: + +- Differential and common-mode channels are enabled in a buffered read +- Oversampling attribute is set to 1 + +For the 24-bits chips, this mode is also available with 16-bits differential +data but is not selectable yet. + +Averaged differential data +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This mode is selected when: + +- Only differential channels are selected enabled in a buffered read +- Oversampling attribute is greater than 1 + +Digital Gain and Offset +----------------------- + +Each differential data channel has a 16-bits unsigned configurable hardware +gain applied to it. By default it's equal to 1. Note that applying gain can +cause numerical saturation. + +Each differential data channel has a signed configurable hardware offset. +For the ADCs ending in ``-24``, the gain is encoded on 24-bits. +Likewise, the ADCs ending in ``-16`` have a gain encoded on 16-bits. Note that +applying an offset can cause numerical saturation. + +The final differential data returned by the ADC is computed by first applying +the gain, then the offset. + +The gain is controlled by the ``calibscale`` IIO attribute while the offset is +controlled by the ``calibbias`` attribute. + +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. + +Reset +----- + +Both hardware and software reset are supported. The driver looks first at the +device tree to see if the ``reset-gpio`` is populated. +If not present, the driver will fallback to a software reset by wiring to the +device's registers. + +Unimplemented features +---------------------- + +- ``BUSY`` indication +- Additional wiring modes +- Additional clock modes +- Differential data 16-bits + common-mode for 24-bits chips +- Overrange events +- Test patterns diff --git a/Documentation/iio/ad4695.rst b/Documentation/iio/ad4695.rst index 9ec8bf466c15..f40593bcc37d 100644 --- a/Documentation/iio/ad4695.rst +++ b/Documentation/iio/ad4695.rst @@ -47,6 +47,36 @@ In this mode, CNV and CS are tied together and there is a single SDO line. 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 --------------------- @@ -149,15 +179,62 @@ 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 +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 ============== @@ -165,3 +242,28 @@ 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). diff --git a/Documentation/iio/ad7191.rst b/Documentation/iio/ad7191.rst new file mode 100644 index 000000000000..977d4fea14b0 --- /dev/null +++ b/Documentation/iio/ad7191.rst @@ -0,0 +1,119 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +============= +AD7191 driver +============= + +Device driver for Analog Devices AD7191 ADC. + +Supported devices +================= + +* `AD7191 <https://www.analog.com/AD7191>`_ + +The AD7191 is a high precision, low noise, 24-bit Σ-Δ ADC with integrated PGA. +It features two differential input channels, an internal temperature sensor, and +configurable sampling rates. + +Devicetree +========== + +Pin Configuration +----------------- + +The driver supports both pin-strapped and GPIO-controlled configurations for ODR +(Output Data Rate) and PGA (Programmable Gain Amplifier) settings. These +configurations are mutually exclusive - you must use either pin-strapped or GPIO +control for each setting, not both. + +ODR Configuration +^^^^^^^^^^^^^^^^^ + +The ODR can be configured either through GPIO control or pin-strapping: + +- When using GPIO control, specify the "odr-gpios" property in the device tree +- For pin-strapped configuration, specify the "adi,odr-value" property in the + device tree + +Available ODR settings: + + - 120 Hz (ODR1=0, ODR2=0) + - 60 Hz (ODR1=0, ODR2=1) + - 50 Hz (ODR1=1, ODR2=0) + - 10 Hz (ODR1=1, ODR2=1) + +PGA Configuration +^^^^^^^^^^^^^^^^^ + +The PGA can be configured either through GPIO control or pin-strapping: + +- When using GPIO control, specify the "pga-gpios" property in the device tree +- For pin-strapped configuration, specify the "adi,pga-value" property in the + device tree + +Available PGA gain settings: + + - 1x (PGA1=0, PGA2=0) + - 8x (PGA1=0, PGA2=1) + - 64x (PGA1=1, PGA2=0) + - 128x (PGA1=1, PGA2=1) + +Clock Configuration +------------------- + +The AD7191 supports both internal and external clock sources: + +- When CLKSEL pin is tied LOW: Uses internal 4.92MHz clock (no clock property + needed) +- When CLKSEL pin is tied HIGH: Requires external clock source + - Can be a crystal between MCLK1 and MCLK2 pins + - Or a CMOS-compatible clock driving MCLK2 pin + - Must specify the "clocks" property in device tree when using external clock + +SPI Interface Requirements +-------------------------- + +The AD7191 has specific SPI interface requirements: + +- The DOUT/RDY output is dual-purpose and requires SPI bus locking +- DOUT/RDY must be connected to an interrupt-capable GPIO +- The SPI controller's chip select must be connected to the PDOWN pin of the ADC +- When CS (PDOWN) is high, the device powers down and resets internal circuitry +- SPI mode 3 operation (CPOL=1, CPHA=1) is required + +Power Supply Requirements +------------------------- + +The device requires the following power supplies: + +- AVdd: Analog power supply +- DVdd: Digital power supply +- Vref: Reference voltage supply (external) + +All power supplies must be specified in the device tree. + +Channel Configuration +===================== + +The device provides three channels: + +1. Temperature Sensor + - 24-bit unsigned + - Internal temperature measurement + - Temperature in millidegrees Celsius + +2. Differential Input (AIN1-AIN2) + - 24-bit unsigned + - Differential voltage measurement + - Configurable gain via PGA + +3. Differential Input (AIN3-AIN4) + - 24-bit unsigned + - Differential voltage measurement + - Configurable gain via PGA + +Buffer Support +============== + +This driver supports IIO triggered buffers. See Documentation/iio/iio_devbuf.rst +for more information about IIO triggered buffers. diff --git a/Documentation/iio/ad7380.rst b/Documentation/iio/ad7380.rst index c46127700e14..d51f9ee3e939 100644 --- a/Documentation/iio/ad7380.rst +++ b/Documentation/iio/ad7380.rst @@ -27,8 +27,10 @@ The following chips are supported by this driver: * `AD7386-4 <https://www.analog.com/en/products/ad7386-4.html>`_ * `AD7387-4 <https://www.analog.com/en/products/ad7387-4.html>`_ * `AD7388-4 <https://www.analog.com/en/products/ad7388-4.html>`_ +* `AD7389-4 <https://www.analog.com/en/products/ad7389-4.html>`_ * `ADAQ4370-4 <https://www.analog.com/en/products/adaq4370-4.html>`_ * `ADAQ4380-4 <https://www.analog.com/en/products/adaq4380-4.html>`_ +* `ADAQ4381-4 <https://www.analog.com/en/products/adaq4381-4.html>`_ Supported features @@ -49,11 +51,17 @@ ad7380-4 ad7380-4 supports only an external reference voltage (2.5V to 3.3V). It must be declared in the device tree as ``refin-supply``. +ad7389-4 +~~~~~~~~ + +ad7389-4 supports only an internal reference voltage. ``refin-supply`` and +``refio-supply`` properties are both omitted in this case. + ADAQ devices ~~~~~~~~~~~~ -adaq4370-4 and adaq4380-4 don't have an external reference, but use a 3.3V -internal reference derived from one of its supplies (``refin-supply``) +ADAQ devices don't have an external reference, but use a 3.3V internal reference +derived from one of its supplies (``refin-supply``) All other devices from ad738x family ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -92,6 +100,38 @@ must restart iiod using the following command: root:~# systemctl restart iiod +Alert +----- + +2 channels variants of the ad738x family, can use the SDOB line as an alert pin +when configured in 1 SDO line mode. 4 channels variants, can use SDOD as an +alert pin when configured in 1 or 2 SDO line(s) mode, although only 1 SDO line +mode is currently supported by the driver (see `SPI wiring modes`_). + +At the end of a conversion the active-low alert pin gets asserted if the +conversion result exceeds the alert high limit or falls below the alert low +limit. It is cleared, on a falling edge of CS. The alert pin is common to all +channels. + +User can enable alert using the regular iio events attribute: + +.. code-block:: bash + + events/thresh_either_en + +The high and low thresholds are common to all channels and can also be set using +regular iio events attributes: + +.. code-block:: bash + + events/in_thresh_falling_value + events/in_thresh_rising_value + +If debugfs is available, user can read the ALERT register to determine the +faulty channel and direction. + +In most use cases, user will hardwire the alert pin to trigger a shutdown. + Channel selection and sequencer (single-end chips only) ------------------------------------------------------- @@ -144,8 +184,25 @@ Unimplemented features - Rolling average oversampling - Power down mode - CRC indication -- Alert +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/pulsar_adc/index.html + +When SPI offload is being used, some attributes will be different. + +* ``trigger`` directory is removed. +* ``in_voltage0_sampling_frequency`` attribute is added for setting the sample + rate. +* ``in_voltage0_sampling_frequency_available`` attribute is 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 ``in_voltage0_type`` attribute. Device buffers ============== diff --git a/Documentation/iio/ad7606.rst b/Documentation/iio/ad7606.rst index 930199e03c67..5e02516bab40 100644 --- a/Documentation/iio/ad7606.rst +++ b/Documentation/iio/ad7606.rst @@ -26,6 +26,35 @@ SPI wiring modes These ADCs can output data on several SDO lines (1/2/4/8). The driver currently supports only 1 SDO line. +SPI offload wiring +------------------ +When used with a SPI offload, the supported wiring configuration is: + +.. code-block:: + + +-------------+ +-------------+ + | BUSY |-------->| TRIGGER | + | CS |<--------| CS | + | | | | + | ADC | | SPI | + | | | | + | SDI |<--------| SDO | + | DOUTA |-------->| SDI | + | SCLK |<--------| SCLK | + | | | | + | | +-------------+ + | CONVST |<--------| PWM | + +-------------+ +-------------+ + +In this case, the ``pwms`` property is required. +The ``#trigger-source-cells = <1>`` property is also required to connect back +to the SPI offload. The SPI offload will have ``trigger-sources`` property +with a cell to indicate the busy signal: +``<&ad7606 AD4695_TRIGGER_EVENT_BUSY>``. + +.. seealso:: `SPI offload support`_ + + Parallel wiring mode -------------------- @@ -123,6 +152,22 @@ Unimplemented features - CRC indication - Calibration +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: https://analogdevicesinc.github.io/hdl/library/spi_engine/index.html + +When SPI offload is being used, some attributes will be different. + +* ``trigger`` directory is removed. +* ``sampling_frequency`` attribute is added for setting the sample rate. +* ``timestamp`` channel is removed. +* Buffer data format may be different compared to when offload is not used, + e.g. the ``in_voltage0_type`` attribute. + Device buffers ============== diff --git a/Documentation/iio/ad7944.rst b/Documentation/iio/ad7944.rst index 0d26e56aba88..e6dbe4d7f58c 100644 --- a/Documentation/iio/ad7944.rst +++ b/Documentation/iio/ad7944.rst @@ -46,6 +46,8 @@ CS mode, 3-wire, without busy indicator To select this mode in the device tree, set the ``adi,spi-mode`` property to ``"single"`` and omit the ``cnv-gpios`` property. +This is the only wiring configuration supported when using `SPI offload support`_. + CS mode, 4-wire, without busy indicator ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -106,7 +108,6 @@ Unimplemented features ---------------------- - ``BUSY`` indication -- ``TURBO`` mode Device attributes @@ -147,6 +148,27 @@ AD7986 is a fully-differential ADC and has the following attributes: In "chain" mode, additional chips will appear as additional voltage input channels, e.g. ``in_voltage2-voltage3_raw``. +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/pulsar_adc/index.html + +When SPI offload is being used, some attributes will be different. + +* ``trigger`` directory is removed. +* ``in_voltage0_sampling_frequency`` attribute is added for setting the sample + rate. +* ``in_voltage0_sampling_frequency_available`` attribute is 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 ``in_voltage0_type`` attribute. + +If the ``turbo-gpios`` property is present in the device tree, the driver will +turn on TURBO during buffered reads and turn it off otherwise. Device buffers ============== diff --git a/Documentation/iio/adis16550.rst b/Documentation/iio/adis16550.rst new file mode 100644 index 000000000000..25db7b8060c4 --- /dev/null +++ b/Documentation/iio/adis16550.rst @@ -0,0 +1,376 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================ +ADIS16550 driver +================ + +This driver supports Analog Device's IMUs on SPI bus. + +1. Supported devices +==================== + +* `ADIS16550 <https://www.analog.com/ADIS16550>`_ + +The ADIS16550 is a complete inertial system that includes a triaxis gyroscope +and a triaxis accelerometer. The factory calibration characterizes each sensor for +sensitivity, bias, and alignment. As a result, each sensor has its own dynamic +compensation formulas that provide accurate sensor measurements. + +2. Device attributes +==================== + +Accelerometer, gyroscope measurements are always provided. Furthermore, the +driver offers the capability to retrieve the delta angle and the delta velocity +measurements computed by the device. + +The delta angle measurements represent a calculation of angular displacement +between each sample update, while the delta velocity measurements represent a +calculation of linear velocity change between each sample update. + +Finally, temperature data are provided which show a coarse measurement of +the temperature inside of the IMU device. This data is most useful for +monitoring relative changes in the thermal environment. + +Each IIO device, has a device folder under ``/sys/bus/iio/devices/iio:deviceX``, +where X is the IIO index of the device. Under these folders reside a set of +device files, depending on the characteristics and features of the hardware +device in questions. These files are consistently generalized and documented in +the IIO ABI documentation. + +The following tables show the adis16550 related device files, found in the +specific device folder path ``/sys/bus/iio/devices/iio:deviceX``. + ++-------------------------------------------+----------------------------------------------------------+ +| 3-Axis Accelerometer related device files | Description | ++-------------------------------------------+----------------------------------------------------------+ +| in_accel_scale | Scale for the accelerometer channels. | ++-------------------------------------------+----------------------------------------------------------+ +| in_accel_filter_low_pass_3db_frequency | Bandwidth for the accelerometer channels. | ++-------------------------------------------+----------------------------------------------------------+ +| in_accel_x_calibbias | Calibration offset for the X-axis accelerometer channel. | ++-------------------------------------------+----------------------------------------------------------+ +| in_accel_x_calibscale | Calibration scale for the X-axis accelerometer channel. | ++-------------------------------------------+----------------------------------------------------------+ +| in_accel_x_raw | Raw X-axis accelerometer channel value. | ++-------------------------------------------+----------------------------------------------------------+ +| in_accel_y_calibbias | Calibration offset for the Y-axis accelerometer channel. | ++-------------------------------------------+----------------------------------------------------------+ +| in_accel_y_calibscale | Calibration scale for the Y-axis accelerometer channel. | ++-------------------------------------------+----------------------------------------------------------+ +| in_accel_y_raw | Raw Y-axis accelerometer channel value. | ++-------------------------------------------+----------------------------------------------------------+ +| in_accel_z_calibbias | Calibration offset for the Z-axis accelerometer channel. | ++-------------------------------------------+----------------------------------------------------------+ +| in_accel_z_calibscale | Calibration scale for the Z-axis accelerometer channel. | ++-------------------------------------------+----------------------------------------------------------+ +| in_accel_z_raw | Raw Z-axis accelerometer channel value. | ++-------------------------------------------+----------------------------------------------------------+ +| in_deltavelocity_scale | Scale for delta velocity channels. | ++-------------------------------------------+----------------------------------------------------------+ +| in_deltavelocity_x_raw | Raw X-axis delta velocity channel value. | ++-------------------------------------------+----------------------------------------------------------+ +| in_deltavelocity_y_raw | Raw Y-axis delta velocity channel value. | ++-------------------------------------------+----------------------------------------------------------+ +| in_deltavelocity_z_raw | Raw Z-axis delta velocity channel value. | ++-------------------------------------------+----------------------------------------------------------+ + ++--------------------------------------------+------------------------------------------------------+ +| 3-Axis Gyroscope related device files | Description | ++--------------------------------------------+------------------------------------------------------+ +| in_anglvel_scale | Scale for the gyroscope channels. | ++--------------------------------------------+------------------------------------------------------+ +| in_anglvel_filter_low_pass_3db_frequency | Scale for the gyroscope channels. | ++--------------------------------------------+------------------------------------------------------+ +| in_anglvel_x_calibbias | Calibration offset for the X-axis gyroscope channel. | ++--------------------------------------------+------------------------------------------------------+ +| in_anglvel_x_calibscale | Calibration scale for the X-axis gyroscope channel. | ++--------------------------------------------+------------------------------------------------------+ +| in_anglvel_x_raw | Raw X-axis gyroscope channel value. | ++--------------------------------------------+------------------------------------------------------+ +| in_anglvel_y_calibbias | Calibration offset for the Y-axis gyroscope channel. | ++--------------------------------------------+------------------------------------------------------+ +| in_anglvel_y_calibscale | Calibration scale for the Y-axis gyroscope channel. | ++--------------------------------------------+------------------------------------------------------+ +| in_anglvel_y_raw | Raw Y-axis gyroscope channel value. | ++--------------------------------------------+------------------------------------------------------+ +| in_anglvel_z_calibbias | Calibration offset for the Z-axis gyroscope channel. | ++--------------------------------------------+------------------------------------------------------+ +| in_anglvel_z_calibscale | Calibration scale for the Z-axis gyroscope channel. | ++--------------------------------------------+------------------------------------------------------+ +| in_anglvel_z_raw | Raw Z-axis gyroscope channel value. | ++--------------------------------------------+------------------------------------------------------+ +| in_deltaangl_scale | Scale for delta angle channels. | ++--------------------------------------------+------------------------------------------------------+ +| in_deltaangl_x_raw | Raw X-axis delta angle channel value. | ++--------------------------------------------+------------------------------------------------------+ +| in_deltaangl_y_raw | Raw Y-axis delta angle channel value. | ++--------------------------------------------+------------------------------------------------------+ +| in_deltaangl_z_raw | Raw Z-axis delta angle channel value. | ++--------------------------------------------+------------------------------------------------------+ + ++----------------------------------+-------------------------------------------+ +| Temperature sensor related files | Description | ++----------------------------------+-------------------------------------------+ +| in_temp0_raw | Raw temperature channel value. | ++----------------------------------+-------------------------------------------+ +| in_temp0_offset | Offset for the temperature sensor channel.| ++----------------------------------+-------------------------------------------+ +| in_temp0_scale | Scale for the temperature sensor channel. | ++----------------------------------+-------------------------------------------+ + ++----------------------------+--------------------------------------------------------------------------------+ +| Miscellaneous device files | Description | ++----------------------------+--------------------------------------------------------------------------------+ +| name | Name of the IIO device. | ++----------------------------+--------------------------------------------------------------------------------+ +| sampling_frequency | Currently selected sample rate. | ++----------------------------+--------------------------------------------------------------------------------+ + +The following table shows the adis16550 related device debug files, found in the +specific device debug folder path ``/sys/kernel/debug/iio/iio:deviceX``. + ++----------------------+-------------------------------------------------------------------------+ +| Debugfs device files | Description | ++----------------------+-------------------------------------------------------------------------+ +| serial_number | The serial number of the chip in hexadecimal format. | ++----------------------+-------------------------------------------------------------------------+ +| product_id | Chip specific product id (16550). | ++----------------------+-------------------------------------------------------------------------+ +| flash_count | The number of flash writes performed on the device. | ++----------------------+-------------------------------------------------------------------------+ +| firmware_revision | String containing the firmware revision in the following format ##.##. | ++----------------------+-------------------------------------------------------------------------+ +| firmware_date | String containing the firmware date in the following format mm-dd-yyyy. | ++----------------------+-------------------------------------------------------------------------+ + +Channels processed values +------------------------- + +A channel value can be read from its _raw attribute. The value returned is the +raw value as reported by the devices. To get the processed value of the channel, +apply the following formula: + +.. code-block:: bash + + processed value = (_raw + _offset) * _scale + +Where _offset and _scale are device attributes. If no _offset attribute is +present, simply assume its value is 0. + +The adis16550 driver offers data for 5 types of channels, the table below shows +the measurement units for the processed value, which are defined by the IIO +framework: + ++--------------------------------------+---------------------------+ +| Channel type | Measurement unit | ++--------------------------------------+---------------------------+ +| Acceleration on X, Y, and Z axis | Meters per Second squared | ++--------------------------------------+---------------------------+ +| Angular velocity on X, Y and Z axis | Radians per second | ++--------------------------------------+---------------------------+ +| Delta velocity on X. Y, and Z axis | Meters per Second | ++--------------------------------------+---------------------------+ +| Delta angle on X, Y, and Z axis | Radians | ++--------------------------------------+---------------------------+ +| Temperature | Millidegrees Celsius | ++--------------------------------------+---------------------------+ + +Usage examples +-------------- + +Show device name: + +.. code-block:: bash + + root:/sys/bus/iio/devices/iio:device0> cat name + adis16550 + +Show accelerometer channels value: + +.. code-block:: bash + + root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_raw + 6903851 + root:/sys/bus/iio/devices/iio:device0> cat in_accel_y_raw + 5650550 + root:/sys/bus/iio/devices/iio:device0> cat in_accel_z_raw + 104873530 + root:/sys/bus/iio/devices/iio:device0> cat in_accel_scale + 0.000000095 + +- X-axis acceleration = in_accel_x_raw * in_accel_scale = 0.655865845 m/s^2 +- Y-axis acceleration = in_accel_y_raw * in_accel_scale = 0.53680225 m/s^2 +- Z-axis acceleration = in_accel_z_raw * in_accel_scale = 9.96298535 m/s^2 + +Show gyroscope channels value: + +.. code-block:: bash + + root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_x_raw + 193309 + root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_raw + -763676 + root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_z_raw + -358108 + root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_scale + 0.000000003 + +- X-axis angular velocity = in_anglvel_x_raw * in_anglvel_scale = 0.000579927 rad/s +- Y-axis angular velocity = in_anglvel_y_raw * in_anglvel_scale = −0.002291028 rad/s +- Z-axis angular velocity = in_anglvel_z_raw * in_anglvel_scale = −0.001074324 rad/s + +Set calibration offset for accelerometer channels: + +.. code-block:: bash + + root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias + 0 + + root:/sys/bus/iio/devices/iio:device0> echo 5000 > in_accel_x_calibbias + root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias + 5000 + +Set calibration offset for gyroscope channels: + +.. code-block:: bash + + root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_calibbias + 0 + + root:/sys/bus/iio/devices/iio:device0> echo -5000 > in_anglvel_y_calibbias + root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_calibbias + -5000 + +Set sampling frequency: + +.. code-block:: bash + + root:/sys/bus/iio/devices/iio:device0> cat sampling_frequency + 4000.000000 + + root:/sys/bus/iio/devices/iio:device0> echo 1000 > sampling_frequency + 1000.000000 + +Set bandwidth for accelerometer channels: + +.. code-block:: bash + + root:/sys/bus/iio/devices/iio:device0> cat in_accel_filter_low_pass_3db_frequency + 0 + + root:/sys/bus/iio/devices/iio:device0> echo 100 > in_accel_filter_low_pass_3db_frequency + root:/sys/bus/iio/devices/iio:device0> cat in_accel_filter_low_pass_3db_frequency + 100 + +Show serial number: + +.. code-block:: bash + + root:/sys/kernel/debug/iio/iio:device0> cat serial_number + 0x000000b6 + +Show product id: + +.. code-block:: bash + + root:/sys/kernel/debug/iio/iio:device0> cat product_id + 16550 + +Show flash count: + +.. code-block:: bash + + root:/sys/kernel/debug/iio/iio:device0> cat flash_count + 13 + +Show firmware revision: + +.. code-block:: bash + + root:/sys/kernel/debug/iio/iio:device0> cat firmware_revision + 1.5 + +Show firmware date: + +.. code-block:: bash + + root:/sys/kernel/debug/iio/iio:device0> cat firmware_date + 28-04-2021 + +3. Device buffers +================= + +This driver supports IIO buffers. + +The device supports retrieving the raw acceleration, gyroscope, delta velocity, +delta angle and temperature measurements using buffers. + +However, when retrieving acceleration or gyroscope data using buffers, delta +readings will not be available and vice versa. This is because the device only +allows to read either acceleration and gyroscope data or delta velocity and +delta angle data at a time and switching between these two burst data selection +modes is time consuming. + +Usage examples +-------------- + +Set device trigger in current_trigger, if not already set: + +.. code-block:: bash + + root:/sys/bus/iio/devices/iio:device0> cat trigger/current_trigger + + root:/sys/bus/iio/devices/iio:device0> echo adis16550-dev0 > trigger/current_trigger + root:/sys/bus/iio/devices/iio:device0> cat trigger/current_trigger + adis16550-dev0 + +Select channels for buffer read: + +.. code-block:: bash + + root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_x_en + root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_y_en + root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_z_en + root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_temp0_en + +Set the number of samples to be stored in the buffer: + +.. code-block:: bash + + root:/sys/bus/iio/devices/iio:device0> echo 10 > buffer/length + +Enable buffer readings: + +.. code-block:: bash + + root:/sys/bus/iio/devices/iio:device0> echo 1 > buffer/enable + +Obtain buffered data: + +.. code-block:: bash + + root:/sys/bus/iio/devices/iio:device0> hexdump -C /dev/iio\:device0 + ... + 0000cdf0 00 00 0d 2f 00 00 08 43 00 00 09 09 00 00 a4 5f |.../...C......._| + 0000ce00 00 00 0d 2f 00 00 07 de 00 00 08 db 00 00 a4 4b |.../...........K| + 0000ce10 00 00 0d 2f 00 00 07 58 00 00 08 a3 00 00 a4 55 |.../...X.......U| + 0000ce20 00 00 0d 2f 00 00 06 d6 00 00 08 5c 00 00 a4 62 |.../.......\...b| + 0000ce30 00 00 0d 2f 00 00 06 45 00 00 08 37 00 00 a4 47 |.../...E...7...G| + 0000ce40 00 00 0d 2f 00 00 05 d4 00 00 08 30 00 00 a3 fa |.../.......0....| + 0000ce50 00 00 0d 2f 00 00 05 d0 00 00 08 12 00 00 a3 d3 |.../............| + 0000ce60 00 00 0d 2f 00 00 05 dd 00 00 08 2e 00 00 a3 e9 |.../............| + 0000ce70 00 00 0d 2f 00 00 05 cc 00 00 08 51 00 00 a3 d5 |.../.......Q....| + 0000ce80 00 00 0d 2f 00 00 05 ba 00 00 08 22 00 00 a3 9a |.../......."....| + 0000ce90 00 00 0d 2f 00 00 05 9c 00 00 07 d9 00 00 a3 40 |.../...........@| + 0000cea0 00 00 0d 2f 00 00 05 68 00 00 07 94 00 00 a2 e4 |.../...h........| + 0000ceb0 00 00 0d 2f 00 00 05 25 00 00 07 8d 00 00 a2 ce |.../...%........| + ... + +See ``Documentation/iio/iio_devbuf.rst`` for more information about how buffered +data is structured. + +4. IIO Interfacing Tools +======================== + +See ``Documentation/iio/iio_tools.rst`` for the description of the available IIO +interfacing tools. diff --git a/Documentation/iio/adxl380.rst b/Documentation/iio/adxl380.rst index 376dee5fe1dd..66c8a4d4f767 100644 --- a/Documentation/iio/adxl380.rst +++ b/Documentation/iio/adxl380.rst @@ -94,7 +94,7 @@ apply the following formula: Where _offset and _scale are device attributes. If no _offset attribute is present, simply assume its value is 0. -The adis16475 driver offers data for 2 types of channels, the table below shows +The ADXL380 driver offers data for 2 types of channels, the table below shows the measurement units for the processed value, which are defined by the IIO framework: diff --git a/Documentation/iio/iio_adc.rst b/Documentation/iio/iio_adc.rst new file mode 100644 index 000000000000..f2f19a691907 --- /dev/null +++ b/Documentation/iio/iio_adc.rst @@ -0,0 +1,305 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +========================= +IIO Abstractions for ADCs +========================= + +1. Overview +=========== + +The IIO subsystem supports many Analog to Digital Converters (ADCs). Some ADCs +have features and characteristics that are supported in specific ways by IIO +device drivers. This documentation describes common ADC features and explains +how they are supported by the IIO subsystem. + +1. ADC Channel Types +==================== + +ADCs can have distinct types of inputs, each of them measuring analog voltages +in a slightly different way. An ADC digitizes the analog input voltage over a +span that is often given by the provided voltage reference, the input type, and +the input polarity. The input range allowed to an ADC channel is needed to +determine the scale factor and offset needed to obtain the measured value in +real-world units (millivolts for voltage measurement, milliamps for current +measurement, etc.). + +Elaborate designs may have nonlinear characteristics or integrated components +(such as amplifiers and reference buffers) that might also have to be considered +to derive the allowed input range for an ADC. For clarity, the sections below +assume the input range only depends on the provided voltage references, input +type, and input polarity. + +There are three general types of ADC inputs (single-ended, differential, +pseudo-differential) and two possible polarities (unipolar, bipolar). The input +type (single-ended, differential, pseudo-differential) is one channel +characteristic, and is completely independent of the polarity (unipolar, +bipolar) aspect. A comprehensive article about ADC input types (on which this +doc is heavily based on) can be found at +https://www.analog.com/en/resources/technical-articles/sar-adc-input-types.html. + +1.1 Single-ended channels +------------------------- + +Single-ended channels digitize the analog input voltage relative to ground and +can be either unipolar or bipolar. + +1.1.1 Single-ended Unipolar Channels +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + ---------- VREF ------------- + ´ ` ´ ` _____________ + / \ / \ / | + / \ / \ --- < IN ADC | + \ / \ / \ | + `-´ `-´ \ VREF | + -------- GND (0V) ----------- +-----------+ + ^ + | + External VREF + +The input voltage to a **single-ended unipolar** channel is allowed to swing +from GND to VREF (where VREF is a voltage reference with electrical potential +higher than system ground). The maximum input voltage is also called VFS +(Voltage input Full-Scale), with VFS being determined by VREF. The voltage +reference may be provided from an external supply or derived from the chip power +source. + +A single-ended unipolar channel could be described in device tree like the +following example:: + + adc@0 { + ... + #address-cells = <1>; + #size-cells = <0>; + + channel@0 { + reg = <0>; + }; + }; + +One is always allowed to include ADC channel nodes in the device tree. Though, +if the device has a uniform set of inputs (e.g. all inputs are single-ended), +then declaring the channel nodes is optional. + +One caveat for devices that support mixed single-ended and differential channels +is that single-ended channel nodes also need to provide a ``single-channel`` +property when ``reg`` is an arbitrary number that doesn't match the input pin +number. + +See ``Documentation/devicetree/bindings/iio/adc/adc.yaml`` for the complete +documentation of ADC specific device tree properties. + + +1.1.2 Single-ended Bipolar Channels +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + ---------- +VREF ------------ + ´ ` ´ ` _____________________ + / \ / \ / | + / \ / \ --- < IN ADC | + \ / \ / \ | + `-´ `-´ \ +VREF -VREF | + ---------- -VREF ------------ +-------------------+ + ^ ^ + | | + External +VREF ------+ External -VREF + +For a **single-ended bipolar** channel, the analog voltage input can go from +-VREF to +VREF (where -VREF is the voltage reference that has the lower +electrical potential while +VREF is the reference with the higher one). Some ADC +chips derive the lower reference from +VREF, others get it from a separate +input. Often, +VREF and -VREF are symmetric but they don't need to be so. When +-VREF is lower than system ground, these inputs are also called single-ended +true bipolar. Also, while there is a relevant difference between bipolar and +true bipolar from the electrical perspective, IIO makes no explicit distinction +between them. + +Here's an example device tree description of a single-ended bipolar channel:: + + adc@0 { + ... + #address-cells = <1>; + #size-cells = <0>; + + channel@0 { + reg = <0>; + bipolar; + }; + }; + +1.2 Differential channels +------------------------- + +A differential voltage measurement digitizes the voltage level at the positive +input (IN+) relative to the negative input (IN-) over the -VREF to +VREF span. +In other words, a differential channel measures the potential difference between +IN+ and IN-, which is often denoted by the IN+ - IN- formula. + +1.2.1 Differential Bipolar Channels +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + -------- +VREF ------ +-------------------+ + ´ ` ´ ` / | + / \ / \ / --- < IN+ | + `-´ `-´ | | + -------- -VREF ------ | | + | ADC | + -------- +VREF ------ | | + ´ ` ´ ` | | + \ / \ / \ --- < IN- | + `-´ `-´ \ +VREF -VREF | + -------- -VREF ------ +-------------------+ + ^ ^ + | +---- External -VREF + External +VREF + +The analog signals to **differential bipolar** inputs are also allowed to swing +from -VREF to +VREF. The bipolar part of the name means that the resulting value +of the difference (IN+ - IN-) can be positive or negative. If -VREF is below +system GND, these are also called differential true bipolar inputs. + +Device tree example of a differential bipolar channel:: + + adc@0 { + ... + #address-cells = <1>; + #size-cells = <0>; + + channel@0 { + reg = <0>; + bipolar; + diff-channels = <0 1>; + }; + }; + +In the ADC driver, ``differential = 1`` is set into ``struct iio_chan_spec`` for +the channel. Even though, there are three general input types, ``differential`` +is only used to distinguish between differential and non-differential (either +single-ended or pseudo-differential) input types. See +``include/linux/iio/iio.h`` for more information. + +1.2.2 Differential Unipolar Channels +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For **differential unipolar** channels, the analog voltage at the positive input +must also be higher than the voltage at the negative input. Thus, the actual +input range allowed to a differential unipolar channel is IN- to +VREF. Because +IN+ is allowed to swing with the measured analog signal and the input setup must +guarantee IN+ will not go below IN- (nor IN- will raise above IN+), most +differential unipolar channel setups have IN- fixed to a known voltage that does +not fall within the voltage range expected for the measured signal. That leads +to a setup that is equivalent to a pseudo-differential channel. Thus, +differential unipolar setups can often be supported as pseudo-differential +unipolar channels. + +1.3 Pseudo-differential Channels +-------------------------------- + +There is a third ADC input type which is called pseudo-differential or +single-ended to differential configuration. A pseudo-differential channel is +similar to a differential channel in that it also measures IN+ relative to IN-. +However, unlike bipolar differential channels, the negative input is limited to +a narrow voltage range (taken as a constant voltage) while only IN+ is allowed +to swing. A pseudo-differential channel can be made out from a differential pair +of inputs by restricting the negative input to a known voltage while allowing +only the positive input to swing. Sometimes, the input provided to IN- is called +common-mode voltage. Besides, some parts have a COM pin that allows single-ended +inputs to be referenced to a common-mode voltage, making them +pseudo-differential channels. Often, the common mode input voltage can be +described in the device tree as a voltage regulator (e.g. ``com-supply``) since +it is basically a constant voltage source. + +1.3.1 Pseudo-differential Unipolar Channels +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + -------- +VREF ------ +-------------------+ + ´ ` ´ ` / | + / \ / \ / --- < IN+ | + `-´ `-´ | | + --------- IN- ------- | ADC | + | | + Common-mode voltage --> --- < IN- | + \ +VREF -VREF | + +-------------------+ + ^ ^ + | +---- External -VREF + External +VREF + +A **pseudo-differential unipolar** input has the limitations a differential +unipolar channel would have, meaning the analog voltage to the positive input +IN+ must stay within IN- to +VREF. The fixed voltage to IN- is often called +common-mode voltage and it must be within -VREF to +VREF as would be expected +from the signal to any differential channel negative input. + +The voltage measured from IN+ is relative to IN- but, unlike differential +channels, pseudo-differential setups are intended to gauge single-ended input +signals. To enable applications to calculate IN+ voltage with respect to system +ground, the IIO channel may provide an ``_offset`` sysfs attribute to be added +to ADC output when converting raw data to voltage units. In many setups, the +common-mode voltage input is at GND level and the ``_offset`` attribute is +omitted due to being always zero. + +Device tree example for pseudo-differential unipolar channel:: + + adc@0 { + ... + #address-cells = <1>; + #size-cells = <0>; + + channel@0 { + reg = <0>; + single-channel = <0>; + common-mode-channel = <1>; + }; + }; + +Do not set ``differential`` in the channel ``iio_chan_spec`` struct of +pseudo-differential channels. + +1.3.2 Pseudo-differential Bipolar Channels +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + -------- +VREF ------ +-------------------+ + ´ ` ´ ` / | + / \ / \ / --- < IN+ | + `-´ `-´ | | + -------- -VREF ------ | ADC | + | | + Common-mode voltage --> --- < IN- | + \ +VREF -VREF | + +-------------------+ + ^ ^ + | +---- External -VREF + External +VREF + +A **pseudo-differential bipolar** input is not limited by the level at IN- but +it will be limited to -VREF or to GND on the lower end of the input range +depending on the particular ADC. Similar to their unipolar counter parts, +pseudo-differential bipolar channels ought to declare an ``_offset`` attribute +to enable the conversion of raw ADC data to voltage units. For the setup with +IN- connected to GND, ``_offset`` is often omitted. + +Device tree example for pseudo-differential bipolar channel:: + + adc@0 { + ... + #address-cells = <1>; + #size-cells = <0>; + + channel@0 { + reg = <0>; + bipolar; + single-channel = <0>; + common-mode-channel = <1>; + }; + }; diff --git a/Documentation/iio/iio_devbuf.rst b/Documentation/iio/iio_devbuf.rst index 9919e4792d0e..dca1f0200b0d 100644 --- a/Documentation/iio/iio_devbuf.rst +++ b/Documentation/iio/iio_devbuf.rst @@ -148,5 +148,5 @@ applied), however there are corner cases in which the buffered data may be found in a processed form. Please note that these corner cases are not addressed by this documentation. -Please see ``Documentation/ABI/testing/sysfs-bus-iio`` for a complete +Please see Documentation/ABI/testing/sysfs-bus-iio for a complete description of the attributes. diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst index 5710f5b9e958..2d6afc5a8ed5 100644 --- a/Documentation/iio/index.rst +++ b/Documentation/iio/index.rst @@ -7,6 +7,7 @@ Industrial I/O .. toctree:: :maxdepth: 1 + iio_adc iio_configfs iio_devbuf iio_dmabuf_api @@ -18,14 +19,18 @@ Industrial I/O Kernel Drivers .. toctree:: :maxdepth: 1 + ad3552r ad4000 + ad4030 ad4695 + ad7191 ad7380 ad7606 ad7625 ad7944 adis16475 adis16480 + adis16550 adxl380 bno055 ep93xx_adc |