| .. SPDX-License-Identifier: GPL-2.0-only | |
| ============= | |
| AD7768 driver | |
| ============= | |
| ADC driver for Analog Devices Inc. AD7768 and AD7768-4 devices. The module name | |
| is ``ad7768``. | |
| Supported devices | |
| ================= | |
| The following chips are supported by this driver: | |
| * `AD7768 <https://www.analog.com/en/products/ad7768.html>`_ - | |
| 8-channel, 24-bit simultaneous sampling ADC | |
| * `AD7768-4 <https://www.analog.com/en/products/ad7768-4.html>`_ - | |
| 4-channel, 24-bit simultaneous sampling ADC | |
| Supported features | |
| ================== | |
| Clock sources | |
| ------------- | |
| The master clock source is selected using the ``clock-names`` device tree | |
| property: | |
| * ``mclk`` selects a CMOS clock on XTAL2/MCLK. CLK_SEL must be low and XTAL1 | |
| must be connected to DGND. | |
| * ``xtal`` selects a crystal connected between XTAL1 and XTAL2. CLK_SEL must | |
| be high. The driver drives FILTER/GPIO4 high and keeps channel 4 on the | |
| AD7768 or channel 2 on the AD7768-4 enabled to maintain crystal excitation. | |
| * ``lvds`` selects a differential clock on XTAL1 and XTAL2. CLK_SEL must be | |
| high. The driver drives FILTER/GPIO4 low before enabling the LVDS input. | |
| GPIO4 is reserved when ``xtal`` or ``lvds`` is selected. | |
| Power modes | |
| ----------- | |
| The AD7768 family supports three power and performance modes: | |
| * **Low power mode** - Optimized for lowest power consumption | |
| * **Median mode** - Balanced power and performance | |
| * **Fast mode** - Highest performance with maximum sampling rates | |
| The driver initializes the device in fast mode and uses the maximum fast-mode | |
| output data rate as the default sampling frequency. | |
| When buffered capture starts, the driver selects the lowest-noise mode that can | |
| produce the requested output data rates for all enabled channels. Where output | |
| data rates overlap, fast mode is preferred over median mode, and median mode is | |
| preferred over low power mode. This prioritizes the lower RMS noise and higher | |
| dynamic range offered by a faster mode at the same output data rate. | |
| Data output configuration | |
| ------------------------- | |
| The devices support flexible serial data output configurations: | |
| AD7768 data lines | |
| ^^^^^^^^^^^^^^^^^ | |
| * 1 data line (DOUT0) - Standard single-lane output | |
| * 2 data lines (DOUT0, DOUT1) - Dual-lane output for higher throughput | |
| * 8 data lines (DOUT0-DOUT7) - Maximum throughput, one line per channel | |
| AD7768-4 data lines | |
| ^^^^^^^^^^^^^^^^^^^ | |
| * 1 data line (DOUT0) - Standard single-lane output | |
| * 4 data lines (DOUT0-DOUT3) - Maximum throughput, one line per channel | |
| The number of data lines can be configured via the ``adi,data-lines-number`` | |
| device tree property. If omitted, the driver uses the maximum supported by the | |
| selected variant: eight lines for AD7768 and four lines for AD7768-4. | |
| Channel configuration | |
| --------------------- | |
| Each channel can be individually configured with: | |
| Channel modes | |
| ^^^^^^^^^^^^^ | |
| * **Mode A** - First set of filter and decimation settings | |
| * **Mode B** - Second set of filter and decimation settings | |
| The hardware provides two mode profiles (A and B), each holding one | |
| (frequency, filter) combination. When buffered capture is started, | |
| enabled channels are grouped by their configured (frequency, filter) | |
| pair. Up to two distinct groups are supported; the driver automatically | |
| assigns each group to a mode slot and programs the hardware accordingly. | |
| If the enabled channels request more than two distinct pairs, buffer setup | |
| fails and capture does not start. | |
| Precharge and reference buffers | |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| Per-channel buffer control for optimal signal integrity: | |
| * Positive input precharge buffer (``adi,prechargebuf-pos-enable``) | |
| * Negative input precharge buffer (``adi,prechargebuf-neg-enable``) | |
| * Positive reference buffer (``adi,refbuf-pos-enable``) | |
| * Negative reference buffer (``adi,refbuf-neg-enable``) | |
| Common mode voltage | |
| ------------------- | |
| The VCM pin provides a buffered common-mode voltage output used to bias | |
| the analog inputs. The driver exposes this as a standard voltage regulator | |
| provider under a ``regulators`` subnode in the device tree. Supported | |
| output voltage levels are: | |
| * (AVDD1 - AVSS) / 2 - Mid-supply (hardware default), reported as half the | |
| voltage provided by ``avdd1-supply`` | |
| * 1,650,000 µV - 1.65V | |
| * 2,500,000 µV - 2.5V | |
| * 2,140,000 µV - 2.14V | |
| The regulator can be enabled and disabled at runtime using the standard | |
| regulator framework interfaces. | |
| The VCM circuitry is associated with channel 0. When VCM is used externally, | |
| ``channel@0`` must be present in the device tree and channel 0 must remain | |
| enabled in the active scan mask. Placing channel 0 in standby disables the VCM | |
| output. | |
| Filter types | |
| ------------ | |
| Two digital filter types are available: | |
| * **Wideband** - Optimized for wide bandwidth applications | |
| * **Sinc5** - Fifth-order sinc filter for high rejection of out-of-band noise | |
| IIO backend support | |
| ------------------- | |
| The driver integrates with IIO backends (e.g., AXI ADC) for high-speed data | |
| capture and DMA operations. Features include: | |
| * Automatic channel enable/disable based on scan mask | |
| * CRC on data interface. CRC replaces the header every 4th output sample. | |
| * High-throughput buffered data acquisition | |
| GPIO controller | |
| --------------- | |
| The AD7768 includes a 5-pin GPIO controller for auxiliary digital I/O | |
| operations. The GPIO pins can be configured as inputs or outputs. | |
| GPIO4 is reserved when a crystal or LVDS master clock is used. GPIO0 through | |
| GPIO3 remain available in these configurations. | |
| Device attributes | |
| ================= | |
| The following IIO attributes are available for each enabled channel: | |
| Voltage scale | |
| ------------- | |
| .. list-table:: | |
| :header-rows: 1 | |
| :widths: 40 60 | |
| * - Attribute | |
| - Description | |
| * - ``in_voltage<N>_scale`` | |
| - Scale in millivolts per least significant bit for signed 24-bit data, | |
| calculated as twice the differential reference voltage used by channel | |
| N divided by 2\ :sup:`24`. | |
| Sampling frequency | |
| ------------------ | |
| .. list-table:: | |
| :header-rows: 1 | |
| :widths: 40 60 | |
| * - Attribute | |
| - Description | |
| * - ``in_voltage<N>_sampling_frequency`` | |
| - Requested sampling frequency in Hz for channel N. Enabled channels are | |
| grouped into up to two profiles at capture time. | |
| * - ``in_voltage<N>_sampling_frequency_available`` | |
| - Available sampling frequencies in Hz for channel N across all power | |
| modes, based on the master clock frequency. Buffer setup fails if no | |
| single power mode supports the frequencies requested by all enabled | |
| channels. | |
| Filter configuration | |
| --------------------- | |
| .. list-table:: | |
| :header-rows: 1 | |
| :widths: 40 60 | |
| * - Attribute | |
| - Description | |
| * - ``in_voltage<N>_filter_type`` | |
| - Requested filter type for channel N: "wideband" or "sinc5". It is | |
| grouped with sampling frequency at capture time. | |
| * - ``in_voltage<N>_filter_type_available`` | |
| - Available filter types for channel N: "wideband sinc5". | |
| Per-channel calibration | |
| ----------------------- | |
| .. list-table:: | |
| :header-rows: 1 | |
| :widths: 40 60 | |
| * - Attribute | |
| - Description | |
| * - ``in_voltage<N>_calibbias`` | |
| - Signed 24-bit two's complement channel offset register value. | |
| * - ``in_voltage<N>_calibscale`` | |
| - Raw unsigned 24-bit channel gain register value. | |
| * - ``in_voltage<N>_convdelay`` | |
| - Per-channel conversion delay. The driver exposes the sync phase offset | |
| value in seconds with picosecond precision. Resolution and valid range | |
| depend on the decimation ratio in use (see datasheet | |
| Table 32). | |
| Device buffers | |
| ============== | |
| This driver supports IIO buffered data acquisition through IIO backends. | |
| When used with compatible backends like the AXI ADC, it provides: | |
| * High-speed simultaneous sampling across all enabled channels | |
| * Hardware-driven data capture | |
| * DMA-based data transfer for minimal CPU overhead | |
| * CRC error detection | |
| See :doc:`iio_devbuf` for more information about IIO device buffers. | |
| Example usage | |
| ============= | |
| .. code-block:: bash | |
| # Read current sampling frequency for channel 0 | |
| cat /sys/bus/iio/devices/iio:device0/in_voltage0_sampling_frequency | |
| # Update sampling frequency for channel 0 | |
| echo 8000 > /sys/bus/iio/devices/iio:device0/in_voltage0_sampling_frequency | |
| # Read current filter type for channel 0 | |
| cat /sys/bus/iio/devices/iio:device0/in_voltage0_filter_type | |
| # List available filter types for channel 0 | |
| cat /sys/bus/iio/devices/iio:device0/in_voltage0_filter_type_available | |
| # Update filter type for channel 0 to wideband | |
| echo wideband > /sys/bus/iio/devices/iio:device0/in_voltage0_filter_type | |
| # Buffer setup fails if enabled channels request more than two distinct | |
| # (sampling frequency, filter type) combinations. | |
| # Read calibration scale for channel 0 | |
| cat /sys/bus/iio/devices/iio:device0/in_voltage0_calibscale | |
| # Read conversion delay for channel 0 | |
| cat /sys/bus/iio/devices/iio:device0/in_voltage0_convdelay | |
| Unimplemented features | |
| ====================== | |
| * CRC message every 16 samples (CRC_SEL configuration) - currently only | |
| supports CRC every 4 samples |