1.. SPDX-License-Identifier: GPL-2.0-only
2
3=============
4AD7380 driver
5=============
6
7ADC driver for Analog Devices Inc. AD7380 and similar devices. The module name
8is ``ad7380``.
9
10
11Supported devices
12=================
13
14The following chips are supported by this driver:
15
16* `AD7380 <https://www.analog.com/en/products/ad7380.html>`_
17* `AD7381 <https://www.analog.com/en/products/ad7381.html>`_
18* `AD7383 <https://www.analog.com/en/products/ad7383.html>`_
19* `AD7384 <https://www.analog.com/en/products/ad7384.html>`_
20* `AD7386 <https://www.analog.com/en/products/ad7386.html>`_
21* `AD7387 <https://www.analog.com/en/products/ad7387.html>`_
22* `AD7388 <https://www.analog.com/en/products/ad7388.html>`_
23* `AD7380-4 <https://www.analog.com/en/products/ad7380-4.html>`_
24* `AD7381-4 <https://www.analog.com/en/products/ad7381-4.html>`_
25* `AD7383-4 <https://www.analog.com/en/products/ad7383-4.html>`_
26* `AD7384-4 <https://www.analog.com/en/products/ad7384-4.html>`_
27* `AD7386-4 <https://www.analog.com/en/products/ad7386-4.html>`_
28* `AD7387-4 <https://www.analog.com/en/products/ad7387-4.html>`_
29* `AD7388-4 <https://www.analog.com/en/products/ad7388-4.html>`_
30* `AD7389-4 <https://www.analog.com/en/products/ad7389-4.html>`_
31* `ADAQ4370-4 <https://www.analog.com/en/products/adaq4370-4.html>`_
32* `ADAQ4380-4 <https://www.analog.com/en/products/adaq4380-4.html>`_
33* `ADAQ4381-4 <https://www.analog.com/en/products/adaq4381-4.html>`_
34
35
36Supported features
37==================
38
39SPI wiring modes
40----------------
41
42ad738x ADCs can output data on several SDO lines (1/2/4). The driver currently
43supports only 1 SDO line.
44
45Reference voltage
46-----------------
47
48ad7380-4
49~~~~~~~~
50
51ad7380-4 supports only an external reference voltage (2.5V to 3.3V). It must be
52declared in the device tree as ``refin-supply``.
53
54ad7389-4
55~~~~~~~~
56
57ad7389-4 supports only an internal reference voltage. ``refin-supply`` and
58``refio-supply`` properties are both omitted in this case.
59
60ADAQ devices
61~~~~~~~~~~~~
62
63ADAQ devices don't have an external reference, but use a 3.3V internal reference
64derived from one of its supplies (``refin-supply``)
65
66All other devices from ad738x family
67~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
68
69All other devices from ad738x support 2 possible reference voltage sources:
70
71- Internal reference (2.5V)
72- External reference (2.5V to 3.3V)
73
74The source is determined by the device tree. If ``refio-supply`` is present,
75then it is used as external reference, else the internal reference is used.
76
77Oversampling and resolution boost
78---------------------------------
79
80This family supports 2 types of oversampling: normal average and rolling
81average. Only normal average is supported by the driver, as rolling average can
82be achieved by processing a captured data buffer. The following ratios are
83available: 1 (oversampling disabled)/2/4/8/16/32.
84
85When the on-chip oversampling function is enabled the performance of the ADC can
86exceed the default resolution. To accommodate the performance boost achievable,
87it is possible to enable an additional two bits of resolution. Because the
88resolution boost feature can only be enabled when oversampling is enabled and
89oversampling is not as useful without the resolution boost, the driver
90automatically enables the resolution boost if and only if oversampling is
91enabled.
92
93Since the resolution boost feature causes 16-bit chips to now have 18-bit data
94which means the storagebits has to change from 16 to 32 bits, we use the new
95ext_scan_type feature to allow changing the scan_type at runtime. Unfortunately
96libiio does not support it. So when enabling or disabling oversampling, user
97must restart iiod using the following command:
98
99.. code-block:: bash
100
101	root:~# systemctl restart iiod
102
103Alert
104-----
105
1062 channels variants of the ad738x family, can use the SDOB line as an alert pin
107when configured in 1 SDO line mode. 4 channels variants, can use SDOD as an
108alert pin when configured in 1 or 2 SDO line(s) mode, although only 1 SDO line
109mode is currently supported by the driver (see `SPI wiring modes`_).
110
111At the end of a conversion the active-low alert pin gets asserted if the
112conversion result exceeds the alert high limit or falls below the alert low
113limit. It is cleared, on a falling edge of CS. The alert pin is common to all
114channels.
115
116User can enable alert using the regular iio events attribute:
117
118.. code-block:: bash
119
120	events/thresh_either_en
121
122The high and low thresholds are common to all channels and can also be set using
123regular iio events attributes:
124
125.. code-block:: bash
126
127	events/in_thresh_falling_value
128	events/in_thresh_rising_value
129
130If debugfs is available, user can read the ALERT register to determine the
131faulty channel and direction.
132
133In most use cases, user will hardwire the alert pin to trigger a shutdown.
134
135Channel selection and sequencer (single-end chips only)
136-------------------------------------------------------
137
138Single-ended chips of this family (ad7386/7/8(-4)) have a 2:1 multiplexer in
139front of each ADC. They also include additional configuration registers that
140allow for either manual selection or automatic switching (sequencer mode), of
141the multiplexer inputs.
142
143From an IIO point of view, all inputs are exported, i.e ad7386/7/8
144export 4 channels and ad7386-4/7-4/8-4 export 8 channels.
145
146Inputs ``AinX0`` of multiplexers correspond to the first half of IIO channels (i.e
1470-1 or 0-3) and inputs ``AinX1`` correspond to second half (i.e 2-3 or 4-7).
148Example for AD7386/7/8 (2 channels parts):
149
150.. code-block::
151
152	   IIO   | AD7386/7/8
153	         |         +----------------------------
154	         |         |     _____        ______
155	         |         |    |     |      |      |
156	voltage0 | AinA0 --|--->|     |      |      |
157	         |         |    | mux |----->| ADCA |---
158	voltage2 | AinA1 --|--->|     |      |      |
159	         |         |    |_____|      |_____ |
160	         |         |     _____        ______
161	         |         |    |     |      |      |
162	voltage1 | AinB0 --|--->|     |      |      |
163	         |         |    | mux |----->| ADCB |---
164	voltage3 | AinB1 --|--->|     |      |      |
165	         |         |    |_____|      |______|
166	         |         |
167	         |         +----------------------------
168
169
170When enabling sequencer mode, the effective sampling rate is divided by two.
171
172Gain (ADAQ devices only)
173~~~~~~~~~~~~~~~~~~~~~~~~
174
175ADAQ devices have a pin selectable gain in front of each ADC. The appropriate
176gain is selectable from device tree using the ``adi,gain-milli`` property.
177Refer to the typical connection diagrams section of the datasheet for pin
178wiring.
179
180Unimplemented features
181----------------------
182
183- 2/4 SDO lines
184- Rolling average oversampling
185- Power down mode
186- CRC indication
187
188SPI offload support
189===================
190
191To be able to achieve the maximum sample rate, the driver can be used with the
192`AXI SPI Engine`_ to provide SPI offload support.
193
194.. _AXI SPI Engine: http://analogdevicesinc.github.io/hdl/projects/pulsar_adc/index.html
195
196When SPI offload is being used, some attributes will be different.
197
198* ``trigger`` directory is removed.
199* ``in_voltage0_sampling_frequency`` attribute is added for setting the sample
200  rate.
201* ``in_voltage0_sampling_frequency_available`` attribute is added for querying
202  the max sample rate.
203* ``timestamp`` channel is removed.
204* Buffer data format may be different compared to when offload is not used,
205  e.g. the ``in_voltage0_type`` attribute.
206
207Device buffers
208==============
209
210This driver supports IIO triggered buffers.
211
212See :doc:`iio_devbuf` for more information.
213