ad7944.rst

  1.. SPDX-License-Identifier: GPL-2.0-only
  2
  3=============
  4AD7944 driver
  5=============
  6
  7ADC driver for Analog Devices Inc. AD7944 and similar devices. The module name
  8is ``ad7944``.
  9
 10
 11Supported devices
 12=================
 13
 14The following chips are supported by this driver:
 15
 16* `AD7944 <https://www.analog.com/AD7944>`_
 17* `AD7985 <https://www.analog.com/AD7985>`_
 18* `AD7986 <https://www.analog.com/AD7986>`_
 19
 20
 21Supported features
 22==================
 23
 24SPI wiring modes
 25----------------
 26
 27The driver currently supports three of the many possible SPI wiring configurations.
 28
 29CS mode, 3-wire, without busy indicator
 30^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 31
 32.. code-block::
 33
 34                                         +-------------+
 35                    +--------------------| CS          |
 36                    v                    |             |
 37    VIO   +--------------------+         |     HOST    |
 38     |    |        CNV         |         |             |
 39     +--->| SDI   AD7944   SDO |-------->| SDI         |
 40          |        SCK         |         |             |
 41          +--------------------+         |             |
 42                    ^                    |             |
 43                    +--------------------| SCLK        |
 44                                         +-------------+
 45
 46To select this mode in the device tree, set the ``adi,spi-mode`` property to
 47``"single"`` and omit the ``cnv-gpios`` property.
 48
 49This is the only wiring configuration supported when using `SPI offload support`_.
 50
 51CS mode, 4-wire, without busy indicator
 52^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 53
 54.. code-block::
 55
 56                                         +-------------+
 57     +-----------------------------------| CS          |
 58     |                                   |             |
 59     |              +--------------------| GPIO        |
 60     |              v                    |             |
 61     |    +--------------------+         |     HOST    |
 62     |    |        CNV         |         |             |
 63     +--->| SDI   AD7944   SDO |-------->| SDI         |
 64          |        SCK         |         |             |
 65          +--------------------+         |             |
 66                    ^                    |             |
 67                    +--------------------| SCLK        |
 68                                         +-------------+
 69
 70To select this mode in the device tree, omit the ``adi,spi-mode`` property and
 71provide the ``cnv-gpios`` property.
 72
 73Chain mode, without busy indicator
 74^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 75
 76.. code-block::
 77
 78                                                                 +-------------+
 79                  +-------------------------+--------------------| CS          |
 80                  v                         v                    |             |
 81        +--------------------+    +--------------------+         |     HOST    |
 82        |        CNV         |    |        CNV         |         |             |
 83   +--->| SDI   AD7944   SDO |--->| SDI   AD7944   SDO |-------->| SDI         |
 84   |    |        SCK         |    |        SCK         |         |             |
 85  GND   +--------------------+    +--------------------+         |             |
 86                  ^                         ^                    |             |
 87                  +-------------------------+--------------------| SCLK        |
 88                                                                 +-------------+
 89
 90To select this mode in the device tree, set the ``adi,spi-mode`` property to
 91``"chain"``, add the ``spi-cs-high`` flag, add the ``#daisy-chained-devices``
 92property, and omit the ``cnv-gpios`` property.
 93
 94Reference voltage
 95-----------------
 96
 97All 3 possible reference voltage sources are supported:
 98
 99- Internal reference
100- External 1.2V reference and internal buffer
101- External reference
102
103The source is determined by the device tree. If ``ref-supply`` is present, then
104the external reference is used. If ``refin-supply`` is present, then the internal
105buffer is used. If neither is present, then the internal reference is used.
106
107Unimplemented features
108----------------------
109
110- ``BUSY`` indication
111
112
113Device attributes
114=================
115
116There are two types of ADCs in this family, pseudo-differential and fully
117differential. The channel name is different depending on the type of ADC.
118
119Pseudo-differential ADCs
120------------------------
121
122AD7944 and AD7985 are pseudo-differential ADCs and have the following attributes:
123
124+---------------------------------------+--------------------------------------------------------------+
125| Attribute                             | Description                                                  |
126+=======================================+==============================================================+
127| ``in_voltage0_raw``                   | Raw ADC voltage value (*IN+* referenced to ground sense).    |
128+---------------------------------------+--------------------------------------------------------------+
129| ``in_voltage0_scale``                 | Scale factor to convert raw value to mV.                     |
130+---------------------------------------+--------------------------------------------------------------+
131
132In "chain" mode, additional chips will appear as additional voltage input
133channels, e.g. ``in_voltage1_raw``.
134
135Fully-differential ADCs
136-----------------------
137
138AD7986 is a fully-differential ADC and has the following attributes:
139
140+---------------------------------------+--------------------------------------------------------------+
141| Attribute                             | Description                                                  |
142+=======================================+==============================================================+
143| ``in_voltage0-voltage1_raw``          | Raw ADC voltage value (*IN+* - *IN-*).                       |
144+---------------------------------------+--------------------------------------------------------------+
145| ``in_voltage0-voltage1_scale``        | Scale factor to convert raw value to mV.                     |
146+---------------------------------------+--------------------------------------------------------------+
147
148In "chain" mode, additional chips will appear as additional voltage input
149channels, e.g. ``in_voltage2-voltage3_raw``.
150
151SPI offload support
152===================
153
154To be able to achieve the maximum sample rate, the driver can be used with the
155`AXI SPI Engine`_ to provide SPI offload support.
156
157.. _AXI SPI Engine: http://analogdevicesinc.github.io/hdl/projects/pulsar_adc/index.html
158
159When SPI offload is being used, some attributes will be different.
160
161* ``trigger`` directory is removed.
162* ``in_voltage0_sampling_frequency`` attribute is added for setting the sample
163  rate.
164* ``in_voltage0_sampling_frequency_available`` attribute is added for querying
165  the max sample rate.
166* ``timestamp`` channel is removed.
167* Buffer data format may be different compared to when offload is not used,
168  e.g. the ``in_voltage0_type`` attribute.
169
170If the ``turbo-gpios`` property is present in the device tree, the driver will
171turn on TURBO during buffered reads and turn it off otherwise.
172
173Device buffers
174==============
175
176This driver supports IIO triggered buffers.
177
178See :doc:`iio_devbuf` for more information.