Message-ID: <20251217-staging-ad4062-v4-0-7890a2951a8f@analog.com>
Date: Wed, 17 Dec 2025 13:13:23 +0100
From: Jorge Marques <jorge.marques@...log.com>
To: Lars-Peter Clausen <lars@...afoo.de>,
        Michael Hennerich
	<Michael.Hennerich@...log.com>,
        Jonathan Cameron <jic23@...nel.org>,
        David
 Lechner <dlechner@...libre.com>,
        Nuno Sá
	<nuno.sa@...log.com>,
        Andy Shevchenko <andy@...nel.org>, Rob Herring
	<robh@...nel.org>,
        Krzysztof Kozlowski <krzk+dt@...nel.org>,
        Conor Dooley
	<conor+dt@...nel.org>, Jonathan Corbet <corbet@....net>,
        Linus Walleij
	<linus.walleij@...aro.org>,
        Bartosz Golaszewski <brgl@...ev.pl>
CC: <linux-iio@...r.kernel.org>, <devicetree@...r.kernel.org>,
        <linux-kernel@...r.kernel.org>, <linux-doc@...r.kernel.org>,
        <linux-gpio@...r.kernel.org>, Jorge Marques <jorge.marques@...log.com>,
        Linus
 Walleij <linusw@...nel.org>
Subject: [PATCH v4 0/9] Add support for AD4062 device family

The AD4060/AD4062 are versatile, 16-bit/12-bit, successive approximation
register (SAR) analog-to-digital converter (ADC).

The device uses a 2-wire I3C interface. The device simplifies acquisition
by providing 4-bytes in the register map, signal-extending the sample
reading accordingly.

The device has autonomous monitoring capabilities, that are exposed as
IIO events. Since register access requires leaving the monitoring state
and returning, any device access exits monitoring mode, disabling the
IIO event.

The device contains two optional outputs:

- gp0: ADC conversion ready signal on the falling edge.
       The user should either invert the signal or set the IRQ as falling edge.
- gp1: Threshold either event interrupt on the rising edge.

The devices utilizes PM to enter the low power mode.

The devices datasheet:
https://www.analog.com/media/en/technical-documentation/data-sheets/ad4060.pdf
https://www.analog.com/media/en/technical-documentation/data-sheets/ad4062.pdf

The monitoring capabilities, I3C protocol, and multiple GPIOs were the
decision factor to have a standalone driver for this device family. The
device is expected to work with any I3C Bus. I tested the device with
with off-the-shelf I3C controllers STM32H7 (baremetal only) and the
open-source ADI I3C Controller (with Linux driver):
https://analogdevicesinc.github.io/hdl/library/i3c_controller/index.html
ADI I3C Controller lore:
https://lore.kernel.org/linux-i3c/175788312841.382502.16653824321627644225.b4-ty@bootlin.com/

The series is divided in 3 blocks, adding:
- The base driver.
- An software IIO trigger: captures samples continuously.
- IIO events support: exposes the device's threshold monitoring
  capability.

The device internal clock register is exposed twice, as
sampling_frequency and events/sampling_frequency, storing in distinct 
state variables, since the usage (burst averaging mode and monitor mode)
cannot be executed at the same time.

Non-implemented features:

- Averaging mode: Similar to burst averaging mode used in the
  oversampling, but requiring a sequence of CNV triggers for each
  conversion.
- Trigger mode: Similar to monitor mode used in the monitoring mode, but
  exits to configuration mode on event.

This device is almost identical to AD4052 family, but I decided to
submit the AD4062 before re-submitting AD4052 to better contextualize
the focus of the device family (high latency, medium-speed protocol,
low-power autonomous monitoring rather than high-throughput
acquisition).

Depending on the resolution of this driver, the AD4052 family may be
added to it, by splitting into ad4062_i3c.c, ad4062_spi.c,
ad4062_core.c, or as a standalone driver ad4052.c.

