1.. SPDX-License-Identifier: GPL-2.0-only
2
3=============
4AD7606 driver
5=============
6
7ADC driver for Analog Devices Inc. AD7606 and similar devices. The module name
8is ``ad7606``.
9
10Supported devices
11=================
12
13The following chips are supported by this driver:
14
15* `AD7605 <https://www.analog.com/en/products/ad7605.html>`_
16* `AD7606 <https://www.analog.com/en/products/ad7606.html>`_
17* `AD7606B <https://www.analog.com/en/products/ad7606b.html>`_
18* `AD7616 <https://www.analog.com/en/products/ad7616.html>`_
19
20Supported features
21==================
22
23SPI wiring modes
24----------------
25
26These ADCs can output data on several SDO lines (1/2/4/8). The driver
27currently supports only 1 SDO line.
28
29SPI offload wiring
30------------------
31When used with a SPI offload, the supported wiring configuration is:
32
33.. code-block::
34
35    +-------------+         +-------------+
36    |        BUSY |-------->| TRIGGER     |
37    |          CS |<--------| CS          |
38    |             |         |             |
39    |     ADC     |         |     SPI     |
40    |             |         |             |
41    |         SDI |<--------| SDO         |
42    |       DOUTA |-------->| SDI         |
43    |        SCLK |<--------| SCLK        |
44    |             |         |             |
45    |             |         +-------------+
46    |      CONVST |<--------| PWM         |
47    +-------------+         +-------------+
48
49In this case, the ``pwms`` property is required.
50The ``#trigger-source-cells = <1>`` property is also required to connect back
51to the SPI offload. The SPI offload will have ``trigger-sources`` property
52with a cell to indicate the busy signal:
53``<&ad7606 AD4695_TRIGGER_EVENT_BUSY>``.
54
55.. seealso:: `SPI offload support`_
56
57
58Parallel wiring mode
59--------------------
60
61There is also a parallel interface, with 16 lines (that can be reduced to 8 in
62byte mode). The parallel interface is selected by declaring the device as
63platform in the device tree (with no io-backends node defined, see below).
64
65IIO-backend mode
66----------------
67
68This mode allows to reach the best sample rates, but it requires an external
69hardware (eg HDL or APU) to handle the low level communication.
70The backend mode is enabled when through the definition of the "io-backends"
71property in the device tree.
72
73The reference configuration for the current implementation of IIO-backend mode
74is the HDL reference provided by ADI:
75https://wiki.analog.com/resources/eval/user-guides/ad7606x-fmc/hdl
76
77This implementation embeds an IIO-backend compatible IP (adi-axi-adc) and a PWM
78connected to the conversion trigger pin.
79
80.. code-block::
81
82    +---+                                       +----------------------------
83    |   |               +-------+               |AD76xx
84    | A |  controls     |       |               |
85    | D |-------------->|  PWM  |-------------->| cnvst
86    | 7 |               |       |               |
87    | 6 |               +-------+               |
88    | 0 | controls  +-----------+-----------+   |
89    | 6 |---------->|           |           |<--| frstdata
90    |   |           | Backend   |  Backend  |<--| busy
91    | D |           | Driver    |           |   |
92    | R |           |           |           |-->| clk
93    | I |  requests |+---------+| DMA       |   |
94    | V |----------->|  Buffer ||<----      |<=>| DATA
95    | E |           |+---------+|           |   |
96    | R |           +-----------+-----------+   |
97    |   |-------------------------------------->| reset/configuration gpios
98    +---+                                       +-----------------------------
99
100
101Software and hardware modes
102---------------------------
103
104While all the AD7606/AD7616 series parts can be configured using GPIOs, some of
105them can be configured using register.
106
107The chips that support software mode have more values available for configuring
108the device, as well as more settings, and allow to control the range and
109calibration per channel.
110
111The following settings are available per channel in software mode:
112 - Scale
113
114Also, there is a broader choice of oversampling ratios in software mode.
115
116Conversion triggering
117---------------------
118
119The conversion can be triggered by two distinct ways:
120
121 - A GPIO is connected to the conversion trigger pin, and this GPIO is controlled
122   by the driver directly.  In this configuration, the driver sets back the
123   conversion trigger pin to high as soon as it has read all the conversions.
124
125 - An external source is connected to the conversion trigger pin. In the
126   current implementation, it must be a PWM. In this configuration, the driver
127   does not control directly the conversion trigger pin. Instead, it can
128   control the PWM's frequency. This trigger is enabled only for iio-backend.
129
130Reference voltage
131-----------------
132
1332 possible reference voltage sources are supported:
134
135 - Internal reference (2.5V)
136 - External reference (2.5V)
137
138The source is determined by the device tree. If ``refin-supply`` is present,
139then the external reference is used, otherwise the internal reference is used.
140
141Oversampling
142------------
143
144This family supports oversampling to improve SNR.
145In software mode, the following ratios are available:
1461 (oversampling disabled)/2/4/8/16/32/64/128/256.
147
148Unimplemented features
149----------------------
150
151- 2/4/8 SDO lines
152- CRC indication
153- Calibration
154
155SPI offload support
156===================
157
158To be able to achieve the maximum sample rate, the driver can be used with the
159`AXI SPI Engine`_ to provide SPI offload support.
160
161.. _AXI SPI Engine: https://analogdevicesinc.github.io/hdl/library/spi_engine/index.html
162
163When SPI offload is being used, some attributes will be different.
164
165* ``trigger`` directory is removed.
166* ``sampling_frequency`` attribute is added for setting the sample rate.
167* ``timestamp`` channel is removed.
168* Buffer data format may be different compared to when offload is not used,
169  e.g. the ``in_voltage0_type`` attribute.
170
171Device buffers
172==============
173
174IIO triggered buffer
175--------------------
176
177This driver supports IIO triggered buffers, with a "built in" trigger, i.e the
178trigger is allocated and linked by the driver, and a new conversion is triggered
179as soon as the samples are transferred, and a timestamp channel is added to make
180up for the potential jitter induced by the delays in the interrupt handling.
181
182IIO backend buffer
183------------------
184
185When IIO backend is used, the trigger is not needed, and the sample rate is
186considered as stable. There is no timestamp channel. The communication is
187delegated to an external logic, called a backend, and the backend's driver
188handles the buffer. When this mode is enabled, the driver cannot control the
189conversion pin, because the busy pin is bound to the backend.
190