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

[Rodrigo Alencar]

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@xxxxxxxxxx> wrote:
> 
> > From: Rodrigo Alencar <rodrigo.alencar@xxxxxxxxxx>
> > 
> > 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@xxxxxxxxxx>
> > ---

...

> > +What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_profile
> > +KernelVersion:
> > +Contact:	linux-iio@xxxxxxxxxxxxxxx
> > +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"

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

...

> > +What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_destination
> > +KernelVersion:
> > +Contact:	linux-iio@xxxxxxxxxxxxxxx
> > +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.

...

> > +What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_operating_mode
> > +KernelVersion:
> > +Contact:	linux-iio@xxxxxxxxxxxxxxx
> > +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.

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

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

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

...

-- 
Kind regards,

Rodrigo Alencar