Re: [PATCH RFC v2 9/9] docs: iio: add documentation for ad9910 driver

[Rodrigo Alencar]

On 26/03/22 05:34PM, Jonathan Cameron wrote:
> On Wed, 18 Mar 2026 17:56:09 +0000
> Rodrigo Alencar via B4 Relay <devnull+rodrigo.alencar.analog.com@xxxxxxxxxx> wrote:
> 
> > From: Rodrigo Alencar <rodrigo.alencar@xxxxxxxxxx>
> > 
> > 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@xxxxxxxxxx>

...

> > +Channel hierarchy
> > +=================
> > +
> > +The driver exposes the following IIO output channels, each identified by a
> > +unique channel number and a human-readable label:
> > +
> > +* ``out_altvoltage100``: ``phy``: Physical output: system clock and profile control
> > +
> > +  * ``out_altvoltage110``: ``single_tone``: Single tone mode: per-profile
> > +    frequency, phase, amplitude
> > +
> > +  * ``out_altvoltage120``: ``parallel_port``: Parallel port modulation: enable
> > +    and offset/scale parameters
> > +
> > +  * ``out_altvoltage130``: ``digital_ramp_generator``: DRG control: enable,
> > +    destination, operating mode
> > +
> > +    * ``out_altvoltage131``: ``digital_ramp_up``: DRG ramp-up parameters:
> > +      limits, step sizes, ramp rate
> > +    * ``out_altvoltage132``: ``digital_ramp_down``: DRG ramp-down parameters:
> > +      limits, step sizes, ramp rate
> > +
> > +  * ``out_altvoltage140``: ``ram_control``: RAM playback: enable, destination,
> > +    operating mode, address range
> > +
> > +  * ``out_altvoltage150``: ``output_shift_keying``: OSK: enable, amplitude
> > +    scale, ramp rate, auto/manual control
> > +
> > +The ``phy`` channel is the root of the hierarchy. Changing its
> > +``sampling_frequency`` reconfigures the system clock (SYSCLK) which affects all
> > +other channels. The ``profile`` attribute on this channel selects the active
> > +hardware profile (0-7) used by the single tone and RAM channels.
> I asked out this profile thing in one of the other patches.  Key to me is
> that how we write non active profiles?  The most similar thing we've seen
> in the past has been setting other frequencies for FSK or phases for PSK or
> more mundane DC DAC output that are symbol based. (often an external signal)

Yes, not allowing to configure a non-active profile at this point.
Initially was not seeing this as a problem, but would you think different
channels for each profiles should be created? e.g.:

- out_altvoltage111 ... out_altvoltage118 for single tone profiles; and
- out_altvoltage141 .. out_altvoltage148 for RAM profiles

That would not remove the need for something like the profile attribute.

> For those we have added an additional index so we can see which symbol we
> are changing parameters for.  Here it might need to be done in the channel
> numbering. I'm not sure.
> 
> > +
> > +All mode-specific channels (parallel port, DRG, RAM, OSK) have an ``enable``
> > +attribute. The DRG and RAM channels additionally have ``destination`` and
> > +``operating_mode`` attributes that configure which DDS core parameter is
> > +modulated and how.
> 
> I wonder if we flatten things out and have separate channels for each type
> of modulation. Might lead to a more standard looking interfaces. We don't really
> have a standard path to control one type of thing feeding another, whereas
> we do have simple 'enable' interfaces.

...

> > +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
> > +
> > +   * - ``out_altvoltage140_en``
> > +     - boolean
> > +     - Enable/disable RAM playback. Toggling swaps profile registers between
> > +       single tone and RAM configurations across all 8 profiles.

...

> > +   * - ``out_altvoltage140_address_start``
> Do we need this flexibility to set the start?  We needed a length, but
> if we want different effective start can just load a different image.

There is one image being loaded into the entire RAM and each profile may choose
from wich sample it starts and ends its address ramp.
The profiles can have those address ranges to overlap or not, then I suppose
considering different images would just complicate things.

> > +     - integer
> > +     - Start address for the active profile. Range [0, 1023]. Cannot be
> > +       changed while RAM mode is enabled. If set above current end address,
> > +       end address is automatically adjusted.
> > +

...

-- 
Kind regards,

Rodrigo Alencar