Depends on:
https://lore.kernel.org/linux-i3c/aRYLc%2F+KAD13g7T7@lizhi-Precision-Tower-5810/T/#t
(for devm ibi clean-up)

Signed-off-by: Jorge Marques <jorge.marques@...log.com>
---
Changes in v4:
- dt-bindings:
  * Simplification of interrupts description
  * Add minItems to interrupt-names, now symmetrical to interrupts.
- docs/ad4052.rst:
  * Drop "Unimplemented features" list (normally forgotten in the long term).
- Move scan_type implementation to iio trigger commit.
- Move #include sysfs.h to iio event commit (used by events/sampling_frequency)
- Fix avg_max type (u8 -> u16) to fit all variants.
- Assert val2 != 0, -EINVAL at oversampling_ratio, store bit position
  instead of resolved value
- Use u32 instead of u64 arithmetics on all possible locations.
- Fix regression at ad4062_get_sampling_frequency missing IIO_VAL_INT return.
- Use be*_to_cpu/cpu_to_be* instead of get/put_unaligned_u*
- Use devm_add_action for IBI
- Refactor methods to use _dispatch methods to, for future usage with
  "ACQUIRE for claim direct mode".
- Fix regression on GPIO configuration, introduced by misuse of masks.
- Simplify calibscale by using IIO_VAL_FRACTIONAL_LOG2.
- Simplify read_chan_raw by using "un-optimized" option for sample
  read, to not depend on scan_type (triggered buffer uses the optimized
  version).
- Fix non-compile constant ad4060_chip_info.prod_id at i3c_device_id by
  using defines AD406*_PROD_ID (kernel ci caught).
- Fix scan-type realbits/storagebits.
- Introduce st->conv_sizeof, st->conv_addr for the optimize triggered
  buffer readings (lest protocol overhead). Adds intuitive
  ad4062_sizeof_storagebits() and ad4062_get_conv_addr() helpers for the
  changing scan_type (due to oversampling).
- Use iio_push_to_buffers_with_ts
- Review chan_scale, add clearer units and move "signed" comment to the
  vref_uV multiplication, as in the datasheet (result is unchanged).
- Use devm for trigger_work.
- Use clearer fieldbit-dependent expression like
  `val != sign_extend32(val, AD4062_LIMIT_BITS - 1)` instead of magic numbers
  `val > 2047 || val < -2048`
- Fix regression on range for threshold value.
- Fix regression on enter MONITOR_MODE by adding missing address point
  write
- Note: false checkpatch positive at "iio: adc: ad4062: Add IIO Trigger
  support" due to macro change adding "bits", used by the ext_scan_type.
- Link to v3: https://lore.kernel.org/r/20251205-staging-ad4062-v3-0-8761355f9c66@analog.com

Changes in v3:
- dt-bidings:
  * Add minItems to interrupt-names, to match interrupts.
  * Reword descriptions.
- Add () to methods in commit messages.
- Group defines by context, adding blanking line between.
- Change ad4062_conversion_freqs from int to unsigned int
- Rename vref_uv to vref_uV
- Re-order state struct, to save some bytes.
- At oversampling_ratio(), use in_range()
- Add formulas, units where appropriate.
- Tune reset delay (data sheet value) and sleep mode resume delay
  (experimental).
- Rework st->oversamp_ratio to store the exponent, so 0 is ratio 1 (2**0).
- Rework get_chan_calibscale() to use IIO_VAL_FRACTIONAL_LOG2,
  simplifying the logic.
- Rework set_chan_calibscale() to not use 64-bits arithmetics, and
  provide formulas, and comments.
- Merge __ad4062_read_chan_raw() into ad4062_read_chan_raw(), since was
  the only consumer.
- Optimize readings with GPO set as DATA_READY, by using CONV_READ
  register (roughly doubles the effective sample rate).
