Re: [PATCH v2 6/6] staging: iio: ad9832: add sysfs documentation

[Jonathan Cameron <jic23@kernel.org>]

On Tue, 30 Dec 2025 17:34:59 -0300
Tomas Borquez <tomasborquez13@gmail.com> wrote:

> Add sysfs ABI documentation for the AD9832/AD9835 Direct Digital
> Synthesizer chips, documenting frequency, phase, output control,
> and pin control attributes.
> 
> Signed-off-by: Tomas Borquez <tomasborquez13@gmail.com>
Hi Tomas,

Good docs, one entry of which reminded me we tend to use powerdown for
output devices rather than _en (for enable)

Jonathan

> ---
>  .../iio/Documentation/sysfs-bus-iio-frequency | 40 +++++++++++++++++++
>  1 file changed, 40 insertions(+)
>  create mode 100644 drivers/staging/iio/Documentation/sysfs-bus-iio-frequency
> 
> diff --git a/drivers/staging/iio/Documentation/sysfs-bus-iio-frequency b/drivers/staging/iio/Documentation/sysfs-bus-iio-frequency
> new file mode 100644
> index 000000000000..10627c19bdb7
> --- /dev/null
> +++ b/drivers/staging/iio/Documentation/sysfs-bus-iio-frequency
> @@ -0,0 +1,40 @@
> +What:		/sys/bus/iio/devices/iio:deviceX/out_altcurrentY_frequencyZ
> +KernelVersion:	6.19
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +    Frequency in Hz for symbol Z of channel Y. The active
> +    frequency symbol is selected via out_altcurrentY_frequency_symbol.
> +
> +What:		/sys/bus/iio/devices/iio:deviceX/out_altcurrentY_phaseZ
> +KernelVersion:	6.19
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +    Phase offset in radians for symbol Z of channel Y. Valid range
> +    is 0 to 2*PI (exclusive). The active phase symbol is selected
> +    via out_altcurrentY_phase_symbol.
> +
> +What:		/sys/bus/iio/devices/iio:deviceX/out_altcurrentY_frequency_symbol
> +KernelVersion:	6.19
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +    Selects which frequency symbol is active for channel Y.
> +
> +What:		/sys/bus/iio/devices/iio:deviceX/out_altcurrentY_phase_symbol
> +KernelVersion:	6.19
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +    Selects which phase symbol is active for channel Y.
> +
> +What:		/sys/bus/iio/devices/iio:deviceX/out_altcurrentY_enable

Ah. I probably led you astray on this in an earlier review. Would be _en
and added to the standard docs in sysfs-bus-iio in the block that starts with in_energyY_en

However, I think that might not be the right attribute to use based on this
being more similar to a DAC channel than those which are about enabling internal
accumulators. For a DAC the common terminology is about powerdown  (so effectively !enable).
That lines up with the use of SLEEP here on the datasheet.

So I think this should be out_altcurrentY_powerdown and documented in the block
with out_altvoltageY_powerdown in sysfs-bus-iio with a tweak to make the descriptive
text cover currents as well as voltages.

Obviously remember to flip the sense of the control though.

> +KernelVersion:	6.19
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +    Enables (1) or disables (0) the output for channel Y.
> +
> +What:		/sys/bus/iio/devices/iio:deviceX/out_altcurrentY_pincontrol_en
> +KernelVersion:	6.19
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +    Enables (1) or disables (0) hardware pin control for frequency
> +    and phase symbol selection on channel Y. When enabled, external
> +    pins control symbol selection instead of software.