Documentation/iio/ad9910.rst

.. SPDX-License-Identifier: GPL-2.0-only

=============
AD9910 driver
=============

Direct Digital Synthesizer (DDS) driver for the Analog Devices Inc. AD9910.
The module name is ``ad9910``.

* `AD9910 <https://www.analog.com/en/products/ad9910.html>`_

The AD9910 is a 1 GSPS DDS with a 14-bit DAC, controlled over SPI. The driver
exposes the device through a hierarchy of typed IIO output channels. The root
``phy`` channel controls the system clock and full-scale output current.
Sub-channels provide independent control over single tone profiles, parallel
port modulation, digital ramp generation (DRG), RAM playback and output shift
keying (OSK).


Channel hierarchy
=================

The driver exposes the following IIO output channels, each identified by a
unique channel number and a human-readable label. The ``phy`` channel is the
root of the hierarchy. Changing its ``sampling_frequency`` reconfigures the
system clock (SYSCLK) which affects all other channels.

.. flat-table::
   :header-rows: 1

   * - Channel
     - Label
     - Parent
     - Description

   * - ``out_altcurrent100``
     - ``phy``
     -
     - Physical output: system clock and full-scale output current (:math:`I_{FS}`).
       See `Physical channel`_.

   * - ``out_altcurrent110`` ... ``out_altcurrent117``
     - ``profile0`` ... ``profile7``
     - ``phy``
     - Single tone control: frequency, phase, amplitude, enable.
       See `Single Tone mode`_.

   * - ``out_altcurrent120``
     - ``parallel_amplitude``
     - ``phy``
     - Parallel port amplitude channel.
       See `Parallel Port mode`_.

   * - ``out_phase120``
     - ``parallel_phase``
     - ``phy``
     - Parallel port phase channel.

   * - ``out_frequency120``
     - ``parallel_frequency``
     - ``phy``
     - Parallel port frequency channel: ``scale`` sets the FM gain
       (power-of-2 multiplier), ``offset`` sets the base FTW.

   * - ``out_altcurrent121``
     - ``parallel_polar_amplitude``
     - ``phy``
     - Parallel polar amplitude channel: ``scale`` is the amplitude
       resolution, ``offset`` is the amplitude bias (lower 6 bits of ASF).

   * - ``out_phase121``
     - ``parallel_polar_phase``
     - ``phy``
     - Parallel polar phase channel: ``scale`` is the phase resolution,
       ``offset`` is the phase bias (lower 8 bits of POW).

   * - ``out_frequency130``
     - ``drg_frequency``
     - ``phy``
     - DRG frequency channel: ``en`` selects and enables the DRG with
       frequency as the ramp target.
       See `Digital ramp generator (DRG)`_.

   * - ``out_frequency131``
     - ``drg_rising_frequency``
     - ``drg_frequency``
     - DRG frequency rising-ramp parameters: limit code, dwell enable,
       ramp clock, rate of change.

   * - ``out_frequency132``
     - ``drg_falling_frequency``
     - ``drg_frequency``
     - DRG frequency falling-ramp parameters: limit code, dwell enable,
       ramp clock, rate of change.

   * - ``out_phase130``
     - ``drg_phase``
     - ``phy``
     - DRG phase channel: ``en`` selects and enables the DRG with phase
       as the ramp target.
       See `Digital ramp generator (DRG)`_.

   * - ``out_phase131``
     - ``drg_rising_phase``
     - ``drg_phase``
     - DRG phase rising-ramp parameters: limit code, dwell enable, ramp clock,
       rate of change.

   * - ``out_phase132``
     - ``drg_falling_phase``
     - ``drg_phase``
     - DRG phase falling-ramp parameters: limit code, dwell enable, ramp clock,
       rate of change.

   * - ``out_altcurrent130``
     - ``drg_amplitude``
     - ``phy``
     - DRG amplitude channel: ``en`` selects and enables the DRG with
       amplitude as the ramp target.
       See `Digital ramp generator (DRG)`_.

   * - ``out_altcurrent131``
     - ``drg_rising_amplitude``
     - ``drg_amplitude``
     - DRG amplitude rising-ramp parameters: limit code, dwell enable,
       ramp clock, rate of change.

   * - ``out_altcurrent132``
     - ``drg_falling_amplitude``
     - ``drg_amplitude``
     - DRG amplitude falling-ramp parameters: limit code, dwell enable,
       ramp clock, rate of change.

   * - ``out_altcurrent140``
     - ``ram``
     - ``phy``
     - RAM playback: enable, frequency, phase and sampling frequency for
       the active profile. See `RAM mode`_.

   * - ``out_altcurrent150``
     - ``osk``
     - ``phy``
     - Output shift keying (OSK): enable, amplitude code, ramp rate,
       rate of change. See `Output Shift Keying (OSK)`_.