- Use new ACQUIRE macros for pm.
- Use devm wrapper for INIT_WORK, cancelling on driver removal,
  resolving exception if the duffer was enabled during removal.
- When possible, use  `return ret ?:`.
- Use IIO_DEVICE_ATTR_RW() instead of IIO_DEVICE_ATTR().
- Use AD4062_LIMIT_BITS - 1 or BIT(x) - 1 to indicate hw limit/field
  size.
- Explain in the commit message why gpio-regmap cannot be used, and
  gpio-controller is used instead.
- Return  relational operator directly (has type int).

- Link to v2: https://lore.kernel.org/r/20251124-staging-ad4062-v2-0-a375609afbb7@analog.com

Changes in v2:
- dt-bindings:
  * add a short description of all mode that can be configured to during
    runtime.
  * add gpio-controller, to expose GPs not listed in interrupt-names as
    a GPO.
- sampling_frequency is the duration of a single sample (convert-start
  high edge until RDY falling edge) ((n_avg - 1) / fosc + tconv)
- Remove .grade from chip_info, since the supported devices have a
  single speed grade.
- Update state buffer to use dma-aligned union of __be32, __be16, u8 bytes[4].
- Use standard IIO_CHAN_INFO_SAMP_FREQ and _AVAIL
- Add defines to magic numbers.
- Ensure commits only contain code related to the particular commit.
- Use new ACQUIRE pm macros.
- Drop lock for debugfs, let user mess the state thorugh the debug
  interface.
- Restructure vio, vdd, ref voltages, only read if needed.
- Have error handling on top.
- Drop unnecessary check_ids error message.
- Use devm for IBI remove (requires patch on i3c subystem).
- Use heap buffers for all i3c_priv_xfer.
- Use CONV_READ if GP1 is routed (less overhead), use CONV_TRIGGER for
  IBI fallback.
- Drop usage pm_runtime_mark_last_busy, since it is now internal to pm_runtime_put_autosuspend
- Don't allow access if monitor mode is enabled, return -EBUSY.
- Implement gpio-controller to expose GPs not listed in interrupt-names
  as a GPO.
- Value in mv as ``raw * _scale`` (embed caliscale).
- Link to v1: https://lore.kernel.org/r/20251013-staging-ad4062-v1-0-0f8ce7fef50c@analog.com

---
Jorge Marques (9):
      dt-bindings: iio: adc: Add adi,ad4062
      docs: iio: New docs for ad4062 driver
      iio: adc: Add support for ad4062
      docs: iio: ad4062: Add IIO Trigger support
      iio: adc: ad4062: Add IIO Trigger support
      docs: iio: ad4062: Add IIO Events support
      iio: adc: ad4062: Add IIO Events support
      docs: iio: ad4062: Add GPIO Controller support
      iio: adc: ad4062: Add GPIO Controller support

 .../devicetree/bindings/iio/adc/adi,ad4062.yaml    |  120 ++
 Documentation/iio/ad4062.rst                       |  148 ++
 Documentation/iio/index.rst                        |    1 +
 MAINTAINERS                                        |    8 +
 drivers/iio/adc/Kconfig                            |   13 +
 drivers/iio/adc/Makefile                           |    1 +
 drivers/iio/adc/ad4062.c                           | 1609 ++++++++++++++++++++
 7 files changed, 1900 insertions(+)
---
base-commit: f9e05791642810a0cf6237d39fafd6fec5e0b4bb
change-id: 20251011-staging-ad4062-20d897d33ab6
prerequisite-change-id: 20251112-ibi-unsafe-48f343e178b8:v1
prerequisite-patch-id: 5f04cbbca0fcc3657c7a4d254656b03e289ad222
prerequisite-message-id: aReN+P5UZTnS1Tww@...hi-Precision-Tower-5810

Best regards,
-- 
Jorge Marques <jorge.marques@...log.com>

Powered by blists - more mailing lists