Re: [PATCH v6 16/16] docs: iio: add documentation for ad9910 driver

[Jonathan Cameron <jic23@kernel.org>]

On Mon, 6 Jul 2026 15:23:28 +0100
Rodrigo Alencar <455.rodrigo.alencar@gmail.com> wrote:

> On 03/07/26 19:30, Jonathan Cameron wrote:
> > On Thu, 18 Jun 2026 14:27:32 +0100
> > Rodrigo Alencar via B4 Relay <devnull+rodrigo.alencar.analog.com@kernel.org> wrote:
> >   
> > > From: Rodrigo Alencar <rodrigo.alencar@analog.com>
> > > 
> > > Add documentation for the AD9910 DDS IIO driver, which describes channels,
> > > DDS modes, attributes and ABI usage examples.  
> 
> ...
> 
> > > +Digital ramp generator (DRG)
> > > +----------------------------
> > > +
> > > +The DRG produces linear frequency, phase or amplitude sweeps using dedicated
> > > +hardware. The active ramp target (destination) is selected by enabling the
> > > +corresponding typed channel at channel number 130:
> > > +
> > > +- ``out_frequency130`` (label ``drg_frequency``) — ramp targets frequency
> > > +- ``out_phase130`` (label ``drg_phase``) — ramp targets phase
> > > +- ``out_altcurrent130`` (label ``drg_amplitude``) — ramp targets amplitude
> > > +
> > > +Writing ``en=1`` to one of these channels enables the DRG and switches its
> > > +destination. Writing ``en=0`` disables the DRG if the channel is the current
> > > +active destination; writing to an already-inactive destination is a no-op.
> > > +
> > > +Each destination channel also exposes a read-only ``scale`` attribute
> > > +reporting the physical quantity per ramp register LSB, which allows converting
> > > +raw limit codes to physical values.
> > > +
> > > +The two ramp channels ``out_altcurrent131`` (``drg_rising``) and
> > > +``out_altcurrent132`` (``drg_falling``) configure ascending and descending
> > > +ramp parameters independently.
> > > +
> > > +Destination channel attributes
> > > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > > +
> > > +.. flat-table::
> > > +   :header-rows: 1
> > > +
> > > +   * - Attribute
> > > +     - Unit
> > > +     - Description
> > > +
> > > +   * - ``en``
> > > +     - boolean
> > > +     - Enable the DRG with this channel as the active destination. Only one
> > > +       destination can be active at a time.
> > > +
> > > +   * - ``scale``
> > > +     - Hz/LSB, rad/LSB or mA/LSB
> > > +     - Read-only. Physical quantity per raw units. Multiply a ramp
> > > +       rising/falling channel ``raw`` value by this scale to get the physical
> > > +       ramp target.
> > > +
> > > +Ramp channel attributes
> > > +^^^^^^^^^^^^^^^^^^^^^^^
> > > +
> > > +.. flat-table::
> > > +   :header-rows: 1
> > > +
> > > +   * - Attribute
> > > +     - Unit
> > > +     - Description
> > > +
> > > +   * - ``dwell_en``
> > > +     - boolean
> > > +     - Enable dwell at the ramp limit. When disabled, the ramp
> > > +       auto-transitions at this limit without waiting for the DRCTL pin.
> > > +       Disabling both creates a bidirectional continuous ramp (triangular
> > > +       pattern). Other combinations create single-shot ramps at the DRCTL
> > > +       pin transition.
> > > +
> > > +   * - ``raw``
> > > +     - integer (64-bit)
> > > +     - Ramp limit expressed as a raw DRG register code in
> > > +       :math:`[0, 2^{32}-1]`. The physical value is ``raw * scale`` where
> > > +       ``scale`` is read from the active destination channel.
> > > +
> > > +   * - ``sampling_frequency``
> > > +     - Hz
> > > +     - Ramp clock rate. Controlled by an integer divider; the written value
> > > +       is adjusted to the nearest supported rate.
> > > +
> > > +   * - ``raw_roc``
> > > +     - /s
> > > +     - Rate of change. Number of register codes advanced per second, computed
> > > +       from the hardware step size and the current ramp clock. Writing
> > > +       requires ``sampling_frequency`` to be configured first.
> > > +
> > > +Usage examples
> > > +^^^^^^^^^^^^^^
> > > +
> > > +Configure a frequency sweep from 40 MHz to 60 MHz with a rate of change of
> > > +25 GHz/s:
> > > +
> > > +.. code-block:: bash
> > > +
> > > +  # Disable dwell on both limits for a bidirectional continuous ramp
> > > +  echo 0 > /sys/bus/iio/devices/iio\:device0/out_altcurrent131_dwell_en
> > > +  echo 0 > /sys/bus/iio/devices/iio\:device0/out_altcurrent132_dwell_en
> > > +
> > > +  # Set ramp rate at 250 MHz
> > > +  echo 250000000 > /sys/bus/iio/devices/iio\:device0/out_altcurrent131_sampling_frequency
> > > +  echo 250000000 > /sys/bus/iio/devices/iio\:device0/out_altcurrent132_sampling_frequency
> > > +
> > > +  # read the frequency scale to convert physical values to raw units
> > > +  cat /sys/bus/iio/devices/iio\:device0/out_frequency130_scale
> > > +  0.232830643650
> > > +
> > > +  # 40 MHz / 0.232830643650 = 171798692
> > > +  echo 171798692 > /sys/bus/iio/devices/iio\:device0/out_altcurrent131_raw
> > > +  # 60 MHz / 0.232830643650 = 257698038
> > > +  echo 257698038 > /sys/bus/iio/devices/iio\:device0/out_altcurrent132_raw  
> > 
> > Why is this writing frequencies to altcurrent channels? Shouldn't this be the
> > frequency ones?  
> 
> All the attributes for ramp up/down channels would do the same thing in separate
> channel types: sampling_frequency, raw, raw_roc and dwell_en... do we need frequency
> and phase ones? For the DRG, right now I have:
> 
> * out_frequency130: en, scale
> * out_phase130: en, scale
> * out_altcurrent130: en: scale
> 	* out_altcurrent131: raw, raw_roc, dwell_en, sampling_frequency
> 	* out_altcurrent132: raw, raw_roc, dwell_en, sampling_frequency

Yes. I think we should have separate ones.  If later we did have a device
that was otherwise similar but had separate registers, maybe for some weird
sync sweep of frequency and magnitude then the naming would match the thing
being enabled.   I'm not that bothered if they 'overwrite' each other, as in
there is only one backend store of the value.  Also fine if you think some
caching layer would be more user friendly.

Thanks,

Jonathan

>  
> > > +
> > > +  # 25 GHz/s / 0.232830643650 = 107374182402
> > > +  echo 107374182402 > /sys/bus/iio/devices/iio\:device0/out_altcurrent131_raw_roc
> > > +  echo 107374182402 > /sys/bus/iio/devices/iio\:device0/out_altcurrent132_raw_roc
> > > +
> > > +  # Enable the DRG with frequency as the destination
> > > +  echo 1 > /sys/bus/iio/devices/iio\:device0/out_frequency130_en
> > > +  
> 
> ...
>