1.. SPDX-License-Identifier: GPL-2.0-only
2
3=============
4AD4000 driver
5=============
6
7Device driver for Analog Devices Inc. AD4000 series of ADCs and similar devices.
8
9Supported devices
10=================
11
12* `AD4000 <https://www.analog.com/AD4000>`_
13* `AD4001 <https://www.analog.com/AD4001>`_
14* `AD4002 <https://www.analog.com/AD4002>`_
15* `AD4003 <https://www.analog.com/AD4003>`_
16* `AD4004 <https://www.analog.com/AD4004>`_
17* `AD4005 <https://www.analog.com/AD4005>`_
18* `AD4006 <https://www.analog.com/AD4006>`_
19* `AD4007 <https://www.analog.com/AD4007>`_
20* `AD4008 <https://www.analog.com/AD4008>`_
21* `AD4010 <https://www.analog.com/AD4010>`_
22* `AD4011 <https://www.analog.com/AD4011>`_
23* `AD4020 <https://www.analog.com/AD4020>`_
24* `AD4021 <https://www.analog.com/AD4021>`_
25* `AD4022 <https://www.analog.com/AD4022>`_
26* `ADAQ4001 <https://www.analog.com/ADAQ4001>`_
27* `ADAQ4003 <https://www.analog.com/ADAQ4003>`_
28* `AD7685 <https://www.analog.com/AD7685>`_
29* `AD7686 <https://www.analog.com/AD7686>`_
30* `AD7687 <https://www.analog.com/AD7687>`_
31* `AD7688 <https://www.analog.com/AD7688>`_
32* `AD7690 <https://www.analog.com/AD7690>`_
33* `AD7691 <https://www.analog.com/AD7691>`_
34* `AD7693 <https://www.analog.com/AD7693>`_
35* `AD7942 <https://www.analog.com/AD7942>`_
36* `AD7946 <https://www.analog.com/AD7946>`_
37* `AD7980 <https://www.analog.com/AD7980>`_
38* `AD7982 <https://www.analog.com/AD7982>`_
39* `AD7983 <https://www.analog.com/AD7983>`_
40* `AD7984 <https://www.analog.com/AD7984>`_
41* `AD7988-1 <https://www.analog.com/AD7988-1>`_
42* `AD7988-5 <https://www.analog.com/AD7988-5>`_
43
44Wiring connections
45------------------
46
47Devices of the AD4000 series can be connected to the SPI host controller in a
48few different modes.
49
50CS mode, 3-wire turbo mode
51^^^^^^^^^^^^^^^^^^^^^^^^^^
52
53Datasheet "3-wire" mode is what most resembles standard SPI connection which,
54for these devices, comprises of connecting the controller CS line to device CNV
55pin and other SPI lines as usual. This configuration is (misleadingly) called
56"CS Mode, 3-Wire Turbo Mode" connection in datasheets.
57NOTE: The datasheet definition of 3-wire mode for the AD4000 series is NOT the
58same of standard spi-3wire mode.
59This is the only connection mode that allows configuration register access but
60it requires the SPI controller to support the ``SPI_MOSI_IDLE_HIGH`` feature.
61
62Omit the ``adi,sdi-pin`` property in device tree to select this mode.
63
64::
65
66                                         +-------------+
67     + ----------------------------------| SDO         |
68     |                                   |             |
69     |               +-------------------| CS          |
70     |               v                   |             |
71     |    +--------------------+         |     HOST    |
72     |    |        CNV         |         |             |
73     +--->| SDI   AD4000   SDO |-------->| SDI         |
74          |        SCK         |         |             |
75          +--------------------+         |             |
76                    ^                    |             |
77                    +--------------------| SCLK        |
78                                         +-------------+
79
80CS mode, 3-wire, without busy indicator
81^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
82
83Another wiring configuration supported as "3-wire" mode has the SDI pin
84hard-wired to digital input/output interface supply (VIO). In this setup, the
85controller is not required to support ``SPI_MOSI_IDLE_HIGH`` but register access
86is not possible. This connection mode saves one wire and works with any SPI
87controller.
88
89Set the ``adi,sdi-pin`` device tree property to ``"high"`` to select this mode.
90
91::
92
93                                         +-------------+
94                    +--------------------| CS          |
95                    v                    |             |
96    VIO   +--------------------+         |     HOST    |
97     |    |        CNV         |         |             |
98     +--->| SDI   AD4000   SDO |-------->| SDI         |
99          |        SCK         |         |             |
100          +--------------------+         |             |
101                    ^                    |             |
102                    +--------------------| SCLK        |
103                                         +-------------+
104
105Alternatively, a GPIO may be connected to the device CNV pin. This is similar to
106the previous wiring configuration but saves the use of a CS line.
107
108::
109
110                                         +-------------+
111                    +--------------------| GPIO        |
112                    v                    |             |
113    VIO   +--------------------+         |     HOST    |
114     |    |        CNV         |         |             |
115     +--->| SDI   AD4000   SDO |-------->| SDI         |
116          |        SCK         |         |             |
117          +--------------------+         |             |
118                    ^                    |             |
119                    +--------------------| SCLK        |
120                                         +-------------+
121
122CS mode, 4-wire without busy indicator
123^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
124
125In datasheet "4-wire" mode, the controller CS line is connected to the ADC SDI
126pin and a GPIO is connected to the ADC CNV pin. This connection mode may better
127suit scenarios where multiple ADCs can share one CNV trigger.
128
129Set ``adi,sdi-pin`` to ``"cs"`` to select this mode.
130
131
132::
133
134                                         +-------------+
135     + ----------------------------------| CS          |
136     |                                   |             |
137     |               +-------------------| GPIO        |
138     |               v                   |             |
139     |    +--------------------+         |     HOST    |
140     |    |        CNV         |         |             |
141     +--->| SDI   AD4000   SDO |-------->| SDI         |
142          |        SCK         |         |             |
143          +--------------------+         |             |
144                    ^                    |             |
145                    +--------------------| SCLK        |
146                                         +-------------+
147
148IIO Device characteristics
149==========================
150
151The AD4000 series driver supports differential and pseudo-differential ADCs.
152
153The span compression feature available in AD4000 series devices can be
154enabled/disabled by changing the ``_scale_available`` attribute of the voltage
155channel. Note that span compression configuration requires writing to AD4000
156configuration register, which is only possible when the ADC is wired in 3-wire
157turbo mode, and the SPI controller is ``SPI_MOSI_IDLE_HIGH`` capable. If those
158conditions are not met, no ``_scale_available`` attribute is provided.
159
160Besides that, differential and pseudo-differential voltage channels present
161slightly different sysfs interfaces.
162
163Pseudo-differential ADCs
164------------------------
165
166Typical voltage channel attributes of a pseudo-differential AD4000 series device:
167
168+-------------------------------------------+------------------------------------------+
169| Voltage Channel Attributes                | Description                              |
170+===========================================+==========================================+
171| ``in_voltage0_raw``                       | Raw ADC output code.                     |
172+-------------------------------------------+------------------------------------------+
173| ``in_voltage0_offset``                    | Offset to convert raw value to mV.       |
174+-------------------------------------------+------------------------------------------+
175| ``in_voltage0_scale``                     | Scale factor to convert raw value to mV. |
176+-------------------------------------------+------------------------------------------+
177| ``in_voltage0_scale_available``           | Toggles input span compression           |
178+-------------------------------------------+------------------------------------------+
179
180Differential ADCs
181-----------------
182
183Typical voltage channel attributes of a differential AD4000 series device:
184
185+-------------------------------------------+------------------------------------------+
186| Voltage Channel Attributes                | Description                              |
187+===========================================+==========================================+
188| ``in_voltage0-voltage1_raw``              | Raw ADC output code.                     |
189+-------------------------------------------+------------------------------------------+
190| ``in_voltage0-voltage1_scale``            | Scale factor to convert raw value to mV. |
191+-------------------------------------------+------------------------------------------+
192| ``in_voltage0-voltage1_scale_available``  | Toggles input span compression           |
193+-------------------------------------------+------------------------------------------+
194
195SPI offload support
196-------------------
197
198To be able to achieve the maximum sample rate, the driver can be used with SPI
199offload engines such as the one usually present in `AXI SPI Engine`_, to provide
200SPI offload support.
201
202.. _AXI SPI Engine: http://analogdevicesinc.github.io/hdl/projects/pulsar_adc/index.html
203
204To keep up with SPI offloading transfer speeds, the ADC must be connected either
205in 3-wire turbo mode or in 3-wire without busy indicator mode and have SPI
206controller CS line connected to the CNV pin.
207
208When set for SPI offload support, the IIO device will provide different
209interfaces.
210
211* Either ``in_voltage0_sampling_frequency`` or
212  ``in_voltage0-voltage1_sampling_frequency`` file is provided to allow setting
213  the sample rate.
214* IIO trigger device is not provided (no ``trigger`` directory).
215* ``timestamp`` channel is not provided.
216
217Also, because the ADC output has a one sample latency (delay) when the device is
218wired in "3-wire" mode and only one transfer per sample is done when using SPI
219offloading, the first data sample in the buffer is not valid because it contains
220the output of an earlier conversion result.
221