lastdragon/linux-kernel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Resguardo inicial

Browse Source
This commit is contained in:
lastdragon
2026-09-06 12:53:21 -06:00
parent 662efe3c2a
commit ad2088d178
94853 changed files with 43200404 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
linux-7.2.3/Documentation/iio/ad3552r.rst
+73
View File
@@ -0,0 +1,73 @@
.. 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
linux-7.2.3/Documentation/iio/ad4000.rst
+220
View File
@@ -0,0 +1,220 @@
.. SPDX-License-Identifier: GPL-2.0-only
=============
AD4000 driver
=============
Device driver for Analog Devices Inc. AD4000 series of ADCs and similar devices.
Supported devices
=================
* `AD4000 <https://www.analog.com/AD4000>`_
* `AD4001 <https://www.analog.com/AD4001>`_
* `AD4002 <https://www.analog.com/AD4002>`_
* `AD4003 <https://www.analog.com/AD4003>`_
* `AD4004 <https://www.analog.com/AD4004>`_
* `AD4005 <https://www.analog.com/AD4005>`_
* `AD4006 <https://www.analog.com/AD4006>`_
* `AD4007 <https://www.analog.com/AD4007>`_
* `AD4008 <https://www.analog.com/AD4008>`_
* `AD4010 <https://www.analog.com/AD4010>`_
* `AD4011 <https://www.analog.com/AD4011>`_
* `AD4020 <https://www.analog.com/AD4020>`_
* `AD4021 <https://www.analog.com/AD4021>`_
* `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
------------------
Devices of the AD4000 series can be connected to the SPI host controller in a
few different modes.
CS mode, 3-wire turbo mode
^^^^^^^^^^^^^^^^^^^^^^^^^^
Datasheet "3-wire" mode is what most resembles standard SPI connection which,
for these devices, comprises of connecting the controller CS line to device CNV
pin and other SPI lines as usual. This configuration is (misleadingly) called
"CS Mode, 3-Wire Turbo Mode" connection in datasheets.
NOTE: The datasheet definition of 3-wire mode for the AD4000 series is NOT the
same of standard spi-3wire mode.
This is the only connection mode that allows configuration register access but
it requires the SPI controller to support the ``SPI_MOSI_IDLE_HIGH`` feature.
Omit the ``adi,sdi-pin`` property in device tree to select this mode.
::
+-------------+
+ ----------------------------------| SDO |
| | |
| +-------------------| CS |
| v | |
| +--------------------+ | HOST |
| | CNV | | |
+--->| SDI AD4000 SDO |-------->| SDI |
| SCK | | |
+--------------------+ | |
^ | |
+--------------------| SCLK |
+-------------+
CS mode, 3-wire, without busy indicator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Another wiring configuration supported as "3-wire" mode has the SDI pin
hard-wired to digital input/output interface supply (VIO). In this setup, the
controller is not required to support ``SPI_MOSI_IDLE_HIGH`` but register access
is not possible. This connection mode saves one wire and works with any SPI
controller.
Set the ``adi,sdi-pin`` device tree property to ``"high"`` to select this mode.
::
+-------------+
+--------------------| CS |
v | |
VIO +--------------------+ | HOST |
| | CNV | | |
+--->| SDI AD4000 SDO |-------->| SDI |
| SCK | | |
+--------------------+ | |
^ | |
+--------------------| SCLK |
+-------------+
Alternatively, a GPIO may be connected to the device CNV pin. This is similar to
the previous wiring configuration but saves the use of a CS line.
::
+-------------+
+--------------------| GPIO |
v | |
VIO +--------------------+ | HOST |
| | CNV | | |
+--->| SDI AD4000 SDO |-------->| SDI |
| SCK | | |
+--------------------+ | |
^ | |
+--------------------| SCLK |
+-------------+
CS mode, 4-wire without busy indicator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In datasheet "4-wire" mode, the controller CS line is connected to the ADC SDI
pin and a GPIO is connected to the ADC CNV pin. This connection mode may better
suit scenarios where multiple ADCs can share one CNV trigger.
Set ``adi,sdi-pin`` to ``"cs"`` to select this mode.
::
+-------------+
+ ----------------------------------| CS |
| | |
| +-------------------| GPIO |
| v | |
| +--------------------+ | HOST |
| | CNV | | |
+--->| SDI AD4000 SDO |-------->| SDI |
| SCK | | |
+--------------------+ | |
^ | |
+--------------------| 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.
linux-7.2.3/Documentation/iio/ad4030.rst
+219
View File
@@ -0,0 +1,219 @@
.. 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 offload wiring
^^^^^^^^^^^^^^^^^^
.. code-block::
+-------------+ +-------------+
| CNV |<-----+--| GPIO |
| | +--| PWM0 |
| | | |
| | +--| PWM1 |
| | | +-------------+
| | +->| TRIGGER |
| CS |<--------| CS |
| | | |
| ADC | | SPI |
| | | |
| SDI |<--------| SDO |
| SDO |-------->| SDI |
| SCLK |<--------| SCLK |
+-------------+ +-------------+
In this mode, both the ``cnv-gpios`` and a ``pwms`` properties are required.
The ``pwms`` property specifies the PWM that is connected to the ADC CNV pin.
The SPI offload will have a ``trigger-sources`` property to indicate the SPI
offload (PWM) trigger source. For AD4030 and similar ADCs, there are two
possible data transfer zones for sample N. One of them (zone 1) starts after the
data conversion for sample N is complete while the other one (zone 2) starts 9.8
nanoseconds after the rising edge of CNV for sample N + 1.
The configuration depicted in the above diagram is intended to perform data
transfer in zone 2. To achieve high sample rates while meeting ADC timing
requirements, an offset is added between the rising edges of PWM0 and PWM1 to
delay the SPI transfer until 9.8 nanoseconds after CNV rising edge. This
requires a specialized PWM controller that can provide such an offset.
The `AD4630-FMC HDL project`_, for example, can be configured to sample AD4030
data during zone 2 data read window.
.. _AD4630-FMC HDL project: https://analogdevicesinc.github.io/hdl/projects/ad4630_fmc/index.html
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
linux-7.2.3/Documentation/iio/ad4062.rst
+148
View File
@@ -0,0 +1,148 @@
.. SPDX-License-Identifier: GPL-2.0-only
=============
AD4062 driver
=============
ADC driver for Analog Devices Inc. AD4060/AD4062 devices. The module name is
``ad4062``.
Supported devices
=================
The following chips are supported by this driver:
* `AD4060 <https://www.analog.com/AD4060>`_
* `AD4062 <https://www.analog.com/AD4062>`_
Wiring modes
============
The ADC is interfaced through an I3C bus, and contains two programmable GPIOs.
The ADC convert-start happens on the SDA rising edge of the I3C stop (P) bit
at the end of the read command.
The two programmable GPIOS are optional and have a role assigned if present in
the devicetree ``interrupt-names`` property:
- GP0: Is assigned the role of Threshold Either signal.
- GP1: Is assigned the role of Data Ready signal.
If the property ``gpio-controller`` is present in the devicetree, then the GPO
not present in the ``interrupt-names`` is exposed as a GPO.
Device attributes
=================
The ADC contains only one channel with following attributes:
.. list-table:: Channel attributes
:header-rows: 1
* - Attribute
- Description
* - ``in_voltage_calibscale``
- Sets the gain scaling factor that the hardware applies to the sample,
to compensate for system gain error.
* - ``in_voltage_oversampling_ratio``
- Sets device's burst averaging mode to over sample using the
internal sample rate. Value 1 disable the burst averaging mode.
* - ``in_voltage_oversampling_ratio_available``
- List of available oversampling values.
* - ``in_voltage_raw``
- Returns the raw ADC voltage value.
* - ``in_voltage_scale``
- Returns the channel scale in reference to the reference voltage
``ref-supply`` or ``vdd-supply`` if the former not present.
Also contain the following device attributes:
.. list-table:: Device attributes
:header-rows: 1
* - Attribute
- Description
* - ``sampling_frequency``
- Sets the duration of a single scan, used in the burst averaging mode.
The duration is described by ``(n_avg - 1) / fosc + tconv``, where
``n_avg`` is the oversampling ratio, ``fosc`` is the internal sample
rate and ``tconv`` is the ADC conversion time.
* - ``sampling_frequency_available``
- Lists the available sampling frequencies, computed on the current
oversampling ratio. If the ratio is 1, the frequency is ``1/tconv``.
Interrupts
==========
The interrupts are mapped through the ``interrupt-names`` and ``interrupts``
properties.
The ``interrupt-names`` ``gp0`` entry sets the role of Threshold signal, and
entry ``gp1`` the role of Data Ready signal.
If each is not present, the driver fallback to enabling the same role as an
I3C IBI.
Low-power mode
==============
The device enters low-power mode on idle to save power. Enabling an event puts
the device out of the low-power since the ADC autonomously samples to assert
the event condition.
IIO trigger support
===================
An IIO trigger ``ad4062-devX`` is registered by the driver to be used by the
same device, to capture samples to a software buffer. It is required to attach
the trigger to the device by setting the ``current_trigger`` before enabling
and reading the buffer.
The acquisition is sequential and bounded by the protocol timings, software
latency and internal timings, the sample rate is not configurable. The burst
averaging mode does impact the effective sample rate, since it increases the
internal timing to output a single sample.
Threshold events
================
The ADC supports a monitoring mode to raise threshold events. The driver
supports a single interrupt for both rising and falling readings.
The feature is enabled/disabled by setting ``thresh_either_en``. During monitor
mode, the device continuously operates in autonomous mode. Any register access
puts the device back in configuration mode, due to this, any access disables
monitor mode.
The following event attributes are available:
.. list-table:: Event attributes
:header-rows: 1
* - Attribute
- Description
* - ``sampling_frequency``
- Frequency used in the monitoring mode, sets the device internal sample
rate when the mode is activated.
* - ``sampling_frequency_available``
- List of available sample rates.
* - ``thresh_either_en``
- Enable monitoring mode.
* - ``thresh_falling_hysteresis``
- Set the hysteresis value for the minimum threshold.
* - ``thresh_falling_value``
- Set the minimum threshold value.
* - ``thresh_rising_hysteresis``
- Set the hysteresis value for the maximum threshold.
* - ``thresh_rising_value``
- Set the maximum threshold value.
GPO controller support
======================
The device supports using GP0 and GP1 as GPOs. If the devicetree contains the
node ``gpio-controller```, the device is marked as a GPIO controller and the
GPs not listed in ``interrupt-names`` are exposed as a GPO. The GPIO index
matches the pin name, so if GP0 is not exposed but GP1 is, index 0 is masked
out and only index 1 can be set.
linux-7.2.3/Documentation/iio/ad4691.rst
+227
View File
@@ -0,0 +1,227 @@
.. SPDX-License-Identifier: GPL-2.0-only
=============
AD4691 driver
=============
ADC driver for Analog Devices Inc. AD4691 family of multichannel SAR ADCs.
The module name is ``ad4691``.
Supported devices
=================
The following chips are supported by this driver:
* `AD4691 <https://www.analog.com/en/products/ad4691.html>`_ — 16-channel, 500 kSPS
* `AD4692 <https://www.analog.com/en/products/ad4692.html>`_ — 16-channel, 1 MSPS
* `AD4693 <https://www.analog.com/en/products/ad4693.html>`_ — 8-channel, 500 kSPS
* `AD4694 <https://www.analog.com/en/products/ad4694.html>`_ — 8-channel, 1 MSPS
IIO channels
============
Each physical ADC input maps to one IIO voltage channel. The AD4691 and AD4692
expose 16 channels (``voltage0`` through ``voltage15``); the AD4693 and AD4694
expose 8 channels (``voltage0`` through ``voltage7``).
All channels share a common scale (``in_voltage_scale``), derived from the
reference voltage. Each channel exposes:
* ``in_voltageN_raw`` — single-shot ADC result
The following attributes are shared across all channels:
* ``in_voltage_sampling_frequency`` — effective output rate, defined as the
internal oscillator frequency divided by the oversampling ratio. Writing this
attribute selects the nearest achievable rate for the current OSR; the value
read back reflects the actual rate after snapping to the closest valid
oscillator entry.
* ``in_voltage_sampling_frequency_available`` — list of achievable effective
rates for the current oversampling ratio. The list updates dynamically when
the oversampling ratio changes.
The following attributes are shared across all channels and only available in
CNV Burst Mode:
* ``in_voltage_oversampling_ratio`` — hardware oversampling depth applied to
all channels; see `Oversampling`_ below.
* ``in_voltage_oversampling_ratio_available`` — valid ratios: 1, 2, 4, 8, 16,
32.
Operating modes
===============
The driver supports two operating modes, selected automatically from the
device tree at probe time.
Manual Mode
-----------
Selected when no ``pwms`` property is present in the device tree. The CNV pin
is tied to the SPI chip-select: every CS assertion triggers a conversion and
returns the previous result. A user-defined IIO trigger (e.g. hrtimer trigger)
drives the buffer.
Oversampling is not supported in Manual Mode.
CNV Burst Mode
--------------
Selected when a ``pwms`` property is present in the device tree. A PWM drives
the CNV pin at the configured conversion rate. A GP pin wired to the SoC and
declared in the device tree signals DATA_READY at the end of each burst,
triggering a readout of all active channel results into the IIO buffer.
The buffer output rate is controlled by the ``sampling_frequency`` attribute
on the IIO buffer. In practice the PWM rate should be set low enough to allow
the SPI readout to complete before the next conversion burst begins.
Autonomous Mode (idle / single-shot)
-------------------------------------
When the IIO buffer is disabled, ``in_voltageN_raw`` reads perform a single
conversion on the requested channel using the internal oscillator. The
oscillator is started and stopped around each read to save power.
Oversampling
============
In CNV Burst Mode a shared hardware accumulator averages a configurable number
of successive conversions across all active channels. The result is always a
16-bit mean, so the buffer data type (shown in ``buffer0/in_voltageN_type``)
is unaffected by the oversampling ratio. Valid ratios are 1, 2, 4, 8, 16 and
32; the default is 1 (no averaging). Oversampling is not supported in Manual
Mode.
.. code-block:: bash
# Set oversampling ratio to 16 (shared across all channels)
echo 16 > /sys/bus/iio/devices/iio:device0/in_voltage_oversampling_ratio
# Read the resulting effective sampling frequency
cat /sys/bus/iio/devices/iio:device0/in_voltage_sampling_frequency
Writing ``in_voltage_oversampling_ratio`` stores the new shared depth and snaps
the internal oscillator to the largest valid table entry that is both less than
or equal to ``old_effective_rate × new_osr`` and evenly divisible by
``new_osr``. This preserves an integer read-back of
``in_voltage_sampling_frequency`` after the change and keeps the oscillator as
close as possible to the previous effective rate.
Reference voltage
=================
The driver supports two reference configurations, mutually exclusive:
* **External reference** (``ref-supply``): a voltage between 2.4 V and 5.25 V
supplied externally.
* **Buffered internal reference** (``refin-supply``): an internal reference
buffer is enabled by the driver.
Exactly one of ``ref-supply`` or ``refin-supply`` must be present in the
device tree. The reference voltage determines the full-scale range reported
via ``in_voltage_scale``.
LDO supply
==========
The chip contains an internal LDO that powers part of the analog front-end.
The supply configuration is mutually exclusive:
* **External VDD** (``vdd-supply``): an external 1.8 V supply is used directly;
the internal LDO is disabled.
* **Internal LDO** (``ldo-in-supply``): the internal LDO is enabled and fed
from the ``ldo-in`` regulator. Use this when no external 1.8 V VDD is present.
Exactly one of ``vdd-supply`` or ``ldo-in-supply`` must be provided.
Reset
=====
The driver supports two reset mechanisms:
* **Hardware reset** (``reset-gpios`` in device tree): the GPIO line is
asserted then deasserted at probe; the driver waits 300 µs for the chip
to complete its internal reset sequence before accepting SPI commands.
* **Software reset** (fallback when ``reset-gpios`` is absent): written
automatically at probe.
GP pins and interrupts
======================
The chip exposes up to four general-purpose (GP) pins. In CNV Burst Mode
(non-offload), one GP pin must be wired to an interrupt-capable SoC input and
declared in the device tree using the ``interrupts`` and ``interrupt-names``
properties. The ``interrupt-names`` value identifies which GP pin is used
(``"gp0"`` through ``"gp3"``).
Example device tree fragment::
adc@0 {
compatible = "adi,ad4692";
...
interrupt-parent = <&gpio0>;
interrupts = <17 IRQ_TYPE_LEVEL_HIGH>;
interrupt-names = "gp0";
};
SPI offload support
===================
When a SPI offload engine (e.g. the AXI SPI Engine) is present, the driver
uses DMA-backed transfers for CPU-independent, high-throughput data capture.
SPI offload is detected automatically at probe; if no offload hardware is
available the driver falls back to the software triggered-buffer path.
Two SPI offload sub-modes exist:
CNV Burst offload
-----------------
Used when a ``pwms`` property is present and SPI offload is available. The PWM
drives CNV at the configured rate; on DATA_READY the offload engine reads all
active channel results and streams them directly to the IIO DMA buffer with no
CPU involvement. The GP pin used as DATA_READY trigger is supplied by the
trigger-source consumer at buffer enable time; no ``interrupt-names`` entry is
required.
Manual offload
--------------
Used when no ``pwms`` property is present and SPI offload is available. A
periodic SPI offload trigger controls the conversion rate and the offload engine
streams results directly to the IIO DMA buffer.
The ``sampling_frequency`` attribute on the IIO buffer controls the trigger
rate (in Hz). The initial rate is 100 kHz.
Oversampling is not supported in Manual Mode.
Buffer data format
==================
The sample format in the IIO buffer depends on whether SPI offload is in use.
Software triggered-buffer path (no SPI offload)
------------------------------------------------
Each active channel occupies one 16-bit big-endian slot (``storagebits=16``,
``endianness=be``). Active channels are packed densely in scan-index order,
followed by a 64-bit software timestamp appended by the IIO core.
SPI offload path
----------------
Each active channel occupies one 16-bit CPU-native slot (``storagebits=16``,
``endianness=cpu``). The SPI offload engine streams 16-bit words directly from
the SPI Engine into the DMA buffer; no software timestamp is appended.
linux-7.2.3/Documentation/iio/ad4695.rst
+269
View File
@@ -0,0 +1,269 @@
.. 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).
linux-7.2.3/Documentation/iio/ad7191.rst
+119
View File
@@ -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 ACTIVE: Uses internal 4.92MHz clock (no clock property
needed)
- When CLKSEL pin is INACTIVE: Requires external clock source
- Can be a crystal between MCLK1 and MCLK2 pins
- Or a CMOS-compatible clock driving MCLK1 pin and MCLK2 left unconnected
- 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.
linux-7.2.3/Documentation/iio/ad7380.rst
+212
View File
@@ -0,0 +1,212 @@
.. SPDX-License-Identifier: GPL-2.0-only
=============
AD7380 driver
=============
ADC driver for Analog Devices Inc. AD7380 and similar devices. The module name
is ``ad7380``.
Supported devices
=================
The following chips are supported by this driver:
* `AD7380 <https://www.analog.com/en/products/ad7380.html>`_
* `AD7381 <https://www.analog.com/en/products/ad7381.html>`_
* `AD7383 <https://www.analog.com/en/products/ad7383.html>`_
* `AD7384 <https://www.analog.com/en/products/ad7384.html>`_
* `AD7386 <https://www.analog.com/en/products/ad7386.html>`_
* `AD7387 <https://www.analog.com/en/products/ad7387.html>`_
* `AD7388 <https://www.analog.com/en/products/ad7388.html>`_
* `AD7380-4 <https://www.analog.com/en/products/ad7380-4.html>`_
* `AD7381-4 <https://www.analog.com/en/products/ad7381-4.html>`_
* `AD7383-4 <https://www.analog.com/en/products/ad7383-4.html>`_
* `AD7384-4 <https://www.analog.com/en/products/ad7384-4.html>`_
* `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
==================
SPI wiring modes
----------------
ad738x ADCs can output data on several SDO lines (1/2/4). The driver currently
supports only 1 SDO line.
Reference voltage
-----------------
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
~~~~~~~~~~~~
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
All other devices from ad738x support 2 possible reference voltage sources:
- Internal reference (2.5V)
- External reference (2.5V to 3.3V)
The source is determined by the device tree. If ``refio-supply`` is present,
then it is used as external reference, else the internal reference is used.
Oversampling and resolution boost
---------------------------------
This family supports 2 types of oversampling: normal average and rolling
average. Only normal average is supported by the driver, as rolling average can
be achieved by processing a captured data buffer. The following ratios are
available: 1 (oversampling disabled)/2/4/8/16/32.
When the on-chip oversampling function is enabled the performance of the ADC can
exceed the default resolution. To accommodate the performance boost achievable,
it is possible to enable an additional two bits of resolution. Because the
resolution boost feature can only be enabled when oversampling is enabled and
oversampling is not as useful without the resolution boost, the driver
automatically enables the resolution boost if and only if oversampling is
enabled.
Since the resolution boost feature causes 16-bit chips to now have 18-bit data
which means the storagebits has to change from 16 to 32 bits, we use the new
ext_scan_type feature to allow changing the scan_type at runtime. Unfortunately
libiio does not support it. So when enabling or disabling oversampling, user
must restart iiod using the following command:
.. code-block:: bash
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)
-------------------------------------------------------
Single-ended chips of this family (ad7386/7/8(-4)) have a 2:1 multiplexer in
front of each ADC. They also include additional configuration registers that
allow for either manual selection or automatic switching (sequencer mode), of
the multiplexer inputs.
From an IIO point of view, all inputs are exported, i.e ad7386/7/8
export 4 channels and ad7386-4/7-4/8-4 export 8 channels.
Inputs ``AinX0`` of multiplexers correspond to the first half of IIO channels (i.e
0-1 or 0-3) and inputs ``AinX1`` correspond to second half (i.e 2-3 or 4-7).
Example for AD7386/7/8 (2 channels parts):
.. code-block::
IIO | AD7386/7/8
| +----------------------------
| | _____ ______
| | | | | |
voltage0 | AinA0 --|--->| | | |
| | | mux |----->| ADCA |---
voltage2 | AinA1 --|--->| | | |
| | |_____| |_____ |
| | _____ ______
| | | | | |
voltage1 | AinB0 --|--->| | | |
| | | mux |----->| ADCB |---
voltage3 | AinB1 --|--->| | | |
| | |_____| |______|
| |
| +----------------------------
When enabling sequencer mode, the effective sampling rate is divided by two.
Gain (ADAQ devices only)
~~~~~~~~~~~~~~~~~~~~~~~~
ADAQ devices have a pin selectable gain in front of each ADC. The appropriate
gain is selectable from device tree using the ``adi,gain-milli`` property.
Refer to the typical connection diagrams section of the datasheet for pin
wiring.
Unimplemented features
----------------------
- 2/4 SDO lines
- Rolling average oversampling
- Power down mode
- CRC indication
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
==============
This driver supports IIO triggered buffers.
See :doc:`iio_devbuf` for more information.
linux-7.2.3/Documentation/iio/ad7606.rst
+189
View File
@@ -0,0 +1,189 @@
.. SPDX-License-Identifier: GPL-2.0-only
=============
AD7606 driver
=============
ADC driver for Analog Devices Inc. AD7606 and similar devices. The module name
is ``ad7606``.
Supported devices
=================
The following chips are supported by this driver:
* `AD7605 <https://www.analog.com/en/products/ad7605.html>`_
* `AD7606 <https://www.analog.com/en/products/ad7606.html>`_
* `AD7606B <https://www.analog.com/en/products/ad7606b.html>`_
* `AD7616 <https://www.analog.com/en/products/ad7616.html>`_
Supported features
==================
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
--------------------
There is also a parallel interface, with 16 lines (that can be reduced to 8 in
byte mode). The parallel interface is selected by declaring the device as
platform in the device tree (with no io-backends node defined, see below).
IIO-backend mode
----------------
This mode allows to reach the best sample rates, but it requires an external
hardware (eg HDL or APU) to handle the low level communication.
The backend mode is enabled when through the definition of the "io-backends"
property in the device tree.
The reference configuration for the current implementation of IIO-backend mode
is the HDL reference provided by ADI:
https://wiki.analog.com/resources/eval/user-guides/ad7606x-fmc/hdl
This implementation embeds an IIO-backend compatible IP (adi-axi-adc) and a PWM
connected to the conversion trigger pin.
.. code-block::
+---+ +----------------------------
| | +-------+ |AD76xx
| A | controls | | |
| D |-------------->| PWM |-------------->| cnvst
| 7 | | | |
| 6 | +-------+ |
| 0 | controls +-----------+-----------+ |
| 6 |---------->| | |<--| frstdata
| | | Backend | Backend |<--| busy
| D | | Driver | | |
| R | | | |-->| clk
| I | requests |+---------+| DMA | |
| V |----------->| Buffer ||<---- |<=>| DATA
| E | |+---------+| | |
| R | +-----------+-----------+ |
| |-------------------------------------->| reset/configuration gpios
+---+ +-----------------------------
Software and hardware modes
---------------------------
While all the AD7606/AD7616 series parts can be configured using GPIOs, some of
them can be configured using register.
The chips that support software mode have more values available for configuring
the device, as well as more settings, and allow to control the range and
calibration per channel.
The following settings are available per channel in software mode:
- Scale
Also, there is a broader choice of oversampling ratios in software mode.
Conversion triggering
---------------------
The conversion can be triggered by two distinct ways:
- A GPIO is connected to the conversion trigger pin, and this GPIO is controlled
by the driver directly. In this configuration, the driver sets back the
conversion trigger pin to high as soon as it has read all the conversions.
- An external source is connected to the conversion trigger pin. In the
current implementation, it must be a PWM. In this configuration, the driver
does not control directly the conversion trigger pin. Instead, it can
control the PWM's frequency. This trigger is enabled only for iio-backend.
Reference voltage
-----------------
2 possible reference voltage sources are supported:
- Internal reference (2.5V)
- External reference (2.5V)
The source is determined by the device tree. If ``refin-supply`` is present,
then the external reference is used, otherwise the internal reference is used.
Oversampling
------------
This family supports oversampling to improve SNR.
In software mode, the following ratios are available:
1 (oversampling disabled)/2/4/8/16/32/64/128/256.
Unimplemented features
----------------------
- 2/4/8 SDO lines
- 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
==============
IIO triggered buffer
--------------------
This driver supports IIO triggered buffers, with a "built in" trigger, i.e the
trigger is allocated and linked by the driver, and a new conversion is triggered
as soon as the samples are transferred, and a timestamp channel is added to make
up for the potential jitter induced by the delays in the interrupt handling.
IIO backend buffer
------------------
When IIO backend is used, the trigger is not needed, and the sample rate is
considered as stable. There is no timestamp channel. The communication is
delegated to an external logic, called a backend, and the backend's driver
handles the buffer. When this mode is enabled, the driver cannot control the
conversion pin, because the busy pin is bound to the backend.
linux-7.2.3/Documentation/iio/ad7625.rst
+91
View File
@@ -0,0 +1,91 @@
.. SPDX-License-Identifier: GPL-2.0-only
====================
AD7625 driver
====================
ADC driver for Analog Devices Inc. AD7625, AD7626, AD7960, and AD7961
devices. The module name is ``ad7625``.
Supported devices
=================
The following chips are supported by this driver:
* `AD7625 <https://www.analog.com/AD7625>`_
* `AD7626 <https://www.analog.com/AD7626>`_
* `AD7960 <https://www.analog.com/AD7960>`_
* `AD7961 <https://www.analog.com/AD7961>`_
The driver requires use of the Pulsar LVDS HDL project:
* `Pulsar LVDS HDL <http://analogdevicesinc.github.io/hdl/projects/pulsar_lvds/index.html>`_
To trigger conversions and enable subsequent data transfer, the devices
require coupled PWM signals with a phase offset.
Supported features
==================
Conversion control modes
------------------------
The driver currently supports one of two possible LVDS conversion control methods.
Echoed-Clock interface mode
^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block::
+----------------+
+xxxxxxxxxxxxxxxxxxxxxxxxxx| CNV |
X | |
v | HOST |
+----------------------------+ | |
| CNV+/CNV- DCO+/DCO- |xxxxxxx>| CLK_IN |
| | | |
| | | |
| AD7625 D+/D- |xxxxxxx>| DATA_IN |
| | | |
| | | |
| CLK+/CLK- |<xxxxxxx| CLK & CLK_GATE |
+----------------------------+ | |
+----------------+
Reference voltage
-----------------
Three possible reference voltage sources are supported:
- Internal reference (only available on AD7625 and AD7626)
- External reference and internal buffer
- External reference
The source is determined by the device tree. If ``ref-supply`` is present, then
the external reference is used. If ``refin-supply`` is present, then the internal
buffer is used. If neither is present, then the internal reference is used.
Unimplemented features
----------------------
- Self-clocked mode
Device attributes
=================
The AD762x is a fully-differential ADC and has the following attributes:
+---------------------------------------+--------------------------------------------------------------+
| Attribute | Description |
+=======================================+==============================================================+
| ``scale`` | Scale factor to convert raw value from buffered reads to mV. |
+---------------------------------------+--------------------------------------------------------------+
Device buffers
==============
This driver supports IIO triggered buffers.
See :doc:`iio_devbuf` for more information.
linux-7.2.3/Documentation/iio/ad7944.rst
+178
View File
@@ -0,0 +1,178 @@
.. SPDX-License-Identifier: GPL-2.0-only
=============
AD7944 driver
=============
ADC driver for Analog Devices Inc. AD7944 and similar devices. The module name
is ``ad7944``.
Supported devices
=================
The following chips are supported by this driver:
* `AD7944 <https://www.analog.com/AD7944>`_
* `AD7985 <https://www.analog.com/AD7985>`_
* `AD7986 <https://www.analog.com/AD7986>`_
Supported features
==================
SPI wiring modes
----------------
The driver currently supports three of the many possible SPI wiring configurations.
CS mode, 3-wire, without busy indicator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block::
+-------------+
+--------------------| CS |
v | |
VIO +--------------------+ | HOST |
| | CNV | | |
+--->| SDI AD7944 SDO |-------->| SDI |
| SCK | | |
+--------------------+ | |
^ | |
+--------------------| SCLK |
+-------------+
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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block::
+-------------+
+-----------------------------------| CS |
| | |
| +--------------------| GPIO |
| v | |
| +--------------------+ | HOST |
| | CNV | | |
+--->| SDI AD7944 SDO |-------->| SDI |
| SCK | | |
+--------------------+ | |
^ | |
+--------------------| SCLK |
+-------------+
To select this mode in the device tree, omit the ``adi,spi-mode`` property and
provide the ``cnv-gpios`` property.
Chain mode, without busy indicator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block::
+-------------+
+-------------------------+--------------------| CS |
v v | |
+--------------------+ +--------------------+ | HOST |
| CNV | | CNV | | |
+--->| SDI AD7944 SDO |--->| SDI AD7944 SDO |-------->| SDI |
| | SCK | | SCK | | |
GND +--------------------+ +--------------------+ | |
^ ^ | |
+-------------------------+--------------------| SCLK |
+-------------+
To select this mode in the device tree, set the ``adi,spi-mode`` property to
``"chain"``, add the ``spi-cs-high`` flag, add the ``#daisy-chained-devices``
property, and omit the ``cnv-gpios`` property.
Reference voltage
-----------------
All 3 possible reference voltage sources are supported:
- Internal reference
- External 1.2V reference and internal buffer
- External reference
The source is determined by the device tree. If ``ref-supply`` is present, then
the external reference is used. If ``refin-supply`` is present, then the internal
buffer is used. If neither is present, then the internal reference is used.
Unimplemented features
----------------------
- ``BUSY`` indication
Device attributes
=================
There are two types of ADCs in this family, pseudo-differential and fully
differential. The channel name is different depending on the type of ADC.
Pseudo-differential ADCs
------------------------
AD7944 and AD7985 are pseudo-differential ADCs and have the following attributes:
+---------------------------------------+--------------------------------------------------------------+
| Attribute | Description |
+=======================================+==============================================================+
| ``in_voltage0_raw`` | Raw ADC voltage value (*IN+* referenced to ground sense). |
+---------------------------------------+--------------------------------------------------------------+
| ``in_voltage0_scale`` | Scale factor to convert raw value to mV. |
+---------------------------------------+--------------------------------------------------------------+
In "chain" mode, additional chips will appear as additional voltage input
channels, e.g. ``in_voltage1_raw``.
Fully-differential ADCs
-----------------------
AD7986 is a fully-differential ADC and has the following attributes:
+---------------------------------------+--------------------------------------------------------------+
| Attribute | Description |
+=======================================+==============================================================+
| ``in_voltage0-voltage1_raw`` | Raw ADC voltage value (*IN+* - *IN-*). |
+---------------------------------------+--------------------------------------------------------------+
| ``in_voltage0-voltage1_scale`` | Scale factor to convert raw value to mV. |
+---------------------------------------+--------------------------------------------------------------+
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
==============
This driver supports IIO triggered buffers.
See :doc:`iio_devbuf` for more information.
linux-7.2.3/Documentation/iio/ade9000.rst
+268
View File
@@ -0,0 +1,268 @@
.. SPDX-License-Identifier: GPL-2.0
===============
ADE9000 driver
===============
This driver supports Analog Device's ADE9000 energy measurement IC on SPI bus.
1. Supported devices
====================
* `ADE9000 <https://www.analog.com/media/en/technical-documentation/data-sheets/ADE9000.pdf>`_
The ADE9000 is a highly accurate, fully integrated, multiphase energy and power
quality monitoring device. Superior analog performance and a digital signal
processing (DSP) core enable accurate energy monitoring over a wide dynamic
range. An integrated high end reference ensures low drift over temperature
with a combined drift of less than ±25 ppm/°C maximum for the entire channel
including a programmable gain amplifier (PGA) and an analog-to-digital
converter (ADC).
2. Device attributes
====================
Power and energy measurements are provided for voltage, current, active power,
reactive power, apparent power, and power factor across three phases.
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 question. These files are consistently generalized and documented in
the IIO ABI documentation.
The following tables show the ADE9000 related device files, found in the
specific device folder path ``/sys/bus/iio/devices/iio:deviceX``.
+---------------------------------------------------+----------------------------------------------------------+
| Current measurement related device files | Description |
+---------------------------------------------------+----------------------------------------------------------+
| in_current[0-2]_raw | Raw current measurement for phases A, B, C. |
+---------------------------------------------------+----------------------------------------------------------+
| in_current[0-2]_scale | Scale for current channels. |
+---------------------------------------------------+----------------------------------------------------------+
| in_current[0-2]_calibscale | Calibration gain for current channels (AIGAIN reg). |
+---------------------------------------------------+----------------------------------------------------------+
| in_altcurrent[0-2]_rms_raw | RMS current measurement for phases A, B, C. |
+---------------------------------------------------+----------------------------------------------------------+
| in_altcurrent[0-2]_rms_scale | Scale for RMS current channels. |
+---------------------------------------------------+----------------------------------------------------------+
| in_altcurrent[0-2]_rms_calibbias | RMS offset correction for current channels (IRMSOS reg). |
+---------------------------------------------------+----------------------------------------------------------+
+---------------------------------------------------+----------------------------------------------------------+
| Voltage measurement related device files | Description |
+---------------------------------------------------+----------------------------------------------------------+
| in_voltage[0-2]_raw | Raw voltage measurement for phases A, B, C. |
+---------------------------------------------------+----------------------------------------------------------+
| in_voltage[0-2]_scale | Scale for voltage channels. |
+---------------------------------------------------+----------------------------------------------------------+
| in_voltage[0-2]_calibscale | Calibration gain for voltage channels (AVGAIN reg). |
+---------------------------------------------------+----------------------------------------------------------+
| in_voltage[0-2]_frequency | Measured line frequency from instantaneous voltage. |
+---------------------------------------------------+----------------------------------------------------------+
| in_altvoltage[0-2]_rms_raw | RMS voltage measurement for phases A, B, C. |
+---------------------------------------------------+----------------------------------------------------------+
| in_altvoltage[0-2]_rms_scale | Scale for RMS voltage channels. |
+---------------------------------------------------+----------------------------------------------------------+
| in_altvoltage[0-2]_rms_calibbias | RMS offset correction for voltage channels (VRMSOS reg). |
+---------------------------------------------------+----------------------------------------------------------+
+---------------------------------------------------+----------------------------------------------------------+
| Power measurement related device files | Description |
+---------------------------------------------------+----------------------------------------------------------+
| in_power[0-2]_active_raw | Active power measurement for phases A, B, C. |
+---------------------------------------------------+----------------------------------------------------------+
| in_power[0-2]_active_scale | Scale for active power channels. |
+---------------------------------------------------+----------------------------------------------------------+
| in_power[0-2]_active_calibbias | Calibration offset for active power (xWATTOS regs). |
+---------------------------------------------------+----------------------------------------------------------+
| in_power[0-2]_active_calibscale | Calibration gain for active power (APGAIN reg). |
+---------------------------------------------------+----------------------------------------------------------+
| in_power[0-2]_reactive_raw | Reactive power measurement for phases A, B, C. |
+---------------------------------------------------+----------------------------------------------------------+
| in_power[0-2]_reactive_scale | Scale for reactive power channels. |
+---------------------------------------------------+----------------------------------------------------------+
| in_power[0-2]_reactive_calibbias | Calibration offset for reactive power (xVAROS regs). |
+---------------------------------------------------+----------------------------------------------------------+
| in_power[0-2]_apparent_raw | Apparent power measurement for phases A, B, C. |
+---------------------------------------------------+----------------------------------------------------------+
| in_power[0-2]_apparent_scale | Scale for apparent power channels. |
+---------------------------------------------------+----------------------------------------------------------+
| in_power[0-2]_powerfactor | Power factor for phases A, B, C. |
+---------------------------------------------------+----------------------------------------------------------+
+---------------------------------------------------+----------------------------------------------------------+
| Energy measurement related device files | Description |
+---------------------------------------------------+----------------------------------------------------------+
| in_energy[0-2]_active_raw | Active energy measurement for phases A, B, C. |
+---------------------------------------------------+----------------------------------------------------------+
| in_energy[0-2]_reactive_raw | Reactive energy measurement for phases A, B, C. |
+---------------------------------------------------+----------------------------------------------------------+
| in_energy[0-2]_apparent_raw | Apparent energy measurement for phases A, B, C. |
+---------------------------------------------------+----------------------------------------------------------+
+------------------------------+------------------------------------------------------------------+
| Shared device attributes | Description |
+------------------------------+------------------------------------------------------------------+
| name | Name of the IIO device. |
+------------------------------+------------------------------------------------------------------+
| filter_type | Waveform buffer filter type (sinc4, sinc4+lp). |
+------------------------------+------------------------------------------------------------------+
| filter_type_available | Available filter types for waveform buffer. |
+------------------------------+------------------------------------------------------------------+
3. Calibration and scaling
===========================
The ADE9000 provides multiple levels of gain and offset correction:
**Calibration Gain (per-channel)**
Fine-tuning calibration gains applied in the digital domain for each channel type.
Controlled via ``calibscale`` attributes (AIGAIN, AVGAIN, APGAIN registers).
**Calibration Bias (per-channel)**
Hardware calibration offsets applied by the device internally:
- Power measurements: Controlled via ``calibbias`` attributes for power channels (xWATTOS, xVAROS registers).
- RMS measurements: Controlled via ``calibbias`` attributes for RMS channels (IRMSOS, VRMSOS registers).
These are internal chip calibrations, not userspace-applied offsets.
4. Event attributes
===================
The ADE9000 provides various interrupts that are mapped to IIO events.
Event functionality is only available if the corresponding interrupts are
connected in the device tree.
+---------------------------------------------------+----------------------------------------------------------+
| IIO Event Attribute | ADE9000 Datasheet Equivalent |
+---------------------------------------------------+----------------------------------------------------------+
| in_voltage[0-2]_thresh_either_en | Zero crossing detection interrupt (ZXVx) |
+---------------------------------------------------+----------------------------------------------------------+
| in_altvoltage[0-2]_rms_thresh_rising_en | RMS swell detection interrupt (SWELLx) |
+---------------------------------------------------+----------------------------------------------------------+
| in_altvoltage[0-2]_rms_thresh_rising_value | RMS swell threshold (SWELL_LVL register) |
+---------------------------------------------------+----------------------------------------------------------+
| in_altvoltage[0-2]_rms_thresh_falling_en | RMS sag/dip detection interrupt (DIPx) |
+---------------------------------------------------+----------------------------------------------------------+
| in_altvoltage[0-2]_rms_thresh_falling_value | RMS sag/dip threshold (DIP_LVL register) |
+---------------------------------------------------+----------------------------------------------------------+
| in_current[0-2]_thresh_either_en | Current zero crossing detection interrupt (ZXIx) |
+---------------------------------------------------+----------------------------------------------------------+
Event directions:
- ``rising``: Upper threshold crossing (swell detection)
- ``falling``: Lower threshold crossing (sag/dip detection)
- ``either``: Any threshold crossing (zero crossing detection)
- ``none``: Timeout or non-directional events
**Note**: Event attributes are only available if the corresponding interrupts
(irq0, irq1, dready) are specified in the device tree. The driver works without
interrupts but with reduced functionality.
5. Device buffers
=================
This driver supports IIO buffers for waveform capture. Buffer functionality
requires the dready interrupt to be connected.
The device supports capturing voltage and current waveforms for power quality
analysis. The waveform buffer can be configured to capture data from different
channel combinations.
Supported channel combinations for buffered capture:
- Phase A: voltage and current (IA + VA)
- Phase B: voltage and current (IB + VB)
- Phase C: voltage and current (IC + VC)
- All phases: all voltage and current channels
- Individual channels: IA, VA, IB, VB, IC, VC
Usage examples
--------------
Enable waveform capture for Phase A:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_current0_en
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_voltage0_en
Set buffer length and enable:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> echo 100 > buffer/length
root:/sys/bus/iio/devices/iio:device0> echo 1 > buffer/enable
6. Clock output
===============
The ADE9000 can provide a clock output via the CLKOUT pin when using an external
crystal/clock source. This feature is enabled by specifying ``#clock-cells = <0>``
in the device tree. The output clock will be registered as "clkout" and can be
referenced by other devices.
7. Usage examples
=================
Show device name:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> cat name
ade9000
Read voltage measurements:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> cat in_voltage0_raw
12345
root:/sys/bus/iio/devices/iio:device0> cat in_voltage0_scale
0.000030517
- Phase A voltage = in_voltage0_raw * in_voltage0_scale = 0.3769 V
Read power measurements:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> cat in_power0_active_raw
5678
root:/sys/bus/iio/devices/iio:device0> cat in_power0_scale
0.000244140
- Phase A active power = in_power0_active_raw * in_power0_scale = 1.386 W
Configure calibration gains:
.. code-block:: bash
# Set current channel 0 calibration gain
root:/sys/bus/iio/devices/iio:device0> echo 0x800000 > in_current0_calibscale
# Set voltage channel 0 calibration gain
root:/sys/bus/iio/devices/iio:device0> echo 0x7FFFFF > in_voltage0_calibscale
Configure RMS voltage event thresholds (requires interrupts):
.. code-block:: bash
# Set RMS sag detection threshold
root:/sys/bus/iio/devices/iio:device0> echo 180000 > events/in_altvoltage0_rms_thresh_falling_value
# Enable RMS sag detection
root:/sys/bus/iio/devices/iio:device0> echo 1 > events/in_altvoltage0_rms_thresh_falling_en
# Set RMS swell detection threshold
root:/sys/bus/iio/devices/iio:device0> echo 260000 > events/in_altvoltage0_rms_thresh_rising_value
# Enable RMS swell detection
root:/sys/bus/iio/devices/iio:device0> echo 1 > events/in_altvoltage0_rms_thresh_rising_en
8. IIO Interfacing Tools
========================
See Documentation/iio/iio_tools.rst for the description of the available IIO
interfacing tools.
linux-7.2.3/Documentation/iio/adis16475.rst
+384
View File
@@ -0,0 +1,384 @@
.. SPDX-License-Identifier: GPL-2.0
================
ADIS16475 driver
================
This driver supports Analog Device's IMUs on SPI bus.
1. Supported devices
====================
* `ADIS16465 <https://www.analog.com/ADIS16465>`_
* `ADIS16467 <https://www.analog.com/ADIS16467>`_
* `ADIS16470 <https://www.analog.com/ADIS16470>`_
* `ADIS16475 <https://www.analog.com/ADIS16475>`_
* `ADIS16477 <https://www.analog.com/ADIS16477>`_
* `ADIS16500 <https://www.analog.com/ADIS16500>`_
* `ADIS16505 <https://www.analog.com/ADIS16505>`_
* `ADIS16507 <https://www.analog.com/ADIS16507>`_
Each supported device is a precision, miniature microelectromechanical system
(MEMS) inertial measurement unit (IMU) that includes a triaxial gyroscope and a
triaxial accelerometer. Each inertial sensor in the IMU device combines with
signal conditioning that optimizes dynamic performance. The factory calibration
characterizes each sensor for sensitivity, bias, alignment, linear acceleration
(gyroscope bias), and point of percussion (accelerometer location). As a result,
each sensor has dynamic compensation formulas that provide accurate sensor
measurements over a broad set of conditions.
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.
The signal chain of each inertial sensor (accelerometers and gyroscopes)
includes the application of unique correction formulas, which are derived from
extensive characterization of bias, sensitivity, alignment, response to linear
acceleration (gyroscopes), and point of percussion (accelerometer location)
over a temperature range of −40°C to +85°C, for each ADIS device. These
correction formulas are not accessible, but users do have the opportunity to
adjust the bias for each sensor individually through the calibbias attribute.
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 adis16475 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_x_calibbias | Calibration offset 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_raw | Raw Y-axis accelerometer channel value. |
+-------------------------------------------+----------------------------------------------------------+
| in_accel_z_calibbias | Calibration offset 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_x_calibbias | Calibration offset 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_raw | Raw Y-axis gyroscope channel value. |
+---------------------------------------+------------------------------------------------------+
| in_anglvel_z_calibbias | Calibration offset 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_scale | Scale for the temperature sensor channel. |
+----------------------------------+-------------------------------------------+
+-------------------------------+---------------------------------------------------------+
| Miscellaneous device files | Description |
+-------------------------------+---------------------------------------------------------+
| name | Name of the IIO device. |
+-------------------------------+---------------------------------------------------------+
| sampling_frequency | Currently selected sample rate. |
+-------------------------------+---------------------------------------------------------+
| filter_low_pass_3db_frequency | Bandwidth for the accelerometer and gyroscope channels. |
+-------------------------------+---------------------------------------------------------+
The following table shows the adis16475 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 (e.g. 16475, 16500, 16505, etc.). |
+----------------------+-------------------------------------------------------------------------+
| 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 adis16475 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
adis16505-2
Show accelerometer channels value:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_raw
-275924
root:/sys/bus/iio/devices/iio:device0> cat in_accel_y_raw
-30142222
root:/sys/bus/iio/devices/iio:device0> cat in_accel_z_raw
261265769
root:/sys/bus/iio/devices/iio:device0> cat in_accel_scale
0.000000037
- X-axis acceleration = in_accel_x_raw * in_accel_scale = −0.010209188 m/s^2
- Y-axis acceleration = in_accel_y_raw * in_accel_scale = −1.115262214 m/s^2
- Z-axis acceleration = in_accel_z_raw * in_accel_scale = 9.666833453 m/s^2
Show gyroscope channels value:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_x_raw
-3324626
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_raw
1336980
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_z_raw
-602983
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_scale
0.000000006
- X-axis angular velocity = in_anglvel_x_raw * in_anglvel_scale = −0.019947756 rad/s
- Y-axis angular velocity = in_anglvel_y_raw * in_anglvel_scale = 0.00802188 rad/s
- Z-axis angular velocity = in_anglvel_z_raw * in_anglvel_scale = −0.003617898 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
2000.000000
root:/sys/bus/iio/devices/iio:device0> echo 1000 > sampling_frequency
1000.000000
Set bandwidth for accelerometer and gyroscope:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> cat filter_low_pass_3db_frequency
720
root:/sys/bus/iio/devices/iio:device0> echo 360 > filter_low_pass_3db_frequency
root:/sys/bus/iio/devices/iio:device0> cat filter_low_pass_3db_frequency
360
Show serial number:
.. code-block:: bash
root:/sys/kernel/debug/iio/iio:device0> cat serial_number
0x04f9
Show product id:
.. code-block:: bash
root:/sys/kernel/debug/iio/iio:device0> cat product_id
16505
Show flash count:
.. code-block:: bash
root:/sys/kernel/debug/iio/iio:device0> cat flash_count
150
Show firmware revision:
.. code-block:: bash
root:/sys/kernel/debug/iio/iio:device0> cat firmware_revision
1.6
Show firmware date:
.. code-block:: bash
root:/sys/kernel/debug/iio/iio:device0> cat firmware_date
06-27-2019
3. Device buffers
=================
This driver supports IIO buffers.
All devices support retrieving the raw acceleration, gyroscope and temperature
measurements using buffers.
The following device families also support retrieving the delta velocity, delta
angle and temperature measurements using buffers:
- ADIS16477
- ADIS16500
- ADIS16505
- ADIS16507
However, when retrieving acceleration or gyroscope data using buffers, delta
readings will not be available and vice versa.
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 adis16505-2-dev0 > trigger/current_trigger
root:/sys/bus/iio/devices/iio:device0> cat trigger/current_trigger
adis16505-2-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
...
00001680 01 1f 00 00 ff ff fe ef 00 00 47 bf 00 03 35 55 |..........G...5U|
00001690 01 1f 00 00 ff ff ff d9 00 00 46 f1 00 03 35 35 |..........F...55|
000016a0 01 1f 00 00 ff ff fe fc 00 00 46 cb 00 03 35 7b |..........F...5{|
000016b0 01 1f 00 00 ff ff fe 41 00 00 47 0d 00 03 35 8b |.......A..G...5.|
000016c0 01 1f 00 00 ff ff fe 37 00 00 46 b4 00 03 35 90 |.......7..F...5.|
000016d0 01 1d 00 00 ff ff fe 5a 00 00 45 d7 00 03 36 08 |.......Z..E...6.|
000016e0 01 1b 00 00 ff ff fe fb 00 00 45 e7 00 03 36 60 |..........E...6`|
000016f0 01 1a 00 00 ff ff ff 17 00 00 46 bc 00 03 36 de |..........F...6.|
00001700 01 1a 00 00 ff ff fe 59 00 00 46 d7 00 03 37 b8 |.......Y..F...7.|
00001710 01 1a 00 00 ff ff fe ae 00 00 46 95 00 03 37 ba |..........F...7.|
00001720 01 1a 00 00 ff ff fe c5 00 00 46 63 00 03 37 9f |..........Fc..7.|
00001730 01 1a 00 00 ff ff fe 55 00 00 46 89 00 03 37 c1 |.......U..F...7.|
00001740 01 1a 00 00 ff ff fe 31 00 00 46 aa 00 03 37 f7 |.......1..F...7.|
...
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.
linux-7.2.3/Documentation/iio/adis16480.rst
+446
View File
@@ -0,0 +1,446 @@
.. SPDX-License-Identifier: GPL-2.0
================
ADIS16480 driver
================
This driver supports Analog Device's IMUs on SPI bus.
1. Supported devices
====================
* `ADIS16375 <https://www.analog.com/ADIS16375>`_
* `ADIS16480 <https://www.analog.com/ADIS16480>`_
* `ADIS16485 <https://www.analog.com/ADIS16485>`_
* `ADIS16486 <https://www.analog.com/ADIS16486>`_
* `ADIS16487 <https://www.analog.com/ADIS16487>`_
* `ADIS16488 <https://www.analog.com/ADIS16488>`_
* `ADIS16489 <https://www.analog.com/ADIS16489>`_
* `ADIS16490 <https://www.analog.com/ADIS16490>`_
* `ADIS16495 <https://www.analog.com/ADIS16495>`_
* `ADIS16497 <https://www.analog.com/ADIS16497>`_
* `ADIS16545 <https://www.analog.com/ADIS16545>`_
* `ADIS16547 <https://www.analog.com/ADIS16547>`_
Each supported device is a complete inertial system that includes a triaxial
gyroscope and a triaxial accelerometer. Each inertial sensor in device combines
with signal conditioning that optimizes dynamic performance. 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.
ADIS16480 and ADIS16488 also provide access to barometric pressure data and
triaxial magnetometer measurements.
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 adis16480 related device files, found in the
specific device folder path ``/sys/bus/iio/devices/iio:deviceX``.
**Available only for ADIS16480 and ADIS16488:**
+------------------------------------------+---------------------------------------------------------+
| 3-Axis Magnetometer related device files | Description |
+------------------------------------------+---------------------------------------------------------+
| in_magn_scale | Scale for the magnetometer channels. |
+------------------------------------------+---------------------------------------------------------+
| in_magn_x_calibbias | Calibration offset for the X-axis magnetometer channel. |
+------------------------------------------+---------------------------------------------------------+
| in_magn_x_filter_low_pass_3db_frequency | Bandwidth for the X-axis magnetometer channel. |
+------------------------------------------+---------------------------------------------------------+
| in_magn_x_raw | Raw X-axis magnetometer channel value. |
+------------------------------------------+---------------------------------------------------------+
| in_magn_y_calibbias | Calibration offset for the Y-axis magnetometer channel. |
+------------------------------------------+---------------------------------------------------------+
| in_magn_y_filter_low_pass_3db_frequency | Bandwidth for the Y-axis magnetometer channel. |
+------------------------------------------+---------------------------------------------------------+
| in_magn_y_raw | Raw Y-axis magnetometer channel value. |
+------------------------------------------+---------------------------------------------------------+
| in_magn_z_calibbias | Calibration offset for the Z-axis magnetometer channel. |
+------------------------------------------+---------------------------------------------------------+
| in_magn_z_filter_low_pass_3db_frequency | Bandwidth for the Z-axis magnetometer channel. |
+------------------------------------------+---------------------------------------------------------+
| in_magn_z_raw | Raw Z-axis magnetometer channel value. |
+------------------------------------------+---------------------------------------------------------+
+------------------------------------------+-----------------------------------------------------+
| Barometric pressure sensor related files | Description |
+------------------------------------------+-----------------------------------------------------+
| in_pressure0_calibbias | Calibration offset for barometric pressure channel. |
+------------------------------------------+-----------------------------------------------------+
| in_pressure0_raw | Raw barometric pressure channel value. |
+------------------------------------------+-----------------------------------------------------+
| in_pressure0_scale | Scale for the barometric pressure sensor channel. |
+------------------------------------------+-----------------------------------------------------+
**Available for all supported devices:**
+-------------------------------------------+----------------------------------------------------------+
| 3-Axis Accelerometer related device files | Description |
+-------------------------------------------+----------------------------------------------------------+
| in_accel_scale | Scale 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_filter_low_pass_3db_frequency | Bandwidth 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_filter_low_pass_3db_frequency | Bandwidth 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_filter_low_pass_3db_frequency | Bandwidth 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_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_filter_low_pass_3db_frequency | Bandwidth 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_filter_low_pass_3db_frequency | Bandwidth 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_filter_low_pass_3db_frequency | Bandwidth 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 adis16480 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 (e.g. 16480, 16488, 16545, etc.). |
+----------------------+-------------------------------------------------------------------------+
| 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 adis16480 driver offers data for 7 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 |
+--------------------------------------+---------------------------+
| Magnetic field along X, Y and Z axis | Gauss |
+--------------------------------------+---------------------------+
| Barometric pressure | kilo Pascal |
+--------------------------------------+---------------------------+
Usage examples
--------------
Show device name:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> cat name
adis16545-1
Show accelerometer channels value:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_raw
1376728
root:/sys/bus/iio/devices/iio:device0> cat in_accel_y_raw
4487621
root:/sys/bus/iio/devices/iio:device0> cat in_accel_z_raw
262773792
root:/sys/bus/iio/devices/iio:device0> cat in_accel_scale
0.000000037
- X-axis acceleration = in_accel_x_raw * in_accel_scale = 0.050938936 m/s^2
- Y-axis acceleration = in_accel_y_raw * in_accel_scale = 0.166041977 m/s^2
- Z-axis acceleration = in_accel_z_raw * in_accel_scale = 9.722630304 m/s^2
Show gyroscope channels value:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_x_raw
-1041702
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_raw
-273013
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_z_raw
2745116
root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_scale
0.000000001
- X-axis angular velocity = in_anglvel_x_raw * in_anglvel_scale = −0.001041702 rad/s
- Y-axis angular velocity = in_anglvel_y_raw * in_anglvel_scale = −0.000273013 rad/s
- Z-axis angular velocity = in_anglvel_z_raw * in_anglvel_scale = 0.002745116 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
4250.000000
root:/sys/bus/iio/devices/iio:device0> echo 1000 > sampling_frequency
1062.500000
Set bandwidth for accelerometer channels:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_filter_low_pass_3db_frequency
0
root:/sys/bus/iio/devices/iio:device0> echo 300 > in_accel_x_filter_low_pass_3db_frequency
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_filter_low_pass_3db_frequency
300
Show serial number:
.. code-block:: bash
root:/sys/kernel/debug/iio/iio:device0> cat serial_number
0x000c
Show product id:
.. code-block:: bash
root:/sys/kernel/debug/iio/iio:device0> cat product_id
16545
Show flash count:
.. code-block:: bash
root:/sys/kernel/debug/iio/iio:device0> cat flash_count
88
Show firmware revision:
.. code-block:: bash
root:/sys/kernel/debug/iio/iio:device0> cat firmware_revision
1.4
Show firmware date:
.. code-block:: bash
root:/sys/kernel/debug/iio/iio:device0> cat firmware_date
09-23-2023
3. Device buffers
=================
This driver supports IIO buffers.
All devices support retrieving the raw acceleration, gyroscope and temperature
measurements using buffers.
The following device families also support retrieving the delta velocity, delta
angle and temperature measurements using buffers:
- ADIS16545
- ADIS16547
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 adis16545-1-dev0 > trigger/current_trigger
root:/sys/bus/iio/devices/iio:device0> cat trigger/current_trigger
adis16545-1-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::
root:/sys/bus/iio/devices/iio:device0> hexdump -C /dev/iio\:device0
...
00006aa0 09 62 00 00 ff ff fc a4 00 00 01 69 00 03 3c 08 |.b.........i..<.|
00006ab0 09 61 00 00 00 00 02 96 00 00 02 8f 00 03 37 50 |.a............7P|
00006ac0 09 61 00 00 00 00 12 3d 00 00 0b 89 00 03 2c 0b |.a.....=......,.|
00006ad0 09 61 00 00 00 00 1e dc 00 00 16 dd 00 03 25 bf |.a............%.|
00006ae0 09 61 00 00 00 00 1e e3 00 00 1b bf 00 03 27 0b |.a............'.|
00006af0 09 61 00 00 00 00 15 50 00 00 19 44 00 03 30 fd |.a.....P...D..0.|
00006b00 09 61 00 00 00 00 09 0e 00 00 14 41 00 03 3d 7f |.a.........A..=.|
00006b10 09 61 00 00 ff ff ff f0 00 00 0e bc 00 03 48 d0 |.a............H.|
00006b20 09 63 00 00 00 00 00 9f 00 00 0f 37 00 03 4c fe |.c.........7..L.|
00006b30 09 64 00 00 00 00 0b f6 00 00 18 92 00 03 43 22 |.d............C"|
00006b40 09 64 00 00 00 00 18 df 00 00 22 33 00 03 33 ab |.d........"3..3.|
00006b50 09 63 00 00 00 00 1e 81 00 00 26 be 00 03 29 60 |.c........&...)`|
00006b60 09 63 00 00 00 00 1b 13 00 00 22 2f 00 03 23 91 |.c........"/..#.|
...
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.
linux-7.2.3/Documentation/iio/adis16550.rst
+376
View File
@@ -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.
linux-7.2.3/Documentation/iio/adxl313.rst
+293
View File
@@ -0,0 +1,293 @@
.. SPDX-License-Identifier: GPL-2.0
===============
ADXL313 driver
===============
This driver supports Analog Device's ADXL313 on SPI/I2C bus.
1. Supported devices
====================
* `ADXL313 <https://www.analog.com/ADXL313>`_
The ADXL313 is a low noise density, low power, 3-axis accelerometer with
selectable measurement ranges. The ADXL313 supports the ±0.5 g, ±1 g, ±2 g and
±4 g ranges.
2. Device attributes
====================
Accelerometer measurements are always provided.
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 adxl313 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_x_calibbias | Calibration offset 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_raw | Raw Y-axis accelerometer channel value. |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_z_calibbias | Calibration offset for the Z-axis accelerometer channel. |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_z_raw | Raw Z-axis accelerometer channel value. |
+---------------------------------------------------+----------------------------------------------------------+
+---------------------------------------+----------------------------------------------+
| Miscellaneous device files | Description |
+---------------------------------------+----------------------------------------------+
| name | Name of the IIO device. |
+---------------------------------------+----------------------------------------------+
| in_accel_sampling_frequency | Currently selected sample rate. |
+---------------------------------------+----------------------------------------------+
| in_accel_sampling_frequency_available | Available sampling frequency configurations. |
+---------------------------------------+----------------------------------------------+
The iio event related settings, found in ``/sys/bus/iio/devices/iio:deviceX/events``.
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_mag_adaptive_falling_period | AC coupled inactivity time. |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_mag_adaptive_falling_value | AC coupled inactivity threshold. |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_mag_adaptive_rising_value | AC coupled activity threshold. |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_mag_falling_period | Inactivity time. |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_mag_falling_value | Inactivity threshold. |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_mag_rising_value | Activity threshold. |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_x\&y\&z_mag_adaptive_falling_en | Enable or disable AC coupled inactivity events. |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_x\|y\|z_mag_adaptive_rising_en | Enable or disable AC coupled activity events. |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_x\&y\&z_mag_falling_en | Enable or disable inactivity events. |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_x\|y\|z_mag_rising_en | Enable or disable activity events. |
+---------------------------------------------------+----------------------------------------------------------+
The default coupling is DC coupled events. In this case the threshold will
be in place as such, where for the AC coupled case an adaptive threshold
(described in the datasheet) will be applied by the sensor. In general activity,
i.e. ``ACTIVITY`` or ``ACTIVITY_AC`` and inactivity i.e. ``INACTIVITY`` or
``INACTIVITY_AC``, will be linked with auto-sleep enabled when both are enabled.
This means in particular ``ACTIVITY`` can also be linked to ``INACTIVITY_AC``
and vice versa, without problem.
Note here, that ``ACTIVITY`` and ``ACTIVITY_AC`` are mutually exclusive. This
means, that the most recent configuration will be set. For instance, if
``ACTIVITY`` is enabled, and ``ACTIVITY_AC`` will be enabled, the sensor driver
will have ``ACTIVITY`` disabled, but ``ACTIVITY_AC`` enabled. The same is valid
for inactivity. In case of turning off an event, it has to match to what is
actually enabled, i.e. enabling ``ACTIVITY_AC`` and then disabling ``ACTIVITY``
is simply ignored as it is already disabled. Or, as if it was any other not
enabled event, too.
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::
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 ADXL313 driver offers data for multiple channels of a single type.
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 |
+-------------------------------------+---------------------------+
Usage examples
--------------
Show device name:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> cat name
adxl313
Show accelerometer channels value:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_raw
2
root:/sys/bus/iio/devices/iio:device0> cat in_accel_y_raw
-57
root:/sys/bus/iio/devices/iio:device0> cat in_accel_z_raw
2
root:/sys/bus/iio/devices/iio:device0> cat in_accel_scale
0.009576806
The accelerometer values will be:
- X-axis acceleration = in_accel_x_raw * in_accel_scale = 0.0191536 m/s^2
- Y-axis acceleration = in_accel_y_raw * in_accel_scale = -0.5458779 m/s^2
- Z-axis acceleration = in_accel_z_raw * in_accel_scale = 0.0191536 m/s^2
Set calibration offset for accelerometer channels. Note, that the calibration
will be rounded according to the graduation of LSB units:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias
0
root:/sys/bus/iio/devices/iio:device0> echo 50 > in_accel_x_calibbias
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias
48
Set sampling frequency:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> cat in_accel_sampling_frequency
100.000000
root:/sys/bus/iio/devices/iio:device0> cat in_accel_sampling_frequency_available
6.250000 12.500000 25.000000 50.000000 100.000000 200.000000 400.000000 800.000000 1600.000000 3200.000000
root:/sys/bus/iio/devices/iio:device0> echo 400 > in_accel_sampling_frequency
root:/sys/bus/iio/devices/iio:device0> cat in_accel_sampling_frequency
400.000000
3. Device buffers and triggers
==============================
This driver supports IIO buffers.
All devices support retrieving the raw acceleration measurements using buffers.
Usage examples
--------------
Select channels for buffer read:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_accel_x_en
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_accel_y_en
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_accel_z_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
...
000000d0 01 fc 31 00 c7 ff 03 fc 31 00 c7 ff 04 fc 33 00 |..1.....1.....3.|
000000e0 c8 ff 03 fc 32 00 c5 ff ff fc 32 00 c7 ff 0a fc |....2.....2.....|
000000f0 30 00 c8 ff 06 fc 33 00 c7 ff 01 fc 2f 00 c8 ff |0.....3...../...|
00000100 02 fc 32 00 c6 ff 04 fc 33 00 c8 ff 05 fc 33 00 |..2.....3.....3.|
00000110 ca ff 02 fc 31 00 c7 ff 02 fc 30 00 c9 ff 09 fc |....1.....0.....|
00000120 35 00 c9 ff 08 fc 35 00 c8 ff 02 fc 31 00 c5 ff |5.....5.....1...|
00000130 03 fc 32 00 c7 ff 04 fc 32 00 c7 ff 02 fc 31 00 |..2.....2.....1.|
00000140 c7 ff 08 fc 30 00 c7 ff 02 fc 32 00 c5 ff ff fc |....0.....2.....|
00000150 31 00 c5 ff 04 fc 31 00 c8 ff 03 fc 32 00 c8 ff |1.....1.....2...|
00000160 01 fc 31 00 c7 ff 05 fc 31 00 c3 ff 04 fc 31 00 |..1.....1.....1.|
00000170 c5 ff 04 fc 30 00 c7 ff 03 fc 31 00 c9 ff 03 fc |....0.....1.....|
...
Enabling activity detection:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> echo 1.28125 > ./events/in_accel_mag_rising_value
root:/sys/bus/iio/devices/iio:device0> echo 1 > ./events/in_accel_x\|y\|z_mag_rising_en
root:/sys/bus/iio/devices/iio:device0> iio_event_monitor adxl313
Found IIO device with name adxl313 with device number 0
<only while moving the sensor>
Event: time: 1748795762298351281, type: accel(x|y|z), channel: 0, evtype: mag, direction: rising
Event: time: 1748795762302653704, type: accel(x|y|z), channel: 0, evtype: mag, direction: rising
Event: time: 1748795762304340726, type: accel(x|y|z), channel: 0, evtype: mag, direction: rising
...
Disabling activity detection:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> echo 0 > ./events/in_accel_x\|y\|z_mag_rising_en
root:/sys/bus/iio/devices/iio:device0> iio_event_monitor adxl313
<nothing>
Enabling inactivity detection:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> echo 1.234375 > ./events/in_accel_mag_falling_value
root:/sys/bus/iio/devices/iio:device0> echo 5 > ./events/in_accel_mag_falling_period
root:/sys/bus/iio/devices/iio:device0> echo 1 > ./events/in_accel_x\&y\&z_mag_falling_en
root:/sys/bus/iio/devices/iio:device0> iio_event_monitor adxl313
Found IIO device with name adxl313 with device number 0
Event: time: 1748796324115962975, type: accel(x&y&z), channel: 0, evtype: mag, direction: falling
Event: time: 1748796329329981772, type: accel(x&y&z), channel: 0, evtype: mag, direction: falling
Event: time: 1748796334543399706, type: accel(x&y&z), channel: 0, evtype: mag, direction: falling
...
<every 5s now indicates inactivity>
Now, enabling activity, e.g. the AC coupled counter-part ``ACTIVITY_AC``
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> echo 1.28125 > ./events/in_accel_mag_rising_value
root:/sys/bus/iio/devices/iio:device0> echo 1 > ./events/in_accel_x\|y\|z_mag_rising_en
root:/sys/bus/iio/devices/iio:device0> iio_event_monitor adxl313
Found IIO device with name adxl313 with device number 0
<some activity with the sensor>
Event: time: 1748796880354686777, type: accel(x|y|z), channel: 0, evtype: mag_adaptive, direction: rising
<5s of inactivity, then>
Event: time: 1748796885543252017, type: accel(x&y&z), channel: 0, evtype: mag, direction: falling
<some other activity detected by accelerating the sensor>
Event: time: 1748796887756634678, type: accel(x|y|z), channel: 0, evtype: mag_adaptive, direction: rising
<again, 5s of inactivity>
Event: time: 1748796892964368352, type: accel(x&y&z), channel: 0, evtype: mag, direction: falling
<stays like this until next activity in auto-sleep>
Note, when AC coupling is in place, the event type will be of ``mag_adaptive``.
AC- or DC-coupled (the default) events are used similarly.
4. IIO Interfacing Tools
========================
See Documentation/iio/iio_tools.rst for the description of the available IIO
interfacing tools.
linux-7.2.3/Documentation/iio/adxl345.rst
+466
View File
@@ -0,0 +1,466 @@
.. SPDX-License-Identifier: GPL-2.0
===============
ADXL345 driver
===============
This driver supports Analog Device's ADXL345/375 on SPI/I2C bus.
1. Supported Devices
====================
* `ADXL345 <https://www.analog.com/ADXL345>`_
* `ADXL375 <https://www.analog.com/ADXL375>`_
The ADXL345 is a general-purpose, low-power, 3-axis accelerometer with selectable
measurement ranges. The ADXL345 supports the following ranges:
- ±2g (approx. ±19.61 m/s^2)
- ±4g (approx. ±39.23 m/s^2)
- ±8g (approx. ±78.45 m/s^2)
- ±16g (approx. ±156.91 m/s^2)
2. Device Attributes
====================
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 question. These files are consistently generalized and documented in
the IIO ABI documentation.
The following table shows the ADXL345 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_sampling_frequency | Currently selected sample rate. |
+-------------------------------------------+----------------------------------------------------------+
| in_accel_sampling_frequency_available | Available sampling frequency configurations. |
+-------------------------------------------+----------------------------------------------------------+
| in_accel_scale | Scale/range for the accelerometer channels. |
+-------------------------------------------+----------------------------------------------------------+
| in_accel_scale_available | Available scale ranges for the accelerometer channel. |
+-------------------------------------------+----------------------------------------------------------+
| in_accel_x_calibbias | Calibration offset 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_raw | Raw Y-axis accelerometer channel value. |
+-------------------------------------------+----------------------------------------------------------+
| in_accel_z_calibbias | Calibration offset for the Z-axis accelerometer channel. |
+-------------------------------------------+----------------------------------------------------------+
| in_accel_z_raw | Raw Z-axis accelerometer channel value. |
+-------------------------------------------+----------------------------------------------------------+
Channel 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.
+-------------------------------------+---------------------------+
| Channel type | Measurement unit |
+-------------------------------------+---------------------------+
| Acceleration on X, Y, and Z axes | Meters per second squared |
+-------------------------------------+---------------------------+
Sensor Events
-------------
Specific IIO events are triggered by their corresponding interrupts. The sensor
driver supports either none or a single active interrupt (INT) line, selectable
from the two available options: INT1 or INT2. The active INT line should be
specified in the device tree. If no INT line is configured, the sensor defaults
to FIFO bypass mode, where event detection is disabled and only individual
X, Y, and Z axis measurements are available.
The table below lists the ADXL345-related device files located in the
device-specific path: ``/sys/bus/iio/devices/iio:deviceX/events``.
Note that activity and inactivity detection are DC-coupled by default;
therefore, only the AC-coupled activity and inactivity events are explicitly
listed.
+---------------------------------------------+---------------------------------------------+
| Event handle | Description |
+---------------------------------------------+---------------------------------------------+
| in_accel_gesture_doubletap_en | Enable double tap detection on all axes |
+---------------------------------------------+---------------------------------------------+
| in_accel_gesture_doubletap_reset_timeout | Double tap window in [us] |
+---------------------------------------------+---------------------------------------------+
| in_accel_gesture_doubletap_scale | Double tap gesture threshold scale. |
+---------------------------------------------+---------------------------------------------+
| in_accel_gesture_doubletap_tap2_min_delay | Double tap latency in [us] |
+---------------------------------------------+---------------------------------------------+
| in_accel_gesture_doubletap_value | Double tap threshold value |
+---------------------------------------------+---------------------------------------------+
| in_accel_gesture_singletap_scale | Single tap gesture threshold scale. |
+---------------------------------------------+---------------------------------------------+
| in_accel_gesture_singletap_timeout | Single tap duration in [us] |
+---------------------------------------------+---------------------------------------------+
| in_accel_gesture_singletap_value | Single tap threshold value |
+---------------------------------------------+---------------------------------------------+
| in_accel_mag_adaptive_falling_period | AC coupled inactivity time in seconds |
+---------------------------------------------+---------------------------------------------+
| in_accel_mag_adaptive_falling_scale | AC coupled inactivity threshold scale. |
+---------------------------------------------+---------------------------------------------+
| in_accel_mag_adaptive_falling_value | AC coupled inactivity threshold |
+---------------------------------------------+---------------------------------------------+
| in_accel_mag_adaptive_rising_en | Enable AC coupled activity on X axis |
+---------------------------------------------+---------------------------------------------+
| in_accel_mag_adaptive_rising_scale | AC coupled activity threshold scale. |
+---------------------------------------------+---------------------------------------------+
| in_accel_mag_adaptive_rising_value | AC coupled activity threshold |
+---------------------------------------------+---------------------------------------------+
| in_accel_mag_falling_period | Inactivity time in seconds |
+---------------------------------------------+---------------------------------------------+
| in_accel_mag_falling_scale | DC coupled inactivity threshold scale. |
+---------------------------------------------+---------------------------------------------+
| in_accel_mag_falling_value | Inactivity threshold value |
+---------------------------------------------+---------------------------------------------+
| in_accel_mag_rising_en | Enable activity detection on X axis |
+---------------------------------------------+---------------------------------------------+
| in_accel_mag_rising_scale | DC coupled activity threshold scale. |
+---------------------------------------------+---------------------------------------------+
| in_accel_mag_rising_value | Activity threshold value |
+---------------------------------------------+---------------------------------------------+
| in_accel_x&y&z_mag_adaptive_falling_en | Enable AC coupled inactivity on all axes |
+---------------------------------------------+---------------------------------------------+
| in_accel_x&y&z_mag_falling_en | Enable inactivity detection on all axes |
+---------------------------------------------+---------------------------------------------+
| in_accel_x_gesture_singletap_en | Enable single tap detection on X axis |
+---------------------------------------------+---------------------------------------------+
| in_accel_y_gesture_singletap_en | Enable single tap detection on Y axis |
+---------------------------------------------+---------------------------------------------+
| in_accel_z_gesture_singletap_en | Enable single tap detection on Z axis |
+---------------------------------------------+---------------------------------------------+
Please refer to the sensor's datasheet for a detailed description of this
functionality.
Manually setting the **ODR** will cause the driver to estimate default values
for inactivity detection timing, where higher ODR values correspond to longer
default wait times, and lower ODR values to shorter ones. If these defaults do
not meet your application’s needs, you can explicitly configure the inactivity
wait time. Setting this value to 0 will revert to the default behavior.
When changing the **g range** configuration, the driver attempts to estimate
appropriate activity and inactivity thresholds by scaling the default values
based on the ratio of the previous range to the new one. The resulting threshold
will never be zero and will always fall between 1 and 255, corresponding to up
to 62.5 mg/LSB (0.612915 m/s^2/LSB) as specified in the datasheet. However,
you can override these estimated thresholds by setting explicit values.
When **activity** and **inactivity** events are enabled, the driver
automatically manages hysteresis behavior by setting the **link** and
**auto-sleep** bits. The link bit connects the activity and inactivity
functions, so that one follows the other. The auto-sleep function puts the
sensor into sleep mode when inactivity is detected, reducing power consumption
to the sub-12.5 Hz rate.
The inactivity time is configurable between 1 and 255 seconds. In addition to
inactivity detection, the sensor also supports free-fall detection, which, from
the IIO perspective, is treated as a fall in magnitude across all axes. In
sensor terms, free-fall is defined using an inactivity period ranging from 0.000
to 1.000 seconds.
The driver behaves as follows:
* If the configured inactivity period is 1 second or more, the driver uses the
sensor's inactivity register. This allows the event to be linked with
activity detection, use auto-sleep, and be either AC- or DC-coupled.
* If the inactivity period is less than 1 second, the event is treated as plain
inactivity or free-fall detection. In this case, auto-sleep and coupling
(AC/DC) are not applied.
* If an inactivity time of 0 seconds is configured, the driver selects a
heuristically determined default period (greater than 1 second) to optimize
power consumption. This also uses the inactivity register.
Note: According to the datasheet, the optimal ODR for detecting activity,
or inactivity (or when operating with the free-fall register) should fall within
the range of 12.5 Hz to 400 Hz. The recommended free-fall threshold is between
300 mg and 600 mg (register values 0x05 to 0x09).
In DC-coupled mode, the current acceleration magnitude is directly compared to
the values in the THRESH_ACT and THRESH_INACT registers to determine activity or
inactivity. In contrast, AC-coupled activity detection uses the acceleration
value at the start of detection as a reference point, and subsequent samples are
compared against this reference. While DC-coupling is the default mode-comparing
live values to fixed thresholds-AC-coupling relies on an internal filter
relative to the configured threshold.
AC and DC coupling modes are configured separately for activity and inactivity
detection, but only one mode can be active at a time for each. For example, if
AC-coupled activity detection is enabled and then DC-coupled mode is set, only
DC-coupled activity detection will be active. In other words, only the most
recent configuration is applied.
**Single tap** detection can be configured per the datasheet by setting the
threshold and duration parameters. When only single tap detection is enabled,
the single tap interrupt triggers as soon as the acceleration exceeds the
threshold (marking the start of the duration) and then falls below it, provided
the duration limit is not exceeded. If both single tap and double tap detections
are enabled, the single tap interrupt is triggered only after the double tap
event has been either confirmed or dismissed.
To configure **double tap** detection, you must also set the window and latency
parameters in microseconds (µs). The latency period begins once the single tap
signal drops below the threshold and acts as a waiting time during which any
spikes are ignored for double tap detection. After the latency period ends, the
detection window starts. If the acceleration rises above the threshold and then
falls below it again within this window, a double tap event is triggered upon
the fall below the threshold.
Double tap event detection is thoroughly explained in the datasheet. After a
single tap event is detected, a double tap event may follow, provided the signal
meets certain criteria. However, double tap detection can be invalidated for
three reasons:
* If the **suppress bit** is set, any acceleration spike above the tap
threshold during the tap latency period immediately invalidates the double tap
detection. In other words, no spikes are allowed during latency when the
suppress bit is active.
* The double tap event is invalid if the acceleration is above the threshold at
the start of the double tap window.
* Double tap detection is also invalidated if the acceleration duration exceeds
the limit set by the duration register.
For double tap detection, the same duration applies as for single tap: the
acceleration must rise above the threshold and then fall below it within the
specified duration. Note that the suppress bit is typically enabled when double
tap detection is active.
Usage Examples
--------------
Show device name:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> cat name
adxl345
Show accelerometer channels value:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_raw
-1
root:/sys/bus/iio/devices/iio:device0> cat in_accel_y_raw
2
root:/sys/bus/iio/devices/iio:device0> cat in_accel_z_raw
-253
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 50 > in_accel_x_calibbias
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias
50
Given the 13-bit full resolution, the available ranges are calculated by the
following formula:
.. code-block:: bash
(g * 2 * 9.80665) / (2^(resolution) - 1) * 100; for g := 2|4|8|16
Scale range configuration:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> cat ./in_accel_scale
0.004789
root:/sys/bus/iio/devices/iio:device0> cat ./in_accel_scale_available
0.004789 0.009578 0.019156 0.038312
root:/sys/bus/iio/devices/iio:device0> echo 0.019156 > ./in_accel_scale
root:/sys/bus/iio/devices/iio:device0> cat ./in_accel_scale
0.019156
Set output data rate (ODR):
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> cat ./in_accel_sampling_frequency
200.000000
root:/sys/bus/iio/devices/iio:device0> cat ./in_accel_sampling_frequency_available
0.097000 0.195000 0.390000 0.781000 1.562000 3.125000 6.250000 12.500000 25.000000 50.000000 100.000000 200.000000 400.000000 800.000000 1600.000000 3200.000000
root:/sys/bus/iio/devices/iio:device0> echo 1.562000 > ./in_accel_sampling_frequency
root:/sys/bus/iio/devices/iio:device0> cat ./in_accel_sampling_frequency
1.562000
Configure one or several events:
.. code-block:: bash
root:> cd /sys/bus/iio/devices/iio:device0
root:/sys/bus/iio/devices/iio:device0> echo 1 > ./buffer0/in_accel_x_en
root:/sys/bus/iio/devices/iio:device0> echo 1 > ./buffer0/in_accel_y_en
root:/sys/bus/iio/devices/iio:device0> echo 1 > ./buffer0/in_accel_z_en
root:/sys/bus/iio/devices/iio:device0> echo 1 > ./scan_elements/in_accel_x_en
root:/sys/bus/iio/devices/iio:device0> echo 1 > ./scan_elements/in_accel_y_en
root:/sys/bus/iio/devices/iio:device0> echo 1 > ./scan_elements/in_accel_z_en
root:/sys/bus/iio/devices/iio:device0> echo 14 > ./in_accel_x_calibbias
root:/sys/bus/iio/devices/iio:device0> echo 2 > ./in_accel_y_calibbias
root:/sys/bus/iio/devices/iio:device0> echo -250 > ./in_accel_z_calibbias
root:/sys/bus/iio/devices/iio:device0> echo 24 > ./buffer0/length
## Check the event scale factor (0.0625 * 9.80665)
root:/sys/bus/iio/devices/iio:device0> cat ./events/in_accel_gesture_doubletap_scale
0.612915
## AC coupled activity, threshold [0.612915 m/s^2/LSB]
root:/sys/bus/iio/devices/iio:device0> echo 6 > ./events/in_accel_mag_adaptive_rising_value
## AC coupled inactivity, threshold, [0.612915 m/s^2/LSB]
root:/sys/bus/iio/devices/iio:device0> echo 4 > ./events/in_accel_mag_adaptive_falling_value
## AC coupled inactivity, time [s]
root:/sys/bus/iio/devices/iio:device0> echo 3 > ./events/in_accel_mag_adaptive_falling_period
## singletap, threshold
root:/sys/bus/iio/devices/iio:device0> echo 35 > ./events/in_accel_gesture_singletap_value
## singletap, duration [us]
root:/sys/bus/iio/devices/iio:device0> echo 0.001875 > ./events/in_accel_gesture_singletap_timeout
## doubletap, window [us]
root:/sys/bus/iio/devices/iio:device0> echo 0.025 > ./events/in_accel_gesture_doubletap_reset_timeout
## doubletap, latency [us]
root:/sys/bus/iio/devices/iio:device0> echo 0.025 > ./events/in_accel_gesture_doubletap_tap2_min_delay
## AC coupled activity, enable
root:/sys/bus/iio/devices/iio:device0> echo 1 > ./events/in_accel_mag_adaptive_rising_en
## AC coupled inactivity, enable
root:/sys/bus/iio/devices/iio:device0> echo 1 > ./events/in_accel_x\&y\&z_mag_adaptive_falling_en
## singletap, enable
root:/sys/bus/iio/devices/iio:device0> echo 1 > ./events/in_accel_x_gesture_singletap_en
root:/sys/bus/iio/devices/iio:device0> echo 1 > ./events/in_accel_y_gesture_singletap_en
root:/sys/bus/iio/devices/iio:device0> echo 1 > ./events/in_accel_z_gesture_singletap_en
## doubletap, enable
root:/sys/bus/iio/devices/iio:device0> echo 1 > ./events/in_accel_gesture_doubletap_en
Verify incoming events:
.. code-block:: bash
root:# iio_event_monitor adxl345
Found IIO device with name adxl345 with device number 0
Event: time: 1739063415957073383, type: accel(z), channel: 0, evtype: mag, direction: rising
Event: time: 1739063415963770218, type: accel(z), channel: 0, evtype: mag, direction: rising
Event: time: 1739063416002563061, type: accel(z), channel: 0, evtype: gesture, direction: singletap
Event: time: 1739063426271128739, type: accel(x&y&z), channel: 0, evtype: mag, direction: falling
Event: time: 1739063436539080713, type: accel(x&y&z), channel: 0, evtype: mag, direction: falling
Event: time: 1739063438357970381, type: accel(z), channel: 0, evtype: mag, direction: rising
Event: time: 1739063446726161586, type: accel(z), channel: 0, evtype: mag, direction: rising
Event: time: 1739063446727892670, type: accel(z), channel: 0, evtype: mag, direction: rising
Event: time: 1739063446743019768, type: accel(z), channel: 0, evtype: mag, direction: rising
Event: time: 1739063446744650696, type: accel(z), channel: 0, evtype: mag, direction: rising
Event: time: 1739063446763559386, type: accel(z), channel: 0, evtype: gesture, direction: singletap
Event: time: 1739063448818126480, type: accel(x&y&z), channel: 0, evtype: mag, direction: falling
...
Activity and inactivity belong together and indicate state changes as follows
.. code-block:: bash
root:# iio_event_monitor adxl345
Found IIO device with name adxl345 with device number 0
Event: time: 1744648001133946293, type: accel(x), channel: 0, evtype: mag, direction: rising
<after inactivity time elapsed>
Event: time: 1744648057724775499, type: accel(x&y&z), channel: 0, evtype: mag, direction: falling
...
3. Device Buffers
=================
This driver supports IIO buffers.
All devices support retrieving the raw acceleration and temperature measurements
using buffers.
Usage examples
--------------
Select channels for buffer read:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_accel_x_en
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_accel_y_en
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_accel_z_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:> iio_readdev -b 16 -s 1024 adxl345 | hexdump -d
WARNING: High-speed mode not enabled
0000000 00003 00012 00013 00005 00010 00011 00005 00011
0000010 00013 00004 00012 00011 00003 00012 00014 00007
0000020 00011 00013 00004 00013 00014 00003 00012 00013
0000030 00004 00012 00013 00005 00011 00011 00005 00012
0000040 00014 00005 00012 00014 00004 00010 00012 00004
0000050 00013 00011 00003 00011 00012 00005 00011 00013
0000060 00003 00012 00012 00003 00012 00012 00004 00012
0000070 00012 00003 00013 00013 00003 00013 00012 00005
0000080 00012 00013 00003 00011 00012 00005 00012 00013
0000090 00003 00013 00011 00005 00013 00014 00003 00012
00000a0 00012 00003 00012 00013 00004 00012 00015 00004
00000b0 00014 00011 00003 00014 00013 00004 00012 00011
00000c0 00004 00012 00013 00004 00014 00011 00004 00013
00000d0 00012 00002 00014 00012 00005 00012 00013 00005
00000e0 00013 00013 00003 00013 00013 00005 00012 00013
00000f0 00004 00014 00015 00005 00012 00011 00005 00012
...
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.
linux-7.2.3/Documentation/iio/adxl380.rst
+233
View File
@@ -0,0 +1,233 @@
.. SPDX-License-Identifier: GPL-2.0
===============
ADXL380 driver
===============
This driver supports Analog Device's ADXL380/382 on SPI/I2C bus.
1. Supported devices
====================
* `ADXL380 <https://www.analog.com/ADXL380>`_
* `ADXL382 <https://www.analog.com/ADXL382>`_
The ADXL380/ADXL382 is a low noise density, low power, 3-axis accelerometer with
selectable measurement ranges. The ADXL380 supports the ±4 g, ±8 g, and ±16 g
ranges, and the ADXL382 supports ±15 g, ±30 g, and ±60 g ranges.
2. Device attributes
====================
Accelerometer measurements are always provided.
Temperature data are also provided. This data can be used to monitor the
internal system temperature or to improve the temperature stability of the
device via calibration.
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 adxl380 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_high_pass_3db_frequency | Low pass filter bandwidth. |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_filter_high_pass_3db_frequency_available | Available low pass filter bandwidth configurations. |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_filter_low_pass_3db_frequency | High pass filter bandwidth. |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_filter_low_pass_3db_frequency_available | Available high pass filter bandwidth configurations. |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_x_calibbias | Calibration offset 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_raw | Raw Y-axis accelerometer channel value. |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_z_calibbias | Calibration offset for the Z-axis accelerometer channel. |
+---------------------------------------------------+----------------------------------------------------------+
| in_accel_z_raw | Raw Z-axis accelerometer channel value. |
+---------------------------------------------------+----------------------------------------------------------+
+----------------------------------+--------------------------------------------+
| Temperature sensor related files | Description |
+----------------------------------+--------------------------------------------+
| in_temp_raw | Raw temperature channel value. |
+----------------------------------+--------------------------------------------+
| in_temp_offset | Offset for the temperature sensor channel. |
+----------------------------------+--------------------------------------------+
| in_temp_scale | Scale for the temperature sensor channel. |
+----------------------------------+--------------------------------------------+
+------------------------------+----------------------------------------------+
| Miscellaneous device files | Description |
+------------------------------+----------------------------------------------+
| name | Name of the IIO device. |
+------------------------------+----------------------------------------------+
| sampling_frequency | Currently selected sample rate. |
+------------------------------+----------------------------------------------+
| sampling_frequency_available | Available sampling frequency configurations. |
+------------------------------+----------------------------------------------+
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 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:
+-------------------------------------+---------------------------+
| Channel type | Measurement unit |
+-------------------------------------+---------------------------+
| Acceleration on X, Y, and Z axis | Meters per Second squared |
+-------------------------------------+---------------------------+
| Temperature | Millidegrees Celsius |
+-------------------------------------+---------------------------+
Usage examples
--------------
Show device name:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> cat name
adxl382
Show accelerometer channels value:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_raw
-1771
root:/sys/bus/iio/devices/iio:device0> cat in_accel_y_raw
282
root:/sys/bus/iio/devices/iio:device0> cat in_accel_z_raw
-1523
root:/sys/bus/iio/devices/iio:device0> cat in_accel_scale
0.004903325
- X-axis acceleration = in_accel_x_raw * in_accel_scale = −8.683788575 m/s^2
- Y-axis acceleration = in_accel_y_raw * in_accel_scale = 1.38273765 m/s^2
- Z-axis acceleration = in_accel_z_raw * in_accel_scale = -7.467763975 m/s^2
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 50 > in_accel_x_calibbias
root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias
50
Set sampling frequency:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> cat sampling_frequency
16000
root:/sys/bus/iio/devices/iio:device0> cat sampling_frequency_available
16000 32000 64000
root:/sys/bus/iio/devices/iio:device0> echo 32000 > sampling_frequency
root:/sys/bus/iio/devices/iio:device0> cat sampling_frequency
32000
Set low pass filter bandwidth for accelerometer channels:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> cat in_accel_filter_low_pass_3db_frequency
32000
root:/sys/bus/iio/devices/iio:device0> cat in_accel_filter_low_pass_3db_frequency_available
32000 8000 4000 2000
root:/sys/bus/iio/devices/iio:device0> echo 2000 > in_accel_filter_low_pass_3db_frequency
root:/sys/bus/iio/devices/iio:device0> cat in_accel_filter_low_pass_3db_frequency
2000
3. Device buffers
=================
This driver supports IIO buffers.
All devices support retrieving the raw acceleration and temperature measurements
using buffers.
Usage examples
--------------
Select channels for buffer read:
.. code-block:: bash
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_accel_x_en
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_accel_y_en
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_accel_z_en
root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_temp_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
...
002bc300 f7 e7 00 a8 fb c5 24 80 f7 e7 01 04 fb d6 24 80 |......$.......$.|
002bc310 f7 f9 00 ab fb dc 24 80 f7 c3 00 b8 fb e2 24 80 |......$.......$.|
002bc320 f7 fb 00 bb fb d1 24 80 f7 b1 00 5f fb d1 24 80 |......$...._..$.|
002bc330 f7 c4 00 c6 fb a6 24 80 f7 a6 00 68 fb f1 24 80 |......$....h..$.|
002bc340 f7 b8 00 a3 fb e7 24 80 f7 9a 00 b1 fb af 24 80 |......$.......$.|
002bc350 f7 b1 00 67 fb ee 24 80 f7 96 00 be fb 92 24 80 |...g..$.......$.|
002bc360 f7 ab 00 7a fc 1b 24 80 f7 b6 00 ae fb 76 24 80 |...z..$......v$.|
002bc370 f7 ce 00 a3 fc 02 24 80 f7 c0 00 be fb 8b 24 80 |......$.......$.|
002bc380 f7 c3 00 93 fb d0 24 80 f7 ce 00 d8 fb c8 24 80 |......$.......$.|
002bc390 f7 bd 00 c0 fb 82 24 80 f8 00 00 e8 fb db 24 80 |......$.......$.|
002bc3a0 f7 d8 00 d3 fb b4 24 80 f8 0b 00 e5 fb c3 24 80 |......$.......$.|
002bc3b0 f7 eb 00 c8 fb 92 24 80 f7 e7 00 ea fb cb 24 80 |......$.......$.|
002bc3c0 f7 fd 00 cb fb 94 24 80 f7 e3 00 f2 fb b8 24 80 |......$.......$.|
...
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.
linux-7.2.3/Documentation/iio/bno055.rst
+51
View File
@@ -0,0 +1,51 @@
.. SPDX-License-Identifier: GPL-2.0
==============================
BNO055 driver
==============================
1. Overview
===========
This driver supports Bosch BNO055 IMUs (on both serial and I2C busses).
Accelerometer, magnetometer and gyroscope measurements are always available.
When "fusion_enable" sysfs attribute is set to 1, orientation (both Euler
angles and quaternion), linear velocity and gravity vector are also
provided, but some sensor settings (e.g. low pass filtering and range)
become locked (the IMU firmware controls them).
This driver supports also IIO buffers.
2. Calibration
==============
The IMU continuously performs an autocalibration procedure if (and only if)
operating in fusion mode. The magnetometer autocalibration can however be
disabled by writing 0 in the sysfs in_magn_calibration_fast_enable attribute.
The driver provides access to autocalibration flags (i.e. you can determine
if the IMU has successfully autocalibrated) and to the calibration data blob.
The user can save this blob in a firmware file (i.e. in /lib/firmware) that
the driver looks for at probe time. If found, then the IMU is initialized
with this calibration data. This saves the user from performing the
calibration procedure every time (which consists of moving the IMU in
various ways).
The driver looks for calibration data file using two different names: first
a file whose name is suffixed with the IMU unique ID (exposed in sysfs as
serial_number) is searched for; this is useful when there is more than one
IMU instance. If this file is not found, then a "generic" calibration file
is searched for (which can be used when only one IMU is present, without
struggling with fancy names, that change on each device).
Valid calibration file names would be e.g.
bno055-caldata-0e7c26a33541515120204a35342b04ff.dat
bno055-caldata.dat
In non-fusion mode the IIO 'offset' attributes provide access to the
offsets from calibration data (if any), so that the user can apply them to
the accel, angvel and magn IIO attributes. In fusion mode they are not
needed (the IMU firmware internally applies those corrections) and they
read as zero.
linux-7.2.3/Documentation/iio/ep93xx_adc.rst
+40
View File
@@ -0,0 +1,40 @@
==============================
Cirrus Logic EP93xx ADC driver
==============================
1. Overview
===========
The driver is intended to work on both low-end (EP9301, EP9302) devices with
5-channel ADC and high-end (EP9307, EP9312, EP9315) devices with 10-channel
touchscreen/ADC module.
2. Channel numbering
====================
Numbering scheme for channels 0..4 is defined in EP9301 and EP9302 datasheets.
EP9307, EP9312 and EP9315 have 3 channels more (total 8), but the numbering is
not defined. So the last three are numbered randomly, let's say.
Assuming ep93xx_adc is IIO device0, you'd find the following entries under
/sys/bus/iio/devices/iio:device0/:
+-----------------+---------------+
| sysfs entry | ball/pin name |
+=================+===============+
| in_voltage0_raw | YM |
+-----------------+---------------+
| in_voltage1_raw | SXP |
+-----------------+---------------+
| in_voltage2_raw | SXM |
+-----------------+---------------+
| in_voltage3_raw | SYP |
+-----------------+---------------+
| in_voltage4_raw | SYM |
+-----------------+---------------+
| in_voltage5_raw | XP |
+-----------------+---------------+
| in_voltage6_raw | XM |
+-----------------+---------------+
| in_voltage7_raw | YP |
+-----------------+---------------+
linux-7.2.3/Documentation/iio/iio_adc.rst
+305
View File
@@ -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>;
};
};
linux-7.2.3/Documentation/iio/iio_configfs.rst
+102
View File
@@ -0,0 +1,102 @@
===============================
Industrial IIO configfs support
===============================
1. Overview
===========
Configfs is a filesystem-based manager of kernel objects. IIO uses some
objects that could be easily configured using configfs (e.g.: devices,
triggers).
See Documentation/filesystems/configfs.rst for more information
about how configfs works.
2. Usage
========
In order to use configfs support in IIO we need to select it at compile
time via CONFIG_IIO_CONFIGFS config option.
Then, mount the configfs filesystem (usually under /config directory)::
$ mkdir /config
$ mount -t configfs none /config
At this point, all default IIO groups will be created and can be accessed
under /config/iio. Next chapters will describe available IIO configuration
objects.
3. Software triggers
====================
One of the IIO default configfs groups is the "triggers" group. It is
automagically accessible when the configfs is mounted and can be found
under /config/iio/triggers.
IIO software triggers implementation offers support for creating multiple
trigger types. A new trigger type is usually implemented as a separate
kernel module following the interface in include/linux/iio/sw_trigger.h::
/*
* drivers/iio/trigger/iio-trig-sample.c
* sample kernel module implementing a new trigger type
*/
#include <linux/iio/sw_trigger.h>
static struct iio_sw_trigger *iio_trig_sample_probe(const char *name)
{
/*
* This allocates and registers an IIO trigger plus other
* trigger type specific initialization.
*/
}
static int iio_trig_sample_remove(struct iio_sw_trigger *swt)
{
/*
* This undoes the actions in iio_trig_sample_probe
*/
}
static const struct iio_sw_trigger_ops iio_trig_sample_ops = {
.probe = iio_trig_sample_probe,
.remove = iio_trig_sample_remove,
};
static struct iio_sw_trigger_type iio_trig_sample = {
.name = "trig-sample",
.owner = THIS_MODULE,
.ops = &iio_trig_sample_ops,
};
module_iio_sw_trigger_driver(iio_trig_sample);
Each trigger type has its own directory under /config/iio/triggers. Loading
iio-trig-sample module will create 'trig-sample' trigger type directory
/config/iio/triggers/trig-sample.
We support the following interrupt sources (trigger types):
* hrtimer, uses high resolution timers as interrupt source
3.1 Hrtimer triggers creation and destruction
---------------------------------------------
Loading iio-trig-hrtimer module will register hrtimer trigger types allowing
users to create hrtimer triggers under /config/iio/triggers/hrtimer.
e.g::
$ mkdir /config/iio/triggers/hrtimer/instance1
$ rmdir /config/iio/triggers/hrtimer/instance1
Each trigger can have one or more attributes specific to the trigger type.
3.2 "hrtimer" trigger types attributes
--------------------------------------
"hrtimer" trigger type doesn't have any configurable attribute from /config dir.
It does introduce the sampling_frequency attribute to trigger directory.
That attribute sets the polling frequency in Hz, with mHz precision.
linux-7.2.3/Documentation/iio/iio_devbuf.rst
+153
View File
@@ -0,0 +1,153 @@
.. SPDX-License-Identifier: GPL-2.0
=============================
Industrial IIO device buffers
=============================
1. Overview
===========
The Industrial I/O core offers a way for continuous data capture based on a
trigger source. Multiple data channels can be read at once from
``/dev/iio:deviceX`` character device node, thus reducing the CPU load.
Devices with buffer support feature an additional sub-directory in the
``/sys/bus/iio/devices/iio:deviceX/`` directory hierarchy, called bufferY, where
Y defaults to 0, for devices with a single buffer.
2. Buffer attributes
====================
An IIO buffer has an associated attributes directory under
``/sys/bus/iio/iio:deviceX/bufferY/``. The attributes are described below.
``length``
----------
Read / Write attribute which states the total number of data samples (capacity)
that can be stored by the buffer.
``enable``
----------
Read / Write attribute which starts / stops the buffer capture. This file should
be written last, after length and selection of scan elements. Writing a non-zero
value may result in an error, such as EINVAL, if, for example, an unsupported
combination of channels is given.
``watermark``
-------------
Read / Write positive integer attribute specifying the maximum number of scan
elements to wait for.
Poll will block until the watermark is reached.
Blocking read will wait until the minimum between the requested read amount or
the low watermark is available.
Non-blocking read will retrieve the available samples from the buffer even if
there are less samples than the watermark level. This allows the application to
block on poll with a timeout and read the available samples after the timeout
expires and thus have a maximum delay guarantee.
Data available
--------------
Read-only attribute indicating the bytes of data available in the buffer. In the
case of an output buffer, this indicates the amount of empty space available to
write data to. In the case of an input buffer, this indicates the amount of data
available for reading.
Scan elements
-------------
The meta information associated with a channel data placed in a buffer is called
a scan element. The scan elements attributes are presented below.
**_en**
Read / Write attribute used for enabling a channel. If and only if its value
is non-zero, then a triggered capture will contain data samples for this
channel.
**_index**
Read-only unsigned integer attribute specifying the position of the channel in
the buffer. Note these are not dependent on what is enabled and may not be
contiguous. Thus for userspace to establish the full layout these must be used
in conjunction with all _en attributes to establish which channels are present,
and the relevant _type attributes to establish the data storage format.
**_type**
Read-only attribute containing the description of the scan element data storage
within the buffer and hence the form in which it is read from userspace. Format
is [be|le]:[f|s|u]bits/storagebits[Xrepeat][>>shift], where:
- **be** or **le** specifies big or little-endian.
- **f** specifies if floating-point.
- **s** or **u** specifies if signed (2's complement) or unsigned.
- **bits** is the number of valid data bits.
- **storagebits** is the number of bits (after padding) that it occupies in the
buffer.
- **repeat** specifies the number of bits/storagebits repetitions. When the
repeat element is 0 or 1, then the repeat value is omitted.
- **shift** if specified, is the shift that needs to be applied prior to
masking out unused bits.
For example, a driver for a 3-axis accelerometer with 12-bit resolution where
data is stored in two 8-bit registers is as follows::
7 6 5 4 3 2 1 0
+---+---+---+---+---+---+---+---+
|D3 |D2 |D1 |D0 | X | X | X | X | (LOW byte, address 0x06)
+---+---+---+---+---+---+---+---+
7 6 5 4 3 2 1 0
+---+---+---+---+---+---+---+---+
|D11|D10|D9 |D8 |D7 |D6 |D5 |D4 | (HIGH byte, address 0x07)
+---+---+---+---+---+---+---+---+
will have the following scan element type for each axis:
.. code-block:: bash
$ cat /sys/bus/iio/devices/iio:device0/buffer0/in_accel_y_type
le:s12/16>>4
A userspace application will interpret data samples read from the buffer as
two-byte little-endian signed data, that needs a 4 bits right shift before
masking out the 12 valid bits of data.
It is also worth mentioning that the data in the buffer will be naturally
aligned, so the userspace application has to handle the buffers accordingly.
Take for example, a driver with four channels with the following description:
- channel0: index: 0, type: be:u16/16>>0
- channel1: index: 1, type: be:u32/32>>0
- channel2: index: 2, type: be:u32/32>>0
- channel3: index: 3, type: be:u64/64>>0
If all channels are enabled, the data will be aligned in the buffer as follows::
0-1 2 3 4-7 8-11 12 13 14 15 16-23 -> buffer byte number
+-----+---+---+-----+-----+---+---+---+---+-----+
|CHN_0|PAD|PAD|CHN_1|CHN_2|PAD|PAD|PAD|PAD|CHN_3| -> buffer content
+-----+---+---+-----+-----+---+---+---+---+-----+
If only channel0 and channel3 are enabled, the data will be aligned in the
buffer as follows::
0-1 2 3 4 5 6 7 8-15 -> buffer byte number
+-----+---+---+---+---+---+---+-----+
|CHN_0|PAD|PAD|PAD|PAD|PAD|PAD|CHN_3| -> buffer content
+-----+---+---+---+---+---+---+-----+
Typically the buffered data is found in raw format (unscaled with no offset
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
description of the attributes.
linux-7.2.3/Documentation/iio/iio_dmabuf_api.rst
+54
View File
@@ -0,0 +1,54 @@
.. SPDX-License-Identifier: GPL-2.0
===================================
High-speed DMABUF interface for IIO
===================================
1. Overview
===========
The Industrial I/O subsystem supports access to buffers through a
file-based interface, with read() and write() access calls through the
IIO device's dev node.
It additionally supports a DMABUF based interface, where the userspace
can attach DMABUF objects (externally created) to an IIO buffer, and
subsequently use them for data transfers.
A userspace application can then use this interface to share DMABUF
objects between several interfaces, allowing it to transfer data in a
zero-copy fashion, for instance between IIO and the USB stack.
The userspace application can also memory-map the DMABUF objects, and
access the sample data directly. The advantage of doing this vs. the
read() interface is that it avoids an extra copy of the data between the
kernel and userspace. This is particularly useful for high-speed devices
which produce several megabytes or even gigabytes of data per second.
It does however increase the userspace-kernelspace synchronization
overhead, as the DMA_BUF_SYNC_START and DMA_BUF_SYNC_END IOCTLs have to
be used for data integrity.
2. User API
===========
As part of this interface, three new IOCTLs have been added. These three
IOCTLs have to be performed on the IIO buffer's file descriptor, which
can be obtained using the IIO_BUFFER_GET_FD_IOCTL() ioctl.
``IIO_BUFFER_DMABUF_ATTACH_IOCTL(int fd)``
Attach the DMABUF object, identified by its file descriptor, to the
IIO buffer. Returns zero on success, and a negative errno value on
error.
``IIO_BUFFER_DMABUF_DETACH_IOCTL(int fd)``
Detach the given DMABUF object, identified by its file descriptor,
from the IIO buffer. Returns zero on success, and a negative errno
value on error.
Note that closing the IIO buffer's file descriptor will
automatically detach all previously attached DMABUF objects.
``IIO_BUFFER_DMABUF_ENQUEUE_IOCTL(struct iio_dmabuf *iio_dmabuf)``
Enqueue a previously attached DMABUF object to the buffer queue.
Enqueued DMABUFs will be read from (if output buffer) or written to
(if input buffer) as long as the buffer is enabled.
linux-7.2.3/Documentation/iio/iio_tools.rst
+27
View File
@@ -0,0 +1,27 @@
.. SPDX-License-Identifier: GPL-2.0
=====================
IIO Interfacing Tools
=====================
1. Linux Kernel Tools
=====================
Linux Kernel provides some userspace tools that can be used to retrieve data
from IIO sysfs:
* lsiio: example application that provides a list of IIO devices and triggers
* iio_event_monitor: example application that reads events from an IIO device
and prints them
* iio_generic_buffer: example application that reads data from buffer
* iio_utils: set of APIs, typically used to access sysfs files.
2. LibIIO
=========
LibIIO is a C/C++ library that provides generic access to IIO devices. The
library abstracts the low-level details of the hardware, and provides a simple
yet complete programming interface that can be used for advanced projects.
For more information about LibIIO, please see:
https://github.com/analogdevicesinc/libiio
linux-7.2.3/Documentation/iio/index.rst
+42
View File
@@ -0,0 +1,42 @@
.. SPDX-License-Identifier: GPL-2.0
==============
Industrial I/O
==============
.. toctree::
:maxdepth: 1
iio_adc
iio_configfs
iio_devbuf
iio_dmabuf_api
iio_tools
Industrial I/O Kernel Drivers
=============================
.. toctree::
:maxdepth: 1
ad3552r
ad4000
ad4030
ad4062
ad4691
ad4695
ad7191
ad7380
ad7606
ad7625
ad7944
ade9000
adis16475
adis16480
adis16550
adxl313
adxl380
adxl345
bno055
ep93xx_adc
opt4060
linux-7.2.3/Documentation/iio/opt4060.rst
+61
View File
@@ -0,0 +1,61 @@
==============================
OPT4060 driver
==============================
1. Overview
=============================
This driver supports the Texas Instrument RGBW high resolution color sensor over
I2C.
https://www.ti.com/lit/gpn/opt4060
The driver supports:
- Raw values for red, green, blue and clear.
- Illuminance values.
- Scaled color values for red, green and blue.
- IIO events for thresholds.
- IIO triggered buffer using both its own data ready trigger and triggers from
other drivers.
2. Illuminance calculation
=============================
Illuminance is calculated using the wide spectrum green channel.
lux = GREEN_RAW x 2.15e-3
The value is accessed from:
/sys/bus/iio/devices/iio:deviceX/in_illuminance_input
See section 8.4.5.2 in the data sheet for additional details.
3. Color scale values
=============================
The sensor has different sensitivity for the different color components and
compensating factors are exposed from the driver.
The values are accessed from:
/sys/bus/iio/devices/iio:deviceX/in_intensity_red_scale
/sys/bus/iio/devices/iio:deviceX/in_intensity_green_scale
/sys/bus/iio/devices/iio:deviceX/in_intensity_blue_scale
A userspace application can multiply the raw values with the scale values so
that for a particular test light source, typically white, the measurement
intensity is the same across the different color channels. This is calculated
in the following way:
R = RED_RAW x SCALE_RED(2.4)
G = GREEN_RAW x SCALE_GREEN(1.0)
B = BLUE_RAW x SCALE_BLUE(1.3)
The data sheet suggests using the scaled values to normalize the scaled R, G
and B values. This is useful to get a value for the ratio between colors
independent of light intensity. A userspace application can do this in the
following way:
R_NORMALIZED = R / (R + G + B)
G_NORMALIZED = G / (R + G + B)
B_NORMALIZED = B / (R + G + B)
See section 8.4.5.2 in the data sheet for additional details.