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

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

[Abinash Singh]

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.


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.

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

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

[Andy Shevchenko]

On Mon, May 11, 2026 at 10:42:55PM +0530, Abinash Singh wrote:

> The documented frequencyY attribute naming is implementation

I'm lost here. What frequencyY? I don't see that in the patch.
I think this needs to be more specific. Can you rephrase?

> 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

Missing space?

> This makes the documented ABI naming consistent with standard
> IIO sysfs attribute conventions and clarifies how tuning word
> registers are selected and programmed.
> 
> 

(A single blank line is enough.)

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

I didn't get is the current documentation wrong or is it that currently
used ABI is wrong?

-- 
With Best Regards,
Andy Shevchenko

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

[Abinash Singh]

On Tue, May 12, 2026 at 4:45 PM Andy Shevchenko
<andriy.shevchenko@intel.com> wrote:
>
> On Mon, May 11, 2026 at 10:42:55PM +0530, Abinash Singh wrote:
>
> > The documented frequencyY attribute naming is implementation
>
> I'm lost here. What frequencyY? I don't see that in the patch.
> I think this needs to be more specific. Can you rephrase?
>
By "frequencyY", I meant the implementation-specific attribute naming
used in the documentation:
"/sys/bus/iio/devices/.../out_altvoltageX_frequencyY"
 where Y represents the tuning word register
index (for example frequency0/frequency1 corresponding to FREQ0/FREQ1
in devices like AD9834).

> > 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
>
> Missing space?
Thanks
>
> > This makes the documented ABI naming consistent with standard
> > IIO sysfs attribute conventions and clarifies how tuning word
> > registers are selected and programmed.
> >
> >
>
> (A single blank line is enough.)

acknowledged.
>
> > 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.
>
> I didn't get is the current documentation wrong or is it that currently
> used ABI is wrong?
>
The current ABI and documentation are consistent with the current driver
implementation

But it uses implementation-specific naming using "IIO_DEVICE_ATTR" ,
such as "frequency0" and "frequency1" for DDS tuning word selection.

As this was in staging. It may be because it is not aligned
with standard IIO ABI naming convention such as "out_altvoltageX_frequency"
This is what I observed. It may be incorrect.

If there are any other
reasons why this is in staging ?, I would love to work on that.

And from Jonathan's reply I realised that I was wrong about
/sys/bus/iio/devices/.../out_altvoltageX_frequencysymbol


> --
> With Best Regards,
> Andy Shevchenko
>
>
Thank You very much for your time
Abinash Singh

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

[Jonathan Cameron]

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

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

[Abinash Singh]

Hi Jonathan

On Tue, May 12, 2026 at 7:38 PM Jonathan Cameron <jic23@kernel.org> wrote:
>
> 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.

I think I misunderstood the purpose of
out_altvoltageX_frequencysymbol.

I initially thought it was used to select which tuning word register
to write into, whereas it actually selects the active output tuning
word. That explains why my proposed interface was confusing.

The ordering requirement you described for FSK setup makes sense now.
With separate frequency0/frequency1 files, userspace can configure both
tuning words before switching the active symbol.

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

With my approach we can have a new entry  /out_altvoltageX_frequencySelect
which can act as a mux to write into FREQ0 and FREQ1 register
via  /out_altvoltage_frequency.

I will take a look at Rodrigo's multichannel DDS approach before
proposing any ABI changes further. It would be helpful if you could
share links to the relevant discussion or patches.

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


And do we need to really work on this documentation in order to work on ad9834.c
What else can be done in ad9834.c apart from this naming.??

Thanks

Abinash Singh