DDS modes
=========

The AD9910 supports multiple modes of operation that can be configured
independently or in combination. Each DDS core parameter (frequency, phase
and amplitude) can come from different sources, but only one is active at a
time. This activation depends on a priority list, which is based on the enable
and destination configurations for such modes. The following tables are
extracted from the AD9910 datasheet and summarize the control parameters for
each mode and their priority when multiple sources are enabled simultaneously:

.. flat-table:: DDS Frequency Control
   :header-rows: 1

   * - Priority
     - Data Source
     - Conditions

   * - Highest Priority
     - RAM
     - RAM enabled and data destination is frequency

   * -
     - DRG
     - DRG enabled and data destination is frequency

   * -
     - Parallel data and Frequency Tuning Word, FTW (frequency_offset)
     - Parallel data port enabled and data destination is frequency

   * -
     - FTW register (frequency)
     - RAM enabled and data destination is not frequency

   * - Lowest Priority
     - FTW (frequency) in single tone channel for the active profile
     - All other cases

.. flat-table:: DDS Phase Control
   :header-rows: 1

   * - Priority
     - Data Source
     - Conditions

   * - Highest Priority
     - RAM
     - RAM enabled and data destination is phase or polar

   * -
     - DRG
     - DRG enabled and data destination is phase

   * -
     - Parallel data port
     - Parallel data port enabled and data destination is phase

   * -
     - Parallel data port and Phase Offset Word, POW register LSBs (phase_offset)
     - Parallel data port enabled and data destination is polar

   * -
     - POW register (phase)
     - RAM enabled and destination is not phase nor polar

   * - Lowest Priority
     - POW (phase) in single tone channel for the active profile
     - All other cases

.. flat-table:: DDS Amplitude Control
   :header-rows: 1

   * - Priority
     - Data Source
     - Conditions

   * - Highest Priority
     - Amplitude Scale Factor, ASF register and OSK generator
     - OSK enabled

   * -
     - RAM
     - RAM enabled and data destination is amplitude or polar

   * -
     - DRG
     - DRG enabled and data destination is amplitude

   * -
     - Parallel data port
     - Parallel data port enabled and data destination is amplitude

   * -
     - Parallel data port and ASF register LSBs (scale_offset)
     - Parallel data port enabled and data destination is polar

   * - Lowest Priority
     - ASF (scale) in single tone channel for the active profile
     - (Amplitude scale is already enabled by default)

While debugging or testing, the debug attributes ``frequency_source``,
``phase_source`` and ``amplitude_source`` can be used to read the label of
the channel that is actively controlling the correspondent DDS parameter,
which reflects the priority list described above.

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

Profile switching is allowed while RAM mode is enabled. In that case single
tone parameters are stored in a shadow register and are not written to
hardware until RAM mode is disabled.

Usage examples
^^^^^^^^^^^^^^

Configure a 100 MHz tone in profile 2 and set it as the active profile:

.. code-block:: bash

  echo 100000000 > /sys/bus/iio/devices/iio\:device0/out_altcurrent112_frequency
  echo 0 > /sys/bus/iio/devices/iio\:device0/out_altcurrent112_phase
  echo 16383 > /sys/bus/iio/devices/iio\:device0/out_altcurrent112_raw

  # Activate profile 2
  echo 1 > /sys/bus/iio/devices/iio\:device0/out_altcurrent112_en

Read back the current single tone frequency:

.. code-block:: bash

  cat /sys/bus/iio/devices/iio\:device0/out_altcurrent112_frequency

