Re: [PATCH RFC v4 10/10] docs: iio: add documentation for ad9910 driver

[Jonathan Cameron <jic23@kernel.org>]

On Mon, 11 May 2026 10:23:35 -0500
David Lechner <dlechner@baylibre.com> wrote:

> On 5/11/26 10:02 AM, Rodrigo Alencar wrote:
> > On 26/05/11 09:46AM, David Lechner wrote:  
> >> On 5/10/26 4:30 AM, Rodrigo Alencar wrote:  
> >>> On 26/05/09 06:42PM, David Lechner wrote:  
> >>>> On 5/8/26 12:00 PM, Rodrigo Alencar via B4 Relay 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.  
> >>>
> >>> ...
> >>>  
> >>>>> +       must be a power of 2.
> >>>>> +
> >>>>> +   * - ``frequency_offset``
> >>>>> +     - Hz
> >>>>> +     - Base FTW to which scaled parallel data is added. Range :math:`[0, f_{SYSCLK}/2)`.
> >>>>> +
> >>>>> +   * - ``phase_offset``
> >>>>> +     - rad
> >>>>> +     - Base phase for polar modulation. Lower 8 bits of POW register.
> >>>>> +       Range :math:`[0, 2\pi/256)`.
> >>>>> +
> >>>>> +   * - ``scale_offset``
> >>>>> +     - fractional
> >>>>> +     - Base amplitude for polar modulation. Lower 6 bits of ASF register.
> >>>>> +       Range :math:`[0, 1/256)`.
> >>>>> +  
> >>>>
> >>>> I guess there was some discussion on these attributes. I see some of these in the
> >>>> ad9832 driver in staging, but I'm guessing they are new ABI. It isn't clear to
> >>>> me from the documentation here what they actually do though. I guess they are
> >>>> just basic transformations on the input signal?  
> >>>
> >>> Not sure how the ABI is not clear:
> >>>
> >>> 	For a channel that allows amplitude control through buffers, this
> >>> 	represents the value for a base amplitude scale. The actual output
> >>> 	amplitude scale is a result with the sum of this value.
> >>>
> >>> So yes, it is a basic transformation.  
> >>
> >> I didn't have time to read the ABI docs yet. For scale_offset though,
> >> how is that different from the existing offset attribute?  
> > 
> > I suppose that existing offset ABI is applied to (raw * scale), mostly for
> > voltage channels, here the scale_offset is an offset to the scale itself.  
> 
> 
> Ah, so a very general case would be (raw * (scale + scale_offset)) + offset
> 
> when the scale can change as a function of time and comes from an external
> source.
Ah. Similar question to what I was commenting on.  Though maths is currently wrong
for normal offset application as it is pre scale.


	(raw + offset) * scale is normal case.
This is proposing (I think)

	(raw + offset) * (scale_offset + scale)

Altvoltages are a little odd though in that we are really always kind of dealing
in scales as it's the peak voltage that is the base unit. So they are kind
of always about scale - hence for such a single offset would be shifting the
mid voltage point which I guess is different form scale_offset.

Hmm. Not sure I can draw this but i'll give it a go...

So with no modulation going on and scale = 2.0, Raw 1000. 
(imagine these are sign waves)

  _         _       _ 2V
 / \       / \
/___\_____/___\___  _ 0V
     \   /     \
      \_/       \__ _ -2V

That is sine wave -2/2V swing.

Now if scale or voltage double it get twice as big.

If offset + 100

  _         _       _ 3V
 / \       / \
/   \     /   \   
_____\___/_____\___ _ 0v
      \_/       \__ _ -1V

Scale offset at this point seems straight forward.. Gets more fun when it's modulated.

For now apply a scale offset of -1 and scale becomes 2 - 1 == 1. 
  _         _       _ 1.5V
 / \       / \
/   \     /   \   
_____\___/_____\___ _ 0v
      \_/       \__ _ -0.5V

So for simple case we could just role it into scale. However the fun here
I believe is that _scale is controlled by say a ramp generator.. 

Ok. I can't really draw this.. Lets try with xs

Initial scale 1, ramping to 2 over a couple 1ish cycles, offset 1.  That is
computed sale is going from 2 to 3.
                   Peak 3
____________________________ 3V
    Peak 2.33         xx
______x_______________xx____ 2V 
     xxx             x  x
   xx   x            x
 xx      x          x
x_________x_________x_______ 0V   
           x       x 
            x      x
             x    x
______________x__x__________ -2V            
_______________xx___________ -2.5
                Peak 2.67

Key being really where this starts which is scale_offset = 1 rather than starting
ramp from scale of 0.

Having drawn these I'm even less clear in my head on whether we can move from
expressing that scale_offset and scale_roc in volts  - i.e. not as scales
or not.

Given need for separate control for overall mid point of waveform and the
starting point of scaling I think not.  Ah well.  The challenge will be
how to makes sure folk looking at the ABI can understand the complex
interactions of all these parameters. We may need some extra docs with
better diagrams than above.
              
Jonathan