tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: iio: ad4030: add documentation
This adds a new page to document how to use the ad4030 ADC driver
Signed-off-by: Esteban Blanc <eblanc@baylibre.com>
Link: https://patch.msgid.link/20250214-eblanc-ad4630_v1-v4-6-135dd66cab6a@baylibre.com
Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
authored by
Esteban Blanc
and committed by
Jonathan Cameron
b29050e8
ec25cf6f
+182
+180
Documentation/iio/ad4030.rst
+180
Documentation/iio/ad4030.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0-only
2
+
3
+
=============
4
+
AD4030 driver
5
+
=============
6
+
7
+
ADC driver for Analog Devices Inc. AD4030 and similar devices. The module name
8
+
is ``ad4030``.
9
+
10
+
11
+
Supported devices
12
+
=================
13
+
14
+
The 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
+
23
+
IIO channels
24
+
============
25
+
26
+
Each "hardware" channel as described in the datasheet is split in 2 IIO
27
+
channels:
28
+
29
+
- One channel for the differential data
30
+
- One channel for the common byte.
31
+
32
+
The 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
+
43
+
Labels
44
+
------
45
+
46
+
For ease of use, the IIO channels provide a label. For a differential channel,
47
+
the label is ``differentialN`` where ``N`` is the "hardware" channel id. For a
48
+
common-mode channel, the label is ``common-modeN`` where ``N`` is the
49
+
"hardware" channel id.
50
+
51
+
The 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
+
62
+
Supported features
63
+
==================
64
+
65
+
SPI wiring modes
66
+
----------------
67
+
68
+
The driver currently supports the following SPI wiring configurations:
69
+
70
+
One lane mode
71
+
^^^^^^^^^^^^^
72
+
73
+
In this mode, each channel has its own SDO line to send the conversion results.
74
+
At the moment this mode can only be used on AD4030 which has one channel so only
75
+
one 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
+
89
+
Interleaved mode
90
+
^^^^^^^^^^^^^^^^
91
+
92
+
In this mode, both channels conversion results are bit interleaved one SDO line.
93
+
As such the wiring is the same as `One lane mode`_.
94
+
95
+
SPI Clock mode
96
+
--------------
97
+
98
+
Only the SPI clocking mode is supported.
99
+
100
+
Output modes
101
+
------------
102
+
103
+
There are more exposed IIO channels than channels as describe in the devices
104
+
datasheet. This is due to the `Differential data + common-mode`_ encoding
105
+
2 types of information in one conversion result. As such a "device" channel
106
+
provides 2 IIO channels, one for the differential data and one for the common
107
+
byte.
108
+
109
+
Differential data
110
+
^^^^^^^^^^^^^^^^^
111
+
112
+
This mode is selected when:
113
+
114
+
- Only differential channels are enabled in a buffered read
115
+
- Oversampling attribute is set to 1
116
+
117
+
Differential data + common-mode
118
+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
119
+
120
+
This 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
+
125
+
For the 24-bits chips, this mode is also available with 16-bits differential
126
+
data but is not selectable yet.
127
+
128
+
Averaged differential data
129
+
^^^^^^^^^^^^^^^^^^^^^^^^^^
130
+
131
+
This mode is selected when:
132
+
133
+
- Only differential channels are selected enabled in a buffered read
134
+
- Oversampling attribute is greater than 1
135
+
136
+
Digital Gain and Offset
137
+
-----------------------
138
+
139
+
Each differential data channel has a 16-bits unsigned configurable hardware
140
+
gain applied to it. By default it's equal to 1. Note that applying gain can
141
+
cause numerical saturation.
142
+
143
+
Each differential data channel has a signed configurable hardware offset.
144
+
For the ADCs ending in ``-24``, the gain is encoded on 24-bits.
145
+
Likewise, the ADCs ending in ``-16`` have a gain encoded on 16-bits. Note that
146
+
applying an offset can cause numerical saturation.
147
+
148
+
The final differential data returned by the ADC is computed by first applying
149
+
the gain, then the offset.
150
+
151
+
The gain is controlled by the ``calibscale`` IIO attribute while the offset is
152
+
controlled by the ``calibbias`` attribute.
153
+
154
+
Reference voltage
155
+
-----------------
156
+
157
+
The chip supports an external reference voltage via the ``REF`` input or an
158
+
internal buffered reference voltage via the ``REFIN`` input. The driver looks
159
+
at the device tree to determine which is being used. If ``ref-supply`` is
160
+
present, then the external reference voltage is used and the internal buffer is
161
+
disabled. If ``refin-supply`` is present, then the internal buffered reference
162
+
voltage is used.
163
+
164
+
Reset
165
+
-----
166
+
167
+
Both hardware and software reset are supported. The driver looks first at the
168
+
device tree to see if the ``reset-gpio`` is populated.
169
+
If not present, the driver will fallback to a software reset by wiring to the
170
+
device's registers.
171
+
172
+
Unimplemented 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
+1
Documentation/iio/index.rst
+1
Documentation/iio/index.rst
+1
MAINTAINERS
+1
MAINTAINERS