Parallel Port mode
------------------

The parallel port allows real-time modulation of DDS parameters through a
16-bit external data bus. The driver exposes separate typed channels for each
modulation target.

Non-polar modulation
^^^^^^^^^^^^^^^^^^^^

In non-polar mode each DDS parameter is controlled by an independent 16-bit bus
input. The parallel port channels expose the resolution and base offset of their
respective bus inputs:

.. flat-table::
   :header-rows: 1

   * - Channel
     - Attribute
     - Unit
     - Description

   * - ``out_phase120``
     - ``scale``
     - rad
     - Phase resolution per parallel bus LSB. Fixed at :math:`\pi / 2^{15}`
       rad/LSB (full 16-bit POW resolution).

   * - ``out_frequency120``
     - ``scale``
     - Hz
     - Outputs the frequency scale evaluated as
       :math:`f_{SYSCLK} \cdot FM / 2^{32}`. Assuming that :math:`f_{SYSCLK}` is
       fixed, it is used to configure the modulation gain :math:`FM`, which is a
       power-of-2 multiplier in range :math:`[1, 32768]`. Writing to this
       attribute rounds up to the nearest :math:`FM` power of 2.

   * - ``out_frequency120``
     - ``offset``
     - Hz
     - Outputs the frequency offset in raw units evaluated as :math:`FTW / FM`.
       Assuming that :math:`FM` is fixed, it is used to configure the FTW
       register, which is a 32-bit unsigned integer.

Polar modulation
^^^^^^^^^^^^^^^^

In polar mode a single 16-bit bus word carries both amplitude (high byte)
and phase (low byte). The ``parallel_polar_amplitude`` and
``parallel_polar_phase`` channels configure the bias applied to the low-order
bits of the ASF and POW registers respectively:

.. flat-table::
   :header-rows: 1

   * - Channel
     - Attribute
     - Unit
     - Description

   * - ``out_altcurrent121``
     - ``scale``
     - mA/LSB
     - Full-scale amplitude resolution (read-only, fixed at :math:`I_{FS} / 2^{8}`).

   * - ``out_altcurrent121``
     - ``offset``
     - fractional (raw units)
     - Amplitude bias. Lower 6 bits of ASF register. Range :math:`[0, 1)`.

   * - ``out_phase121``
     - ``scale``
     - rad/LSB
     - Phase resolution (read-only, fixed at :math:`\pi / 2^{7}`).

   * - ``out_phase121``
     - ``offset``
     - fractional (raw units)
     - Phase bias. Lower 8 bits of POW register. Range :math:`[0, 1)`.

Usage examples
^^^^^^^^^^^^^^

Set parallel port frequency modulation with a modulation gain of 16 and a 50 MHz
offset:

.. code-block:: bash

  # f_SYSCLK = 1 GHz, FM = 16
  # frequency scale = f_SYSCLK * FM / 2^32 = 3.725290298
  echo 3.725290298 > /sys/bus/iio/devices/iio\:device0/out_frequency120_scale
  # frequency offset = 50 MHz / scale = 50e6 / 13421772.8
  echo 13421772.8 > /sys/bus/iio/devices/iio\:device0/out_frequency120_offset

One should choose a frequency scale that allows all the desired frequencies
to be represented in the 16-bit bus range, i.e.,
:math:`scale = (f_{max} - f_{min}) / 2^{16}`.


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 six ramp channels:

- ``out_frequency131`` (label ``drg_rising_frequency``)
- ``out_frequency132`` (label ``drg_falling_frequency``)
- ``out_phase131`` (label ``drg_rising_phase``)
- ``out_phase132`` (label ``drg_falling_phase``)
- ``out_altcurrent131`` (label ``drg_rising_amplitude``)
- ``out_altcurrent132`` (label ``drg_falling_amplitude``)

