Re: [PATCH RFC v2 8/9] Documentation: ABI: testing: add docs for ad9910 sysfs entries

[Jonathan Cameron <jic23@kernel.org>]

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

> On 26/03/22 05:22PM, Jonathan Cameron wrote:
> > On Wed, 18 Mar 2026 17:56:08 +0000
> > Rodrigo Alencar via B4 Relay <devnull+rodrigo.alencar.analog.com@kernel.org> wrote:
> >   
> > > From: Rodrigo Alencar <rodrigo.alencar@analog.com>
> > > 
> > > Add ABI documentation file for the DDS AD9910 with sysfs entries to
> > > control Parallel Port, Digital Ramp Generator, RAM and OSK parameters.
> > > 
> > > Signed-off-by: Rodrigo Alencar <rodrigo.alencar@analog.com>
> > > ---  
> 
> ...
> 
> > > +What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_profile
> > > +KernelVersion:
> > > +Contact:	linux-iio@vger.kernel.org
> > > +Description:
> > > +		Read/write the active profile index [0, 7] from/to the physical
> > > +		channel. The AD9910 supports 8 profiles, each storing a complete
> > > +		set of single tone (frequency, phase, amplitude) and RAM playback
> > > +		parameters.  
> > 
> > This one is interesting.  Can we treat them as symbols that we are picking
> > between?  We have similar DAC ABIs for that already.  
> 
> The profile concept comes from the datasheet and defines sets of configuration
> for single tone and RAM control mode. I am not sure how we fit this idea into a
> "symbol"

Think of those tones as just different frequencies (the other stuff could be the same)
then this is FSK with 8 symbols.

> 
> > Is this picking between them for purposes of configuration or setting which one is
> > in being output currently?  
> 
> Well, this is being used for configuration and activating, then, yes, you can only configure
> an active profile, but I was not seeing that as an issue. I suppose that simplifies the
> ABI a bit.
If you are only configuring the one that is active, short of a small overhead
of having to configure more than one property why have this at all?

Just leave it in a profile and have userspace reconfigure everything it wants to.

However, I see that in some of them modes below this is more complex
as the profiles are cycled through - for ram playback anyway.
It may make sense to separate the ram case from tone ones.


> 
> ...
> 
> > > +What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_destination
> > > +KernelVersion:
> > > +Contact:	linux-iio@vger.kernel.org
> > > +Description:
> > > +		Read/write the digital ramp generator (DRG) or the RAM control
> > > +		destination parameter. Determines which DDS core parameter is to
> > > +		be modulated when the child mode channel is enabled.
> > > +
> > > +		Available values can be read from the corresponding
> > > +		out_altvoltageY_destination_available attribute.
> > > +
> > > +		Valid values: "polar" (only for RAM control), "frequency", "phase"
> > > +		and "amplitude"  
> > 
> > This is very device specific. Maybe we are better representing these as separate
> > channels each with their own controls for DRG.  No problem if changing one changes
> > another.  
> 
> You mean removing this generic Y there? Indeed, there are separate configs for each one.

No, I mean having more channels.  One for each of polar, frequency, phase and frequency for
each channel.  Then enables for which channel is turned on.  Might not work out,
but I'd like you to explore what problems that type of interface would bring.

The aim here is to add as little new ABI as possible as custom ABI is a real
pain for generic userspace.


> 
> ...
> 
> > > +What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_operating_mode
> > > +KernelVersion:
> > > +Contact:	linux-iio@vger.kernel.org
> > > +Description:
> > > +		Read/write the DRG or RAM control operating mode. For the DRG
> > > +		channel it controls the no-dwell behavior of the ramp.
> > > +
> > > +		Available values can be read from the corresponding
> > > +		out_altvoltageY_operating_mode_available attribute.
> > > +
> > > +		Valid values for DRG channel:
> > > +
> > > +		  - "bidirectional": Normal ramp generation (ramp up then
> > > +		    down, dwelling at limits).  
> > 
> > Some sort of trapezium wave?  Maybe this and continuous forms are combined
> > and we have a separate dwell time control?  
> 
> Yes, sort of. Dwell control is made by an external pin (DRCTL), often controlled
> by an FPGA to achieve certain required timings. I can say that software control
> is not really recommended, unless only a one-shot ramp is necessary.

