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.
179