path: root/Documentation/iio/ad7768.rst

.. 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