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