Re: [PATCH] staging: Documentation: dds: replace frequencyY with frequency

[Jonathan Cameron <jic23@kernel.org>]

On Mon, 11 May 2026 22:42:55 +0530
Abinash Singh <abinashsinghlalotra@gmail.com> wrote:

> From: Abinash Singh <abinashlalotra@gmail.com>
> 
> The documented frequencyY attribute naming is implementation
> specific and differs from common IIO sysfs attribute
> conventions.
> 
> Replace the non-standard frequencyY attribute documentation with
> out_altvoltageX_frequency and document tuning word selection
> through out_altvoltageX_frequencysymbol
> 
> This makes the documented ABI naming consistent with standard
> IIO sysfs attribute conventions and clarifies how tuning word
> registers are selected and programmed.
> 

Hmm. So some history on why it was done like this (long time back
but I think I recall the basic argument).

Consider the programming you need to set up FSK on a channel and
the fact that someone is recieving the result.

When you set the symbol to program it that channel will begin
outputting the voltage. That means someone at the other end starts
decoding it.

Hence we normally expect to set a frequency 'before' changing the
symbol.  Hence the per symbol files.

There might be a valid way to set them up using your proposed
interface but I'm not currently understanding what it is.

We went through the same dance with the more complex DDS that
Rodrigo is working on. Take a look at the multichannel approach
he is using.  It may apply here - I'm not sure.


> 
> Signed-off-by: Abinash Singh <abinashlalotra@gmail.com>
> ---
> 
> The out_altvoltageX_frequencysymbol and
> out_altvoltageX_frequency_scale attributes can be added
> through extended channel attributes (.ext_info in channel_spec struct of IIO)
> 
> Feedback on this approach would be appreciated, and if
> there is some other way in your mind. I would like to 
> work on that.
> 
> I am also interested in working on the sysfs-bus-iio-dds
> documentation and the ad9834 driver. I recently bought an
> AD9833 IC for experimentation and testing.
> 
Excellent!

Thanks,

Jonathan

> Thanks
> 
>  .../iio/Documentation/sysfs-bus-iio-dds       | 31 ++++++++++---------
>  1 file changed, 16 insertions(+), 15 deletions(-)
> 
> diff --git a/drivers/staging/iio/Documentation/sysfs-bus-iio-dds b/drivers/staging/iio/Documentation/sysfs-bus-iio-dds
> index ee8c509c6733..dfc6ae3964d1 100644
> --- a/drivers/staging/iio/Documentation/sysfs-bus-iio-dds
> +++ b/drivers/staging/iio/Documentation/sysfs-bus-iio-dds
> @@ -1,33 +1,34 @@
>  
> -What:		/sys/bus/iio/devices/.../out_altvoltageX_frequencyY
> +What:		/sys/bus/iio/devices/.../out_altvoltageX_frequency
>  KernelVersion:	2.6.37
>  Contact:	linux-iio@vger.kernel.org
>  Description:
> -		Stores frequency into tuning word Y.
> -		There will be more than one out_altvoltageX_frequencyY file,
> -		which allows for pin controlled FSK Frequency Shift Keying
> -		(out_altvoltageX_pincontrol_frequency_en is active) or the user
> -		can control the desired active tuning word by writing Y to the
> +		Stores frequency into active tuning word register.
> +		To select active tuning word register, the user
> +		must write the desired index to the
>  		out_altvoltageX_frequencysymbol file.
> +		For pin controlled FSK (Frequency Shift Keying),
> +		tuning word registers must be loaded by selecting
> +		each via out_altvoltageX_frequencysymbol before enabling
> +		out_altvoltageX_pincontrol_frequency_en.
>  
> -What:		/sys/bus/iio/devices/.../out_altvoltageX_frequencyY_scale
> +What:		/sys/bus/iio/devices/.../out_altvoltageX_frequency_scale
>  KernelVersion:	2.6.37
>  Contact:	linux-iio@vger.kernel.org
>  Description:
> -		Scale to be applied to out_altvoltageX_frequencyY in order to
> -		obtain the desired value in Hz. If shared across all frequency
> -		registers Y is not present. It is also possible X is not present
> +		Scale to be applied to out_altvoltageX_frequency in order to
> +		obtain the desired value in Hz. It is also possible X is not present
>  		if shared across all channels.
>  
>  What:		/sys/bus/iio/devices/.../out_altvoltageX_frequencysymbol
>  KernelVersion:	2.6.37
>  Contact:	linux-iio@vger.kernel.org
>  Description:
> -		Specifies the active output frequency tuning word. The value
> -		corresponds to the Y in out_altvoltageX_frequencyY.
> -		To exit this mode the user can write
> -		out_altvoltageX_pincontrol_frequency_en or
> -		out_altvoltageX_out_enable file.
> +		Specifies the active output frequency tuning word index.
> +		Writing an index here selects which tuning word register
> +		is written by out_altvoltageX_frequency. To exit this mode
> +		the user can write out_altvoltageX_pincontrol_frequency_en
> +		or out_altvoltageX_out_enable file.
>  
>  What:		/sys/bus/iio/devices/.../out_altvoltageX_phaseY
>  KernelVersion:	2.6.37