1.. SPDX-License-Identifier: GPL-2.0-only
2
3=============
4AD4030 driver
5=============
6
7ADC driver for Analog Devices Inc. AD4030 and similar devices. The module name
8is ``ad4030``.
9
10
11Supported devices
12=================
13
14The following chips are supported by this driver:
15
16* `AD4030-24 <https://www.analog.com/AD4030-24>`_
17* `AD4032-24 <https://www.analog.com/AD4032-24>`_
18* `AD4630-16 <https://www.analog.com/AD4630-16>`_
19* `AD4630-24 <https://www.analog.com/AD4630-24>`_
20* `AD4632-16 <https://www.analog.com/AD4632-16>`_
21* `AD4632-24 <https://www.analog.com/AD4632-24>`_
22
23IIO channels
24============
25
26Each "hardware" channel as described in the datasheet is split in 2 IIO
27channels:
28
29- One channel for the differential data
30- One channel for the common byte.
31
32The possible IIO channels depending on the numbers of "hardware" channel are:
33
34+------------------------------------+------------------------------------+
35| 1 channel ADC                      | 2 channels ADC                     |
36+====================================+====================================+
37| - voltage0-voltage1 (differential) | - voltage0-voltage1 (differential) |
38| - voltage2 (common-mode)           | - voltage2-voltage3 (differential) |
39|                                    | - voltage4 (common-mode)           |
40|                                    | - voltage5 (common-mode)           |
41+------------------------------------+------------------------------------+
42
43Labels
44------
45
46For ease of use, the IIO channels provide a label. For a differential channel,
47the label is ``differentialN`` where ``N`` is the "hardware" channel id. For a
48common-mode channel, the label is ``common-modeN`` where ``N`` is the
49"hardware" channel id.
50
51The possible labels are:
52
53+-----------------+-----------------+
54| 1 channel ADC   | 2 channels ADC  |
55+=================+=================+
56| - differential0 | - differential0 |
57| - common-mode0  | - differential1 |
58|                 | - common-mode0  |
59|                 | - common-mode1  |
60+-----------------+-----------------+
61
62Supported features
63==================
64
65SPI wiring modes
66----------------
67
68The driver currently supports the following SPI wiring configurations:
69
70One lane mode
71^^^^^^^^^^^^^
72
73In this mode, each channel has its own SDO line to send the conversion results.
74At the moment this mode can only be used on AD4030 which has one channel so only
75one SDO line is used.
76
77.. code-block::
78
79    +-------------+         +-------------+
80    |     ADC     |         |     HOST    |
81    |             |         |             |
82    |         CNV |<--------| CNV         |
83    |          CS |<--------| CS          |
84    |         SDI |<--------| SDO         |
85    |        SDO0 |-------->| SDI         |
86    |        SCLK |<--------| SCLK        |
87    +-------------+         +-------------+
88
89Interleaved mode
90^^^^^^^^^^^^^^^^
91
92In this mode, both channels conversion results are bit interleaved one SDO line.
93As such the wiring is the same as `One lane mode`_.
94
95SPI Clock mode
96--------------
97
98Only the SPI clocking mode is supported.
99
100Output modes
101------------
102
103There are more exposed IIO channels than channels as describe in the devices
104datasheet. This is due to the `Differential data + common-mode`_ encoding
1052 types of information in one conversion result. As such a "device" channel
106provides 2 IIO channels, one for the differential data and one for the common
107byte.
108
109Differential data
110^^^^^^^^^^^^^^^^^
111
112This mode is selected when:
113
114- Only differential channels are enabled in a buffered read
115- Oversampling attribute is set to 1
116
117Differential data + common-mode
118^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
119
120This mode is selected when:
121
122- Differential and common-mode channels are enabled in a buffered read
123- Oversampling attribute is set to 1
124
125For the 24-bits chips, this mode is also available with 16-bits differential
126data but is not selectable yet.
127
128Averaged differential data
129^^^^^^^^^^^^^^^^^^^^^^^^^^
130
131This mode is selected when:
132
133- Only differential channels are selected enabled in a buffered read
134- Oversampling attribute is greater than 1
135
136Digital Gain and Offset
137-----------------------
138
139Each differential data channel has a 16-bits unsigned configurable hardware
140gain applied to it. By default it's equal to 1. Note that applying gain can
141cause numerical saturation.
142
143Each differential data channel has a signed configurable hardware offset.
144For the ADCs ending in ``-24``, the gain is encoded on 24-bits.
145Likewise, the ADCs ending in ``-16`` have a gain encoded on 16-bits. Note that
146applying an offset can cause numerical saturation.
147
148The final differential data returned by the ADC is computed by first applying
149the gain, then the offset.
150
151The gain is controlled by the ``calibscale`` IIO attribute while the offset is
152controlled by the ``calibbias`` attribute.
153
154Reference voltage
155-----------------
156
157The chip supports an external reference voltage via the ``REF`` input or an
158internal buffered reference voltage via the ``REFIN`` input. The driver looks
159at the device tree to determine which is being used. If ``ref-supply`` is
160present, then the external reference voltage is used and the internal buffer is
161disabled. If ``refin-supply`` is present, then the internal buffered reference
162voltage is used.
163
164Reset
165-----
166
167Both hardware and software reset are supported. The driver looks first at the
168device tree to see if the ``reset-gpio`` is populated.
169If not present, the driver will fallback to a software reset by wiring to the
170device's registers.
171
172Unimplemented features
173----------------------
174
175- ``BUSY`` indication
176- Additional wiring modes
177- Additional clock modes
178- Differential data 16-bits + common-mode for 24-bits chips
179- Overrange events
180- Test patterns
181