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

[Jonathan Cameron <jic23@kernel.org>]

On Mon, 8 Sep 2025 07:35:25 +0000
Antoniu Miclaus <antoniu.miclaus@analog.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@analog.com>
Please test your docs build and carefully look at the output.
There were a few formatting errors in here that I have fixed up.

Jonathan



> +
> ++---------------------------------------------------+----------------------------------------------------------+
> +| 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:

blank line before bulleted list.

> +- ``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:

blank line before bulleted list.

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