So is it worth exposing this software control at all?  Maybe just make it a firmware
description problem as to whether that DRCTL is connected or not.

> 
> When adding the IIO backend support, extendend attributes will be added to
> support control of dwell times.
> 
> >   
> > > +		  - "ramp_down": No-dwell low; the ramp resets to upper
> > > +		    limit upon reaching the lower limit.
> > > +		  - "ramp_up": No-dwell high; the ramp resets to lower
> > > +		    limit upon reaching the upper limit.
> > > +		  - "bidirectional_continuous": Both no-dwell high and low;
> > > +		    the ramp continuously sweeps without dwelling.  
> > 
> > Triangle wave?  bidirectional continuous is a rather confusing term so maybe
> > we should rethink this one.  
> 
> Mostly yes, but not only that. Sawtooth can be achieved as well by changing
> the step sizes, also other weird patterns can be achieved by toggling DRCTL pin.

Sawtooth is kind of a special triangle wave with one very steep side.
Wikipedia even has: "It can also be considered the extreme case of an asymmetric triangle wave"
https://en.wikipedia.org/wiki/Sawtooth_wave

> This mode is the most useful when one does not have an FPGA and want to save
> resources on controlling the DRCTL pin. That mode name comes from the datasheet,
> so I suppose it was fine.

Let us see if we can get more opinions on this.  Whilst I can see the logic of
the datasheet naming, it's a bit obscure.

> 
> > > +
> > > +		Valid values for RAM control channel:
> > > +
> > > +		  - "direct_switch": start address defines fixed word to be used
> > > +		    by the selected profile.
> > > +		  - "ramp_up": One-shot ramp up through current profile's address
> > > +		    range.
> > > +		  - "bidirectional": Ramp up then down through PROFILE0 pin.  
> > 
> > Avoid specifics like this.  Can we call external control pin or something like that?
> >   
> > > +		  - "bidirectional_continuous": Continuous ramp up/down
> > > +		    through current profile's address range.
> > > +		  - "ramp_up_continuous": Continuous ramp up through
> > > +		    current profile's address range.  
> > 
> > I guess this goes back to start on finishing ramping up?  
> 
> Yes, any dwell time should be considered when loading the "waveform" into the RAM
> 
> >   
> > > +		  - "sequenced": Sequenced playback of RAM profiles up to
> > > +		    the active profile. Requires active profile > 0.  
> > Is this just running through each profile one after another? (other than profile 0)?  
> 
> for this, this would be the actions:
> - configure all desired profiles (0 up to X) 
> - Set the operating mode to sequenced (profile X would be active at this point)
> - Enable RAM mode
Ah. This reflects on the profile control above. As I mention there I'm not sure we
shouldn't separate the use of profile for tones (where it is symbol like) to that
for RAM addresses.

For the ram addresses I think I'd expose separate attributes for each (there aren't
that many) rather than a selector + controls.

Another option would be to push the control of this into the firmware files
(some sort of header).  Whether that is sufficient would depend on the usecases
for the device.  It would definitely make for an easier runtime configuration
though!

> 
> When RAM mode is enabled, it would trigger the execution of profiles 0 up to X,
> in sequence, according to the configured address range and sample rate for each profile.
> When one profile ends the next starts until profile X finishes.
> 
> > > +		  - "sequenced_continuous": Continuous sequenced playback
> > > +		    of RAM profiles up to the active profile. Requires
> > > +		    active profile > 0.  
> > Similar to above, maybe separate out dwell time if that's the difference between
> > sequenced and sequenced_continuous.  
> 
> The difference here is that when Profile X finishes, Profile 0 starts again.
> So the previous one is kind of an one-shot mode of multiple profiles in sequence

They had fun designing this didn't they!

Anyhow, I think we'll need to work through a few more versions of this to get
as extensible an interface as possible.

> 
> ...
>