configure ascending and descending ramp parameters.

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_frequency131_dwell_en
  echo 0 > /sys/bus/iio/devices/iio\:device0/out_frequency132_dwell_en

  # Set ramp rate at 250 MHz
  echo 250000000 > /sys/bus/iio/devices/iio\:device0/out_frequency131_sampling_frequency
  echo 250000000 > /sys/bus/iio/devices/iio\:device0/out_frequency132_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_frequency131_raw
  # 60 MHz / 0.232830643650 = 257698038
  echo 257698038 > /sys/bus/iio/devices/iio\:device0/out_frequency132_raw

  # 25 GHz/s / 0.232830643650 = 107374182402
  echo 107374182402 > /sys/bus/iio/devices/iio\:device0/out_frequency131_raw_roc
  echo 107374182402 > /sys/bus/iio/devices/iio\:device0/out_frequency132_raw_roc

  # Enable the DRG with frequency as the destination
  echo 1 > /sys/bus/iio/devices/iio\:device0/out_frequency130_en

RAM mode
--------

The AD9910 contains a 1024 x 32-bit RAM that can be loaded with waveform data
and played back to modulate frequency, phase, amplitude, or polar (phase +
amplitude) parameters.

RAM control channel attributes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. flat-table::
   :header-rows: 1

   * - Attribute
     - Unit
     - Description

   * - ``en``
     - boolean
     - Enable/disable RAM playback. Toggling swaps profile registers between
       single tone and RAM configurations across all 8 profiles.

   * - ``frequency``
     - Hz
     - Frequency tuning word used as the single tone frequency when
       RAM destination is not ``frequency``. Range: :math:`[0, f_{SYSCLK} / 2)`.

   * - ``phase``
     - rad
     - Phase offset word used as the single tone phase when RAM destination
       is not ``phase``. Range: :math:`[0, 2\pi)`.

   * - ``sampling_frequency``
     - Hz
     - RAM playback step rate of the active profile, which controls how fast
       the address counter advances. Controlled by an integer divider; the
       written value is adjusted to the nearest supported rate.

Loading RAM data
^^^^^^^^^^^^^^^^

RAM data is loaded through the firmware upload framework. The driver registers
a firmware upload sysfs entry named ``iio_deviceX:ram``. The firmware data
follows a binary format (version 1) with an 80-byte header followed by data
words. All fields are big-endian.

.. flat-table:: RAM firmware header (80 bytes)
   :header-rows: 1

   * - Offset
     - Size
     - Field
     - Description

   * - 0
     - 4
     - ``magic``
     - Magic number: ``0x00AD9910``

   * - 4
     - 2
     - ``version``
     - Format version: ``0x0001``

   * - 6
     - 2
     - ``wcount``
     - Number of 32-bit RAM data words (0--1024)

   * - 8
     - 4
     - ``crc``
     - CRC32 checksum over ``cfr1``, ``profiles`` and ``words``

   * - 12
     - 4
     - ``cfr1``
     - CFR1 register value. Only RAM-relevant bits are used:
       bits [30:29] set data destination (00: frequency, 01: phase,
       10: amplitude, 11: polar); bits [20:17] set internal profile
       control (see datasheet Table 14)

   * - 16
     - 64
     - ``profiles[0..7]``
     - 8 sets of 8-byte RAM profile configurations (see below)

   * - 80
     - 4 x wcount
     - ``words[]``
     - RAM data words in reverse order

Each 8-byte profile entry contains:

.. flat-table:: RAM profile entry (8 bytes)
   :header-rows: 1

   * - Bits
     - Field
     - Description

   * - [55:40]
     - Address step rate
     - Controls playback speed for this profile

   * - [39:30]
     - End address
     - Last RAM address for this profile

   * - [23:14]
     - Start address
     - First RAM address for this profile

   * - [5]
     - No-dwell high
     - No-dwell at high limit (ramp-up mode)

   * - [3]
     - Zero-crossing
     - Zero-crossing enable (direct-switch mode)

   * - [2:0]
     - Operating mode
     - 000: direct switch, 001: ramp-up, 010: bidirectional,
       011: bidirectional continuous, 100: ramp-up continuous

Usage examples
^^^^^^^^^^^^^^

Configure RAM mode with firmware data and enable it:

.. code-block:: bash

  # Load RAM data via firmware upload
  echo 1 > /sys/class/firmware/iio\:device0\:ram/loading
  cat ad9910-ram.bin > /sys/class/firmware/iio\:device0\:ram/data
  echo 0 > /sys/class/firmware/iio\:device0\:ram/loading

  # Enable RAM mode
  echo 1 > /sys/bus/iio/devices/iio\:device0/out_altcurrent140_en

