Message-ID: <20250913134656.44964f5f@jic23-huawei>
Date: Sat, 13 Sep 2025 13:46:56 +0100
From: Jonathan Cameron <jic23@...nel.org>
To: Antoniu Miclaus <antoniu.miclaus@...log.com>
Cc: <robh@...nel.org>, <conor+dt@...nel.org>, <linux-iio@...r.kernel.org>,
 <linux-kernel@...r.kernel.org>, <devicetree@...r.kernel.org>
Subject: Re: [PATCH v7 5/6] docs: iio: add documentation for ade9000 driver

On Mon, 8 Sep 2025 07:35:25 +0000
Antoniu Miclaus <antoniu.miclaus@...log.com> wrote:

> Add documentation for ade9000 driver which describes the driver
> device files and shows how the user may use the ABI for various
> scenarios (configuration, measurement, etc.).
> 
> Signed-off-by: Antoniu Miclaus <antoniu.miclaus@...log.com>
> ---
> changes in v7:
>  - remove PGA gain documentation section
>  - remove frequency configuration section
>  - remove scale and frequency attributes from device-level attributes table
>  - update examples to remove PGA gain and frequency configuration
>  Documentation/iio/ade9000.rst | 265 ++++++++++++++++++++++++++++++++++
>  Documentation/iio/index.rst   |   1 +
>  2 files changed, 266 insertions(+)
>  create mode 100644 Documentation/iio/ade9000.rst
> 
> diff --git a/Documentation/iio/ade9000.rst b/Documentation/iio/ade9000.rst
> new file mode 100644
> index 000000000000..163d36a56be3
> --- /dev/null
> +++ b/Documentation/iio/ade9000.rst
> @@ -0,0 +1,265 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===============
> +ADE9000 driver
> +===============
> +
> +This driver supports Analog Device's ADE9000 energy measurement IC on SPI bus.
> +
> +1. Supported devices
> +====================
> +
> +* `ADE9000 <https://www.analog.com/media/en/technical-documentation/data-sheets/ADE9000.pdf>`_
> +
> +The ADE9000 is a highly accurate, fully integrated, multiphase energy and power
> +quality monitoring device. Superior analog performance and a digital signal
> +processing (DSP) core enable accurate energy monitoring over a wide dynamic
> +range. An integrated high end reference ensures low drift over temperature
> +with a combined drift of less than ±25 ppm/°C maximum for the entire channel
> +including a programmable gain amplifier (PGA) and an analog-to-digital
> +converter (ADC).
> +
> +2. Device attributes
> +====================
> +
> +Power and energy measurements are provided for voltage, current, active power,
> +reactive power, apparent power, and power factor across three phases.
> +
> +Each IIO device has a device folder under ``/sys/bus/iio/devices/iio:deviceX``,
> +where X is the IIO index of the device. Under these folders reside a set of
> +device files, depending on the characteristics and features of the hardware
> +device in question. These files are consistently generalized and documented in
> +the IIO ABI documentation.
> +
> +The following tables show the ADE9000 related device files, found in the
> +specific device folder path ``/sys/bus/iio/devices/iio:deviceX``.
> +
> ++---------------------------------------------------+----------------------------------------------------------+
> +| Current measurement related device files          | Description                                              |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_current[0-2]_raw                               | Raw current measurement for phases A, B, C.              |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_current[0-2]_scale                             | Scale for current channels.                              |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_current[0-2]_calibscale                        | Calibration gain for current channels (AIGAIN reg).      |
I thought someone raised this on the previous version, but perhaps I imagined it.
Missing line break here.

