1.. SPDX-License-Identifier: GPL-2.0-only 2 3============= 4AD4695 driver 5============= 6 7ADC driver for Analog Devices Inc. AD4695 and similar devices. The module name 8is ``ad4695``. 9 10 11Supported devices 12================= 13 14The following chips are supported by this driver: 15 16* `AD4695 <https://www.analog.com/AD4695>`_ 17* `AD4696 <https://www.analog.com/AD4696>`_ 18* `AD4697 <https://www.analog.com/AD4697>`_ 19* `AD4698 <https://www.analog.com/AD4698>`_ 20 21 22Supported features 23================== 24 25SPI wiring modes 26---------------- 27 28The driver currently supports the following SPI wiring configuration: 29 304-wire mode 31^^^^^^^^^^^ 32 33In this mode, CNV and CS are tied together and there is a single SDO line. 34 35.. code-block:: 36 37 +-------------+ +-------------+ 38 | CS |<-+------| CS | 39 | CNV |<-+ | | 40 | ADC | | HOST | 41 | | | | 42 | SDI |<--------| SDO | 43 | SDO |-------->| SDI | 44 | SCLK |<--------| SCLK | 45 +-------------+ +-------------+ 46 47To use this mode, in the device tree, omit the ``cnv-gpios`` and 48``spi-rx-bus-width`` properties. 49 50SPI offload wiring 51^^^^^^^^^^^^^^^^^^ 52 53When used with a SPI offload, the supported wiring configuration is: 54 55.. code-block:: 56 57 +-------------+ +-------------+ 58 | GP0/BUSY |-------->| TRIGGER | 59 | CS |<--------| CS | 60 | | | | 61 | ADC | | SPI | 62 | | | | 63 | SDI |<--------| SDO | 64 | SDO |-------->| SDI | 65 | SCLK |<--------| SCLK | 66 | | | | 67 | | +-------------+ 68 | CNV |<-----+--| PWM | 69 | | +--| GPIO | 70 +-------------+ +-------------+ 71 72In this case, both the ``cnv-gpios`` and ``pwms`` properties are required. 73The ``#trigger-source-cells = <2>`` property is also required to connect back 74to the SPI offload. The SPI offload will have ``trigger-sources`` property 75with cells to indicate the busy signal and which GPx pin is used, e.g 76``<&ad4695 AD4695_TRIGGER_EVENT_BUSY AD4695_TRIGGER_PIN_GP0>``. 77 78.. seealso:: `SPI offload support`_ 79 80Channel configuration 81--------------------- 82 83Since the chip supports multiple ways to configure each channel, this must be 84described in the device tree based on what is actually wired up to the inputs. 85 86There are three typical configurations: 87 88An ``INx`` pin is used as the positive input with the ``REFGND``, ``COM`` or 89the next ``INx`` pin as the negative input. 90 91Pairing with REFGND 92^^^^^^^^^^^^^^^^^^^ 93 94Each ``INx`` pin can be used as a pseudo-differential input in conjunction with 95the ``REFGND`` pin. The device tree will look like this: 96 97.. code-block:: 98 99 channel@0 { 100 reg = <0>; /* IN0 */ 101 }; 102 103If no other channel properties are needed (e.g. ``adi,no-high-z``), the channel 104node can be omitted entirely. 105 106This will appear on the IIO bus as the ``voltage0`` channel. The processed value 107(*raw × scale*) will be the voltage present on the ``IN0`` pin relative to 108``REFGND``. (Offset is always 0 when pairing with ``REFGND``.) 109 110Pairing with COM 111^^^^^^^^^^^^^^^^ 112 113Each ``INx`` pin can be used as a pseudo-differential input in conjunction with 114the ``COM`` pin. The device tree will look like this: 115 116.. code-block:: 117 118 com-supply = <&vref_div_2>; 119 120 channel@1 { 121 reg = <1>; /* IN1 */ 122 common-mode-channel = <AD4695_COMMON_MODE_COM>; 123 bipolar; 124 }; 125 126This will appear on the IIO bus as the ``voltage1`` channel. The processed value 127(*(raw + offset) × scale*) will be the voltage measured on the ``IN1`` pin 128relative to ``REFGND``. (The offset is determined by the ``com-supply`` voltage.) 129 130The macro comes from: 131 132.. code-block:: 133 134 #include <dt-bindings/iio/adc/adi,ad4695.h> 135 136Pairing two INx pins 137^^^^^^^^^^^^^^^^^^^^ 138 139An even-numbered ``INx`` pin and the following odd-numbered ``INx`` pin can be 140used as a pseudo-differential input. The device tree for using ``IN2`` as the 141positive input and ``IN3`` as the negative input will look like this: 142 143.. code-block:: 144 145 in3-supply = <&vref_div_2>; 146 147 channel@2 { 148 reg = <2>; /* IN2 */ 149 common-mode-channel = <3>; /* IN3 */ 150 bipolar; 151 }; 152 153This will appear on the IIO bus as the ``voltage2`` channel. The processed value 154(*(raw + offset) × scale*) will be the voltage measured on the ``IN1`` pin 155relative to ``REFGND``. (Offset is determined by the ``in3-supply`` voltage.) 156 157VCC supply 158---------- 159 160The chip supports being powered by an external LDO via the ``VCC`` input or an 161internal LDO via the ``LDO_IN`` input. The driver looks at the device tree to 162determine which is being used. If ``ldo-supply`` is present, then the internal 163LDO is used. If ``vcc-supply`` is present, then the external LDO is used and 164the internal LDO is disabled. 165 166Reference voltage 167----------------- 168 169The chip supports an external reference voltage via the ``REF`` input or an 170internal buffered reference voltage via the ``REFIN`` input. The driver looks 171at the device tree to determine which is being used. If ``ref-supply`` is 172present, then the external reference voltage is used and the internal buffer is 173disabled. If ``refin-supply`` is present, then the internal buffered reference 174voltage is used. 175 176Gain/offset calibration 177----------------------- 178 179System calibration is supported using the channel gain and offset registers via 180the ``calibscale`` and ``calibbias`` attributes respectively. 181 182Oversampling 183------------ 184 185The chip supports per-channel oversampling when SPI offload is being used, with 186available oversampling ratios (OSR) of 1 (default), 4, 16, and 64. Enabling 187oversampling on a channel raises the effective number of bits of sampled data to 18817 (OSR == 4), 18 (16), or 19 (64), respectively. This can be set via the 189``oversampling_ratio`` attribute. 190 191Setting the oversampling ratio for a channel also changes the sample rate for 192that channel, since it requires multiple conversions per 1 sample. Specifically, 193the new sampling frequency is the PWM sampling frequency divided by the 194particular OSR. This is set automatically by the driver when setting the 195``oversampling_ratio`` attribute. For example, if the device's current 196``sampling_frequency`` is 10000 and an OSR of 4 is set on channel ``voltage0``, 197the new reported sampling rate for that channel will be 2500 (ignoring PWM API 198rounding), while all others will remain at 10000. Subsequently setting the 199sampling frequency to a higher value on that channel will adjust the CNV trigger 200period for all channels, e.g. if ``voltage0``'s sampling frequency is adjusted 201from 2500 (with an OSR of 4) to 10000, the value reported by 202``in_voltage0_sampling_frequency`` will be 10000, but all other channels will 203now report 40000. 204 205For simplicity, the sampling frequency of the device should be set (considering 206the highest desired OSR value to be used) first, before configuring oversampling 207for specific channels. 208 209Unimplemented features 210---------------------- 211 212- Additional wiring modes 213- Threshold events 214- GPIO support 215- CRC support 216 217SPI offload support 218=================== 219 220To be able to achieve the maximum sample rate, the driver can be used with the 221`AXI SPI Engine`_ to provide SPI offload support. 222 223.. _AXI SPI Engine: http://analogdevicesinc.github.io/hdl/projects/ad469x_fmc/index.html 224 225.. seealso:: `SPI offload wiring`_ 226 227When SPI offload is being used, some attributes will be different. 228 229* ``trigger`` directory is removed. 230* ``in_voltage0_sampling_frequency`` attributes are added for setting the sample 231 rate. 232* ``in_voltage0_sampling_frequency_available`` attributes are added for querying 233 the max sample rate. 234* ``timestamp`` channel is removed. 235* Buffer data format may be different compared to when offload is not used, 236 e.g. the ``buffer0/in_voltage0_type`` attribute. 237 238Device buffers 239============== 240 241This driver supports hardware triggered buffers. This uses the "advanced 242sequencer" feature of the chip to trigger a burst of conversions. 243 244Also see :doc:`iio_devbuf` for more general information. 245 246Effective sample rate for buffered reads 247---------------------------------------- 248 249When SPI offload is not used, the sample rate is determined by the trigger that 250is manually configured in userspace. All enabled channels will be read in a 251burst when the trigger is received. 252 253When SPI offload is used, the sample rate is configured per channel. All 254channels will have the same rate, so only one ``in_voltageY_sampling_frequency`` 255attribute needs to be set. Since this rate determines the delay between each 256individual conversion, the effective sample rate for each sample is actually 257the sum of the periods of each enabled channel in a buffered read. In other 258words, it is the value of the ``in_voltageY_sampling_frequency`` attribute 259divided by the number of enabled channels. So if 4 channels are enabled, with 260the ``in_voltageY_sampling_frequency`` attributes set to 1 MHz, the effective 261sample rate is 250 kHz. 262 263With oversampling enabled, the effective sample rate also depends on the OSR 264assigned to each channel. For example, if one of the 4 channels mentioned in the 265previous case is configured with an OSR of 4, the effective sample rate for that 266channel becomes (1 MHz / 4 ) = 250 kHz. The effective sample rate for all 267four channels is then 1 / ( (3 / 1 MHz) + ( 1 / 250 kHz) ) ~= 142.9 kHz. Note 268that in this case "sample" refers to one read of all enabled channels (i.e. one 269full cycle through the auto-sequencer). 270