Re: [PATCH v6 16/16] docs: iio: add documentation for ad9910 driver

[Jonathan Cameron <jic23@kernel.org>]

On Thu, 18 Jun 2026 14:27:32 +0100
Rodrigo Alencar via B4 Relay <devnull+rodrigo.alencar.analog.com@kernel.org> wrote:

> From: Rodrigo Alencar <rodrigo.alencar@analog.com>
> 
> Add documentation for the AD9910 DDS IIO driver, which describes channels,
> DDS modes, attributes and ABI usage examples.
> 
> Signed-off-by: Rodrigo Alencar <rodrigo.alencar@analog.com>
> ---
>  Documentation/iio/ad9910.rst | 759 +++++++++++++++++++++++++++++++++++++++++++
>  Documentation/iio/index.rst  |   1 +
>  MAINTAINERS                  |   1 +
>  3 files changed, 761 insertions(+)
> 
> diff --git a/Documentation/iio/ad9910.rst b/Documentation/iio/ad9910.rst
> new file mode 100644
> index 000000000000..113521fead3e
> --- /dev/null
> +Single Tone mode
> +----------------
> +
> +Single tone is the baseline operating mode. The ``profileY`` channels
> +provide enable, frequency, phase and amplitude control:
> +
> +.. flat-table::
> +   :header-rows: 1
> +
> +   * - Attribute
> +     - Unit
> +     - Description
> +
> +   * - ``en``
> +     - boolean (0 or 1)
> +     - Enable/disable profile Y. Only one profile can be active at a
> +       time. When enabling a profile it disables the current active profile.
> +       Disabling an active profile brings the device to a powered down state.
> +
> +   * - ``frequency``
> +     - Hz
> +     - Output frequency. Range :math:`[0, f_{SYSCLK}/2)`. Stored in the

Probably spaces around the / for consistency.

> +       profile's frequency tuning word (FTW).
> +
> +   * - ``phase``
> +     - rad
> +     - Phase offset. Range :math:`[0, 2\pi)`. Stored in the profile's phase
> +       offset word (POW).
> +
> +   * - ``raw``
> +     - integer
> +     - Amplitude scale factor code. Range :math:`[0, 16383]`. Stored in the
> +       profile's amplitude scale factor (ASF) register. The physical output
> +       amplitude is ``raw * scale`` where ``scale`` is read from the ``phy``
> +       channel.

...

> +Digital ramp generator (DRG)
> +----------------------------
> +
> +The DRG produces linear frequency, phase or amplitude sweeps using dedicated
> +hardware. The active ramp target (destination) is selected by enabling the
> +corresponding typed channel at channel number 130:
> +
> +- ``out_frequency130`` (label ``drg_frequency``) — ramp targets frequency
> +- ``out_phase130`` (label ``drg_phase``) — ramp targets phase
> +- ``out_altcurrent130`` (label ``drg_amplitude``) — ramp targets amplitude
> +
> +Writing ``en=1`` to one of these channels enables the DRG and switches its
> +destination. Writing ``en=0`` disables the DRG if the channel is the current
> +active destination; writing to an already-inactive destination is a no-op.
> +
> +Each destination channel also exposes a read-only ``scale`` attribute
> +reporting the physical quantity per ramp register LSB, which allows converting
> +raw limit codes to physical values.
> +
> +The two ramp channels ``out_altcurrent131`` (``drg_rising``) and
> +``out_altcurrent132`` (``drg_falling``) configure ascending and descending
> +ramp parameters independently.
> +
> +Destination channel attributes
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +.. flat-table::
> +   :header-rows: 1
> +
> +   * - Attribute
> +     - Unit
> +     - Description
> +
> +   * - ``en``
> +     - boolean
> +     - Enable the DRG with this channel as the active destination. Only one
> +       destination can be active at a time.
> +
> +   * - ``scale``
> +     - Hz/LSB, rad/LSB or mA/LSB
> +     - Read-only. Physical quantity per raw units. Multiply a ramp
> +       rising/falling channel ``raw`` value by this scale to get the physical
> +       ramp target.
> +
> +Ramp channel attributes
> +^^^^^^^^^^^^^^^^^^^^^^^
> +
> +.. flat-table::
> +   :header-rows: 1
> +
> +   * - Attribute
> +     - Unit
> +     - Description
> +
> +   * - ``dwell_en``
> +     - boolean
> +     - Enable dwell at the ramp limit. When disabled, the ramp
> +       auto-transitions at this limit without waiting for the DRCTL pin.
> +       Disabling both creates a bidirectional continuous ramp (triangular
> +       pattern). Other combinations create single-shot ramps at the DRCTL
> +       pin transition.
> +
> +   * - ``raw``
> +     - integer (64-bit)
> +     - Ramp limit expressed as a raw DRG register code in
> +       :math:`[0, 2^{32}-1]`. The physical value is ``raw * scale`` where
> +       ``scale`` is read from the active destination channel.
> +
> +   * - ``sampling_frequency``
> +     - Hz
> +     - Ramp clock rate. Controlled by an integer divider; the written value
> +       is adjusted to the nearest supported rate.
> +
> +   * - ``raw_roc``
> +     - /s
> +     - Rate of change. Number of register codes advanced per second, computed
> +       from the hardware step size and the current ramp clock. Writing
> +       requires ``sampling_frequency`` to be configured first.
> +
> +Usage examples
> +^^^^^^^^^^^^^^
> +
> +Configure a frequency sweep from 40 MHz to 60 MHz with a rate of change of
> +25 GHz/s:
> +
> +.. code-block:: bash
> +
> +  # Disable dwell on both limits for a bidirectional continuous ramp
> +  echo 0 > /sys/bus/iio/devices/iio\:device0/out_altcurrent131_dwell_en
> +  echo 0 > /sys/bus/iio/devices/iio\:device0/out_altcurrent132_dwell_en
> +
> +  # Set ramp rate at 250 MHz
> +  echo 250000000 > /sys/bus/iio/devices/iio\:device0/out_altcurrent131_sampling_frequency
> +  echo 250000000 > /sys/bus/iio/devices/iio\:device0/out_altcurrent132_sampling_frequency
> +
> +  # read the frequency scale to convert physical values to raw units
> +  cat /sys/bus/iio/devices/iio\:device0/out_frequency130_scale
> +  0.232830643650
> +
> +  # 40 MHz / 0.232830643650 = 171798692
> +  echo 171798692 > /sys/bus/iio/devices/iio\:device0/out_altcurrent131_raw
> +  # 60 MHz / 0.232830643650 = 257698038
> +  echo 257698038 > /sys/bus/iio/devices/iio\:device0/out_altcurrent132_raw

Why is this writing frequencies to altcurrent channels? Shouldn't this be the
frequency ones?

> +
> +  # 25 GHz/s / 0.232830643650 = 107374182402
> +  echo 107374182402 > /sys/bus/iio/devices/iio\:device0/out_altcurrent131_raw_roc
> +  echo 107374182402 > /sys/bus/iio/devices/iio\:device0/out_altcurrent132_raw_roc
> +
> +  # Enable the DRG with frequency as the destination
> +  echo 1 > /sys/bus/iio/devices/iio\:device0/out_frequency130_en
> +
> +RAM mode
> +--------

...



> +
> +.. code-block:: bash
> +
> +  echo 1 > /sys/bus/iio/devices/iio\:device0/out_altcurrent100_powerdown
> \ No newline at end of file
Tidy that up.

Thanks,

Jonathan