> +| in_altcurrent[0-2]_rms_raw                        | RMS current measurement for phases A, B, C.              |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_altcurrent[0-2]_rms_scale                      | Scale for RMS current channels.                          |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_altcurrent[0-2]_rms_calibbias                  | RMS offset correction for current channels (IRMSOS reg). |
> ++---------------------------------------------------+----------------------------------------------------------+
> +
> ++---------------------------------------------------+----------------------------------------------------------+
> +| Voltage measurement related device files          | Description                                              |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_voltage[0-2]_raw                               | Raw voltage measurement for phases A, B, C.              |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_voltage[0-2]_scale                             | Scale for voltage channels.                              |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_voltage[0-2]_calibscale                        | Calibration gain for voltage channels (AVGAIN reg).      |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_voltage[0-2]_frequency                         | Measured line frequency from instantaneous voltage.      |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_altvoltage[0-2]_rms_raw                        | RMS voltage measurement for phases A, B, C.              |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_altvoltage[0-2]_rms_scale                      | Scale for RMS voltage channels.                          |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_altvoltage[0-2]_rms_calibbias                  | RMS offset correction for voltage channels (VRMSOS reg). |
> ++---------------------------------------------------+----------------------------------------------------------+
> +
> ++---------------------------------------------------+----------------------------------------------------------+
> +| Power measurement related device files            | Description                                              |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_power[0-2]_active_raw                          | Active power measurement for phases A, B, C.             |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_power[0-2]_active_scale                        | Scale for active power channels.                         |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_power[0-2]_active_calibbias                    | Calibration offset for active power (xWATTOS regs).      |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_power[0-2]_active_calibscale                   | Calibration gain for active power (APGAIN reg).          |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_power[0-2]_reactive_raw                        | Reactive power measurement for phases A, B, C.           |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_power[0-2]_reactive_scale                      | Scale for reactive power channels.                       |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_power[0-2]_reactive_calibbias                  | Calibration offset for reactive power (xVAROS regs).     |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_power[0-2]_apparent_raw                        | Apparent power measurement for phases A, B, C.           |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_power[0-2]_apparent_scale                      | Scale for apparent power channels.                       |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_power[0-2]_powerfactor                         | Power factor for phases A, B, C.                         |
> ++---------------------------------------------------+----------------------------------------------------------+
> +
> ++---------------------------------------------------+----------------------------------------------------------+
> +| Energy measurement related device files           | Description                                              |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_energy[0-2]_active_raw                         | Active energy measurement for phases A, B, C.            |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_energy[0-2]_reactive_raw                       | Reactive energy measurement for phases A, B, C.          |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_energy[0-2]_apparent_raw                       | Apparent energy measurement for phases A, B, C.          |
> ++---------------------------------------------------+----------------------------------------------------------+
> +
> ++------------------------------+------------------------------------------------------------------+
> +| Shared device attributes     | Description                                                      |
> ++------------------------------+------------------------------------------------------------------+
> +| name                         | Name of the IIO device.                                          |
> ++------------------------------+------------------------------------------------------------------+
> +| filter_type                  | Waveform buffer filter type (sinc4, sinc4+lp).                   |
> ++------------------------------+------------------------------------------------------------------+
> +| filter_type_available        | Available filter types for waveform buffer.                      |
> ++------------------------------+------------------------------------------------------------------+
> +
> +3. Calibration and scaling
> +===========================
> +
> +The ADE9000 provides multiple levels of gain and offset correction:
> +
> +**Calibration Gain (per-channel)**
> +  Fine-tuning calibration gains applied in the digital domain for each channel type.
> +  Controlled via ``calibscale`` attributes (AIGAIN, AVGAIN, APGAIN registers).
> +
> +**Calibration Bias (per-channel)**
> +  Hardware calibration offsets applied by the device internally:
> +
> +  - Power measurements: Controlled via ``calibbias`` attributes for power channels (xWATTOS, xVAROS registers).
> +  - RMS measurements: Controlled via ``calibbias`` attributes for RMS channels (IRMSOS, VRMSOS registers).
> +
> +  These are internal chip calibrations, not userspace-applied offsets.
> +
> +4. Event attributes
> +===================
> +
> +The ADE9000 provides various interrupts that are mapped to IIO events.
> +Event functionality is only available if the corresponding interrupts are
> +connected in the device tree.
> +
> ++---------------------------------------------------+----------------------------------------------------------+
> +| IIO Event Attribute                               | ADE9000 Datasheet Equivalent                             |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_voltage[0-2]_thresh_either_en                  | Zero crossing detection interrupt (ZXVx)                 |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_altvoltage[0-2]_rms_thresh_rising_en           | RMS swell detection interrupt (SWELLx)                   |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_altvoltage[0-2]_rms_thresh_rising_value        | RMS swell threshold (SWELL_LVL register)                 |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_altvoltage[0-2]_rms_thresh_falling_en          | RMS sag/dip detection interrupt (DIPx)                   |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_altvoltage[0-2]_rms_thresh_falling_value       | RMS sag/dip threshold (DIP_LVL register)                 |
> ++---------------------------------------------------+----------------------------------------------------------+
> +| in_current[0-2]_thresh_either_en                  | Current zero crossing detection interrupt (ZXIx)         |
> ++---------------------------------------------------+----------------------------------------------------------+
> +
> +Event directions:
> +- ``rising``: Upper threshold crossing (swell detection)
> +- ``falling``: Lower threshold crossing (sag/dip detection)
> +- ``either``: Any threshold crossing (zero crossing detection)
> +- ``none``: Timeout or non-directional events
> +
> +**Note**: Event attributes are only available if the corresponding interrupts
> +(irq0, irq1, dready) are specified in the device tree. The driver works without
> +interrupts but with reduced functionality.
> +
> +5. Device buffers
> +=================
> +
> +This driver supports IIO buffers for waveform capture. Buffer functionality
> +requires the dready interrupt to be connected.
> +
> +The device supports capturing voltage and current waveforms for power quality
> +analysis. The waveform buffer can be configured to capture data from different
> +channel combinations.
> +
> +Supported channel combinations for buffered capture:
> +- Phase A: voltage and current (IA + VA)
> +- Phase B: voltage and current (IB + VB)
> +- Phase C: voltage and current (IC + VC)
> +- All phases: all voltage and current channels
> +- Individual channels: IA, VA, IB, VB, IC, VC
> +
> +Usage examples
> +--------------
> +
> +Enable waveform capture for Phase A:
> +
> +.. code-block:: bash
> +
> +        root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_current0_en
> +        root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_voltage0_en
> +
> +Set buffer length and enable:
> +
> +.. code-block:: bash
> +
> +        root:/sys/bus/iio/devices/iio:device0> echo 100 > buffer/length
> +        root:/sys/bus/iio/devices/iio:device0> echo 1 > buffer/enable
> +
> +6. Clock output
> +===============
> +
> +The ADE9000 can provide a clock output via the CLKOUT pin when using an external
> +crystal/clock source. This feature is enabled by specifying ``#clock-cells = <0>``
> +in the device tree. The output clock will be registered as "clkout" and can be
> +referenced by other devices.
> +
> +7. Usage examples
> +=================
> +
> +Show device name:
> +
> +.. code-block:: bash
> +
> +	root:/sys/bus/iio/devices/iio:device0> cat name
> +        ade9000
> +
> +Read voltage measurements:
> +
> +.. code-block:: bash
> +
> +        root:/sys/bus/iio/devices/iio:device0> cat in_voltage0_raw
> +        12345
> +        root:/sys/bus/iio/devices/iio:device0> cat in_voltage0_scale
> +        0.000030517
> +
> +- Phase A voltage = in_voltage0_raw * in_voltage0_scale = 0.3769 V
> +
> +Read power measurements:
> +
> +.. code-block:: bash
> +
> +        root:/sys/bus/iio/devices/iio:device0> cat in_power0_active_raw
> +        5678
> +        root:/sys/bus/iio/devices/iio:device0> cat in_power0_scale
> +        0.000244140
> +
> +- Phase A active power = in_power0_active_raw * in_power0_scale = 1.386 W
> +
> +Configure calibration gains:
> +
> +.. code-block:: bash
> +
> +        # Set current channel 0 calibration gain
> +        root:/sys/bus/iio/devices/iio:device0> echo 0x800000 > in_current0_calibscale
> +        # Set voltage channel 0 calibration gain
> +        root:/sys/bus/iio/devices/iio:device0> echo 0x7FFFFF > in_voltage0_calibscale
> +
> +Configure RMS voltage event thresholds (requires interrupts):
> +
> +.. code-block:: bash
> +
> +        # Set RMS sag detection threshold
> +        root:/sys/bus/iio/devices/iio:device0> echo 180000 > events/in_altvoltage0_rms_thresh_falling_value
> +        # Enable RMS sag detection
> +        root:/sys/bus/iio/devices/iio:device0> echo 1 > events/in_altvoltage0_rms_thresh_falling_en
> +
> +        # Set RMS swell detection threshold
> +        root:/sys/bus/iio/devices/iio:device0> echo 260000 > events/in_altvoltage0_rms_thresh_rising_value
> +        # Enable RMS swell detection
> +        root:/sys/bus/iio/devices/iio:device0> echo 1 > events/in_altvoltage0_rms_thresh_rising_en
> +
> +8. IIO Interfacing Tools
> +========================
> +
> +See ``Documentation/iio/iio_tools.rst`` for the description of the available IIO
> +interfacing tools.
> diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst
> index c106402a91f7..792c815286f4 100644
> --- a/Documentation/iio/index.rst
> +++ b/Documentation/iio/index.rst
> @@ -28,6 +28,7 @@ Industrial I/O Kernel Drivers
>     ad7606
>     ad7625
>     ad7944
> +   ade9000
>     adis16475
>     adis16480
>     adis16550

Powered by blists - more mailing lists