Documentation/iio/ad4062.rst

.. SPDX-License-Identifier: GPL-2.0-only

=============
AD4062 driver
=============

ADC driver for Analog Devices Inc. AD4060/AD4062 devices. The module name is
``ad4062``.

Supported devices
=================

The following chips are supported by this driver:

* `AD4060 <https://www.analog.com/AD4060>`_
* `AD4062 <https://www.analog.com/AD4062>`_

Wiring modes
============

The ADC is interfaced through an I3C bus, and contains two programmable GPIOs.

The ADC convert-start happens on the SDA rising edge of the I3C stop (P) bit
at the end of the read command.

The two programmable GPIOS are optional and have a role assigned if present in
the devicetree ``interrupt-names`` property:

- GP0: Is assigned the role of Threshold Either signal.
- GP1: Is assigned the role of Data Ready signal.

If the property ``gpio-controller`` is present in the devicetree, then the GPO
not present in the ``interrupt-names`` is exposed as a GPO.

Device attributes
=================

The ADC contains only one channel with following attributes:

.. list-table:: Channel attributes
   :header-rows: 1

   * - Attribute
     - Description
   * - ``in_voltage_calibscale``
     - Sets the gain scaling factor that the hardware applies to the sample,
       to compensate for system gain error.
   * - ``in_voltage_oversampling_ratio``
     - Sets device's burst averaging mode to over sample using the
       internal sample rate. Value 1 disable the burst averaging mode.
   * - ``in_voltage_oversampling_ratio_available``
     - List of available oversampling values.
   * - ``in_voltage_raw``
     - Returns the raw ADC voltage value.
   * - ``in_voltage_scale``
     - Returns the channel scale in reference to the reference voltage
       ``ref-supply`` or ``vdd-supply`` if the former not present.

Also contain the following device attributes:

.. list-table:: Device attributes
   :header-rows: 1

   * - Attribute
     - Description
   * - ``sampling_frequency``
     - Sets the duration of a single scan, used in the burst averaging mode.
       The duration is described by ``(n_avg - 1) / fosc + tconv``, where
       ``n_avg`` is the oversampling ratio, ``fosc`` is the internal sample
       rate and ``tconv`` is the ADC conversion time.
   * - ``sampling_frequency_available``
     - Lists the available sampling frequencies, computed on the current
       oversampling ratio. If the ratio is 1, the frequency is ``1/tconv``.

Interrupts
==========

The interrupts are mapped through the ``interrupt-names`` and ``interrupts``
properties.

The ``interrupt-names`` ``gp0`` entry sets the role of Threshold signal, and
entry ``gp1`` the role of Data Ready signal.

If each is not present, the driver fallback to enabling the same role as an
I3C IBI.

Low-power mode
==============

The device enters low-power mode on idle to save power. Enabling an event puts
the device out of the low-power since the ADC autonomously samples to assert
the event condition.

IIO trigger support
===================

An IIO trigger ``ad4062-devX`` is registered by the driver to be used by the
same device, to capture samples to a software buffer. It is required to attach
the trigger to the device by setting the ``current_trigger`` before enabling
and reading the buffer.

The acquisition is sequential and bounded by the protocol timings, software
latency and internal timings, the sample rate is not configurable. The burst
averaging mode does impact the effective sample rate, since it increases the
internal timing to output a single sample.

Threshold events
================

The ADC supports a monitoring mode to raise threshold events. The driver
supports a single interrupt for both rising and falling readings.

The feature is enabled/disabled by setting ``thresh_either_en``. During monitor
mode, the device continuously operates in autonomous mode. Any register access
puts the device back in configuration mode, due to this, any access disables
monitor mode.

The following event attributes are available:

.. list-table:: Event attributes
   :header-rows: 1

   * - Attribute
     - Description
   * - ``sampling_frequency``
     - Frequency used in the monitoring mode, sets the device internal sample
       rate when the mode is activated.
   * - ``sampling_frequency_available``
     - List of available sample rates.
   * - ``thresh_either_en``
     - Enable monitoring mode.
   * - ``thresh_falling_hysteresis``
     - Set the hysteresis value for the minimum threshold.
   * - ``thresh_falling_value``
     - Set the minimum threshold value.
   * - ``thresh_rising_hysteresis``
     - Set the hysteresis value for the maximum threshold.
   * - ``thresh_rising_value``
     - Set the maximum threshold value.

GPO controller support
======================

The device supports using GP0 and GP1 as GPOs. If the devicetree contains the
node ``gpio-controller```, the device is marked as a GPIO controller and the
GPs not listed in ``interrupt-names`` are exposed as a GPO. The GPIO index
matches the pin name, so if GP0 is not exposed but GP1 is, index 0 is masked
out and only index 1 can be set.