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

[Jonathan Cameron <jic23@kernel.org>]

On Mon, 23 Mar 2026 11:58:53 +0000
Rodrigo Alencar <455.rodrigo.alencar@gmail.com> wrote:

> 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@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>  
> 
> ...
> 
> > > +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.
Yes. I'm thinking it would be something along those lines. 

I think the tone and RAM profiles end up with totally different controls
so this should make it clear they aren't related.

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

In the ABI docs discussion I raised the question on whether it makes more
sense to push this 'meta data' into the firmware image.  Depends a bit
on how costly loading the image is vs just updating this properties and whether
there are significant real use cases where tweaking what is run from the
image apply. I can easily conjecture some. I just have no idea if they are
real!

Thanks,

Jonathan

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