Re: [PATCH v5 12/13] Documentation: ABI: testing: add docs for ad9910 sysfs entries

[Jonathan Cameron <jic23@kernel.org>]

On Wed, 20 May 2026 19:47:25 +0100
Rodrigo Alencar <455.rodrigo.alencar@gmail.com> wrote:

> On 26/05/17 07:37PM, Rodrigo Alencar via B4 Relay wrote:
> > From: Rodrigo Alencar <rodrigo.alencar@analog.com>
> > 
> > Add custom ABI documentation file for the DDS AD9910 with sysfs entries to
> > control Parallel Port, Digital Ramp Generator and OSK parameters.  
> 
> ...
> 
> > +What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency_offset
> > +KernelVersion:
> > +Contact:	linux-iio@vger.kernel.org
> > +Description:
> > +		For a channel that allows frequency control through buffers, this
> > +		represents the base frequency value in Hz. The actual output frequency
> > +		is derived from this offset combined with the processed buffer sample
> > +		value.
> > +
> > +What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency_scale
> > +KernelVersion:
> > +Contact:	linux-iio@vger.kernel.org
> > +Description:
> > +		For a channel that allows frequency control through buffers, this
> > +		represents the frequency modulation gain. This value multiplies the
> > +		buffer input sample value before it is added to a frequency offset.
> > +
> > +What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_phase_offset
> > +KernelVersion:
> > +Contact:	linux-iio@vger.kernel.org
> > +Description:
> > +		For a channel that allows phase control through buffers, this
> > +		represents the base phase value in radians. The actual output phase	is
> > +		derived from this offset combined with the processed buffer sample
> > +		value.
> > +
> > +What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_scale_offset
> > +KernelVersion:
> > +Contact:	linux-iio@vger.kernel.org
> > +Description:
> > +		For a channel that allows amplitude control through buffers, this
> > +		represents the value for a base amplitude scale. The actual output
> > +		amplitude scale is derived from this offset combined with the processed
> > +		buffer sample value.
> > +  
> 
> This will become just offset with altcurrent channels. I noticed we have a IIO_PHASE
> iio_chan_type, could we have a IIO_FREQUENCY too? Parallel port needs actual raw
> frequency values in that case to be written to the dma buffer.
> 
Sure to IIO_FREQUENCY.  I thought we already did but seems not!
The Phase one is a bit special given it's use in resolvers and distance sensors
but perhaps it is the right solution here.


> Then we may have buffer capable channels for the parallel port:
> 
> out_altcurrent120
> 	offset

So that's the amplitude envelope control.

> out_phase120
> 	offset

So this is the phase adjustment being controlled. 

> out_frequency120

And this is the frequency being controlled.

> 	scale
> 	offset

> 
> Problem is that the math for the actual frequency output is:
> 
> 	f_OUT = f_FTW + (f_RAW * FM)
> 
> where f_FTW is a base frequency (already scaled), FM is a
> modulation gain and f_RAW is the contribution from the parallel
> port, which is the already scaled:
> 
> 	f_RAW = RAW * f_SYSCLK / 2^32
> 	f_FTW = FTW * f_SYSCLK / 2^32
> 
> so the above becomes:
> 
> 	f_OUT = (FTW * f_SYSCLK / 2^32) + (RAW * f_SYSCLK / 2^32) * FM
> 	f_OUT = (FTW/FM + RAW) * f_SYSCLK * FM / 2^32
> 
> if I make:
> 
> 	SCALE = f_SYSCLK * FM / 2^32
> 	OFFSET = FTW/FM
> 	f_OUT = (OFFSET + RAW) * SCALE
> 
> That would work for a IIO_FREQUENCY channel type, problem is that both
> scale and offset would depend on the modulation gain (FM)... I suppose
> scale should be setting that and offset assumes it is constant to act
> only on FTW.

I'm not that concerned about the coupling - it's a bit of a useability 
issue I guess as not obvious which should be the fixed one.  Can we do
cache written values and try and compensate to get a pair that is nearest
to whatever we try to drive (in either order of setting them?)
> 
> I suppose we can keep altcurrent for other modes as phase and frequency
> can be attributes (knobs) for them. However, in parallel mode we are effectively
> pushing frequency, phase or amplitude values into the buffer.

Given that's the thing we are controlling. My Friday evening tired brain agrees
that it makes sense to use channel types rather than adjustments on something else.

I'll think some more on this.  We've never had continuous (well digital
so near continous) control of either phase or frequency before - it's just
be symbol stuff with a couple of points to set.


> 
> The polar destination is a corner case, but can be solved when both
> phase and altcurrent channels are enabled. When that happens we can
> change the scan_type with has_ext_scan_type = 1, so the 16-bit data
> bus is split between the two.
> 
For now I'll just nod at that!

> With the above, all of those *_offset and *_scale custom ABI can be dropped.
That is definitely attractive :)

Jonathan 
>