Re: [PATCH v6 5/6] docs: iio: add documentation for ade9000 driver

[David Lechner <dlechner@baylibre.com>]

On 8/29/25 6:41 AM, Antoniu Miclaus 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.).

This is quite helpful to get the high-level picture of how this
is supposed to work.

> 
> Signed-off-by: Antoniu Miclaus <antoniu.miclaus@analog.com>
> ---
> changes in v6:
>  - add RMS channel documentation with scale and calibbias
>  - add separate scale docs for each power type
>  - improve calibration section explanation
>  - focus events on RMS voltage instead of instantaneous
>  - add filter_type attributes documentation
>  - update examples to use RMS voltage events
>  - complete device file attribute tables
>  Documentation/iio/ade9000.rst | 292 ++++++++++++++++++++++++++++++++++
>  Documentation/iio/index.rst   |   1 +
>  2 files changed, 293 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..869ba154653e
> --- /dev/null
> +++ b/Documentation/iio/ade9000.rst
> @@ -0,0 +1,292 @@
> +.. 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).      |

We should probably clarify that this is the instantaneous current.

Also missing a row divider 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).      |

row divider?

> +| in_voltage[0-2]_frequency                         | Measured line frequency for phases A, B, C.              |

And these are 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.                                          |
> ++------------------------------+------------------------------------------------------------------+
> +| frequency                    | System line frequency configuration (50Hz/60Hz).                 |

Probably should call this one `mains_frequency`.

> ++------------------------------+------------------------------------------------------------------+
> +| scale                        | Shared PGA gain setting (1x, 2x, 4x) affecting all channels.     |

scale is already listed above. Does this mean that there are 2 scale
values that have to be applied to convert raw to processed?

> ++------------------------------+------------------------------------------------------------------+
> +| filter_type                  | Waveform buffer filter type (sinc4, sinc4+lp).                   |
> ++------------------------------+------------------------------------------------------------------+
> +| filter_type_available        | Available filter types for waveform buffer.                      |
> ++------------------------------+------------------------------------------------------------------+
> +