Re: [PATCH RFC v4 09/10] Documentation: ABI: testing: add docs for ad9910 sysfs entries

[Jonathan Cameron]

On Mon, 18 May 2026 16:27:23 +0100
Rodrigo Alencar <455.rodrigo.alencar@xxxxxxxxx> wrote:

> On 26/05/18 02:45PM, Jonathan Cameron wrote:
> > On Sun, 17 May 2026 18:30:27 +0100
> > Rodrigo Alencar <455.rodrigo.alencar@xxxxxxxxx> wrote:
> >   
> > > On 26/05/17 03:58PM, Jonathan Cameron wrote:  
> > > > On Fri, 08 May 2026 18:00:25 +0100
> > > > Rodrigo Alencar via B4 Relay <devnull+rodrigo.alencar.analog.com@xxxxxxxxxx> wrote:
> > > >     
> > > > > From: Rodrigo Alencar <rodrigo.alencar@xxxxxxxxxx>
> > > > > 
> > > > > Add custom ABI documentation file for the DDS AD9910 with sysfs entries to
> > > > > control Parallel Port, Digital Ramp Generator and OSK parameters.
> > > > > 
> > > > > Signed-off-by: Rodrigo Alencar <rodrigo.alencar@xxxxxxxxxx>    
> > > > I'm fine with phase and frequency as defined, but for the scaling it made me wonder.
> > > > For outvoltage0 channels the assumption the value is the peak voltage so if
> > > > we know what input to be modulated by the ramp generator can we express them
> > > > in volts (well milivolts) rather than as a scaling multiplier?    
> > > 
> > > The DAC output is current-based and differential. Voltage conversion would happen
> > > outside the device...  
> > 
> > Why aren't we representing this as out_altcurrentX-Y_xxxx?  
> 
> Good point! altcurrent makes more sense than altvoltage if we want to use raw to
> control the output level rather than scale, which would be a constant to convert
> raw into current units (what is the one that is used in the sysfs ABI? Ampere, mA or uA?)

Same as non alternating version so mA (which is a historical design error we have
long been stuck with :()  The altvoltageY_raw docs don't give a unit either.
If you don't mind, please send a patch adding that whilst you are here.
Same mid to peak - hopefully that is what any users not modifying to RMS have
been doing!

Seems we either never had one or that particular bit of ABI doc is missing.
Please add an entry for altcurrentX_raw

> 
> Not sure about the benefits on setting "differential" in channel spec.. the name would
> become out_altcurrentX-altcurrentY_xxxxx...

Becomes a question of whether it is useful to represent that - maybe not
in this particular case.

> 
> Is there any modifier for amplitude/peak/envelope? I see IIO_MOD_RMS, which could be used
> if adding a 1/sqrt(2) factor to the fixed scale.

For altcurrent / altvoltage assumption is it's mid to peak.  Unless the modifier switches
it to RMS as you've noted.

> 
> Then, I would consider something like out_altcurrent_rms_xxxx as a good alternative.
> 
> "scale" would be a constant in the top-level phy channel
> 
> single tone profile channels would have:
> - frequency
> - phase
> - raw
> 
> drg ramp up/down channels:
> - frequency and frequency_roc
> - phase and phase_roc
> - raw and raw_roc
> 
> parallel port channel(s):
> - frequency_scale and frequency_offset (frequency destination)
> - phase_offset (polar destination)
> - offset (polar destination)
> 
> osk channel:
> - raw
> - raw_roc
> 
> raw_roc could be just roc, but that sounds like it carries the scale and refers to
> a current value? and maybe that breaks consistency with other destination attributes?
> I am fine with just roc if that refers to the raw value, not (raw * scale).

This is a good question.  We ran into ambiguity with events where we have to derive
if it is _raw or _processed for the thresholds based on whether the main attribute
is _raw or _processed.  Nice to avoid doing that again.

I'd be interesting in others views on this but to me raw_roc seems fine.

> 
> With all the above, still using altvoltage is not incorrect, just a matter on how
> we want to express the units.

Agreed - but to get to directly useable values we'd need to provide info on the
external circuit - and given we are dealing with AC signals that is tricky to do
in a compact way.


> Note that using raw instead of scale to control the
> amplitude is just another option to tackle the problem. I suppose that the
> important thing here is being technically corrent and consistent in terms of
> usage. Maybe out_altcurrent_rms_* is more clear in terms of amplitude level.

Agreed.  It is always (?) possible to switch between scale and raw.
For an ADC the distinction is clear as we can't control _raw. For a DAC it all gets
rather value as we can logically control both and for an AC type of DAC / DDS it
all gets less intuitive.  As you say, consistency is key.

I'd like us to at least be consistent across DDS devices. Perhaps we need some
general documentation on whatever the outcome of this discussion is to record
some of the logic behind those decisions.

> 
> > 
> >   
> > > using a resistor load or an op-amp transimpedance stage,
> > > and I am no expert on that, but that often requires impedance matching so voltage
> > > levels may depend on the frequency. Then, I suppose that voltage is not the right
> > > unit to use.  
> > 
> > Understood that it can get complex!  
> > > 
> > > The scale here controls the amplitude of the varying signal. Assuming the peak voltage
> > > (amplitude) is constant means we have a constant envelope, but that should not mean
> > > we can't control it or it should not mean that the hardware can have other ways to
> > > control it. That said, scale behaves as a "gain multiplier".  
> > Understood. Given it's the envelope then if scale happened to be 1 always it would
> > be presented as _processed. So this is consistent with other channel types.
> >   
> > >   
> > > > 
> > > > That seems to me like it fits better with the overall ABI.
> > > >     
> > > > > +What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_scale_offset
> > > > > +KernelVersion:
> > > > > +Contact:	linux-iio@xxxxxxxxxxxxxxx
> > > > > +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 a result with the sum of this value.
> > > > > +    
> > > >     
> > > > > +
> > > > > +What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_scale_roc    
> > > > 
> > > > Silly question perhaps but can work out how this related to millivolts/sec
> > > > That might make a more intuitive interface than scaling multiplier per sec
> > > > Perhaps the combination with offset makes this impossible though maybe that
> > > > could be a expressed as a voltage offset?  Afterall if the amplitude being
> > > > scaled is 5V then 5 * (offset + scale) = 5 * offset + 5 * scale
> > > >      
> > > > > +KernelVersion:
> > > > > +Contact:	linux-iio@xxxxxxxxxxxxxxx
> > > > > +Description:
> > > > > +		Amplitude scale rate of change in 1/s for channels that ramp
> > > > > +		amplitude. This value may be influenced by the channel's
> > > > > +		sampling_frequency setting.    
> > > > 
> > > >     
> > >   
> >   
>