github-mirror/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux.git synced 2026-11-07 06:17:02 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity Graph

docs: iio: add documentation for ad9910 driver

Browse Source 
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>
Signed-off-by: Jonathan Cameron <jonathan.cameron@oss.qualcomm.com>
This commit is contained in:
Rodrigo Alencar 2026-07-29 09:25:44 +01:00 committed by Jonathan Cameron
parent e5f2f69db7
commit 280d8ccc6b
3 changed files with 794 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

792
Documentation/iio/ad9910.rst Normal file
View File

@ -0,0 +1,792 @@
.. 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

1
Documentation/iio/index.rst
View File

@ -30,6 +30,7 @@ Industrial I/O Kernel Drivers
ad7606
ad7625
ad7944
ad9910
ade9000
adf41513
adis16475

1
MAINTAINERS
View File

@ -1723,6 +1723,7 @@ W: https://ez.analog.com/linux-software-drivers
F: Documentation/ABI/testing/debugfs-iio-ad9910
F: Documentation/ABI/testing/sysfs-bus-iio-frequency-ad9910
F: Documentation/devicetree/bindings/iio/frequency/adi,ad9910.yaml
F: Documentation/iio/ad9910.rst
F: drivers/iio/frequency/ad9910.c
ANALOG DEVICES INC MAX22007 DRIVER