Output Shift Keying (OSK)
-------------------------

OSK controls the output amplitude envelope, allowing the output to be ramped
on/off rather than switched abruptly.

.. flat-table::
   :header-rows: 1

   * - Attribute
     - Unit
     - Description

   * - ``en``
     - boolean (0 or 1)
     - Enable/disable OSK.

   * - ``raw``
     - integer
     - Target amplitude code. 14-bit ASF field. Range: :math:`[0, 16383]`.
       The physical output amplitude is ``raw * scale`` where ``scale`` is read
       from the ``phy`` channel.

   * - ``raw_roc``
     - /s
     - Amplitude ramp rate. Writing a non-zero value enables automatic OSK
       and selects the closest hardware step size. Writing ``0`` disables
       automatic ramping (manual control via ``raw``). Writing the maximum
       available value enables pin-controlled immediate transition.

   * - ``raw_roc_available``
     - /s
     - Lists the available ``raw_roc`` values based on the current
       ``sampling_frequency``. The first value is always ``0`` (disabled) and
       the last value corresponds to pin-controlled immediate mode.

   * - ``sampling_frequency``
     - Hz
     - OSK ramp clock. Controlled by an integer divider; the written value
       is adjusted to the nearest supported rate.

Usage examples
^^^^^^^^^^^^^^

Enable OSK with automatic ramping:

.. code-block:: bash

  # Set ramp rate 1MHz
  echo 1000000 > /sys/bus/iio/devices/iio\:device0/out_altcurrent150_sampling_frequency

  # Check available rate of change values
  cat /sys/bus/iio/devices/iio\:device0/out_altcurrent150_raw_roc_available
  0 1000000 2000000 4000000 8000000 16383000000

  # Enable automatic OSK with a rate of change of 8000000 raw units/s
  echo 8000000 > /sys/bus/iio/devices/iio\:device0/out_altcurrent150_raw_roc

  # Enable OSK
  echo 1 > /sys/bus/iio/devices/iio\:device0/out_altcurrent150_en

Enable pin-controlled immediate OSK:

.. code-block:: bash

  # Enable OSK in manual mode (no ramp)
  echo 0 > /sys/bus/iio/devices/iio\:device0/out_altcurrent150_raw_roc
  echo 1 > /sys/bus/iio/devices/iio\:device0/out_altcurrent150_en

  # Set target amplitude to full scale
  echo 16383 > /sys/bus/iio/devices/iio\:device0/out_altcurrent150_raw

Physical channel
================

The ``phy`` channel provides device-level control:

.. flat-table::
   :header-rows: 1

   * - Attribute
     - Unit
     - Description

   * - ``sampling_frequency``
     - Hz
     - System clock (SYSCLK) frequency. When the internal PLL is enabled
       (via the ``adi,pll-enable`` devicetree property), configures the PLL
       multiplier (Range: :math:`[420, 1000]` MHz). Without PLL, the reference
       clock can only be divided by 2.

   * - ``scale``
     - mA/LSB
     - Full-scale DAC output current per amplitude code LSB, which is evaluated
       as :math:`I_{FS} / 2^{14}`. Shared across all ``altcurrent`` channels.
       Setting this attribute reconfigures the auxiliary DAC full-scale code and
       updates the effective amplitude resolution for single tone profiles,
       DRG amplitude ramps and OSK.

   * - ``powerdown``
     - boolean (0 or 1)
     - Software power-down. Writing 1 powers down the digital core, DAC,
       reference clock input and auxiliary DAC simultaneously.

Usage examples
--------------

Set the system clock to 1 GHz:

.. code-block:: bash

  echo 1000000000 > /sys/bus/iio/devices/iio\:device0/out_altcurrent100_sampling_frequency

Read current system clock frequency:

.. code-block:: bash

  cat /sys/bus/iio/devices/iio\:device0/out_altcurrent100_sampling_frequency

Power down the device:

.. code-block:: bash

  echo 1 > /sys/bus/iio/devices/iio\:device0/out_altcurrent100_powerdown