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

[Rodrigo Alencar]

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?)

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

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.

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

With all the above, still using altvoltage is not incorrect, just a matter on how
we want to express the units. 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.

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

-- 
Kind regards,

Rodrigo Alencar