Message-ID: <20251219164751.000071a1@huawei.com>
Date: Fri, 19 Dec 2025 16:47:51 +0000
From: Jonathan Cameron <jonathan.cameron@...wei.com>
To: Janani Sunil <janani.sunil@...log.com>
CC: Lars-Peter Clausen <lars@...afoo.de>, Michael Hennerich
	<Michael.Hennerich@...log.com>, Alexandru Ardelean
	<alexandru.ardelean@...log.com>, Jonathan Cameron <jic23@...nel.org>, "Rob
 Herring" <robh@...nel.org>, Krzysztof Kozlowski <krzk+dt@...nel.org>, "Conor
 Dooley" <conor+dt@...nel.org>, Jonathan Corbet <corbet@....net>,
	<linux-iio@...r.kernel.org>, <devicetree@...r.kernel.org>,
	<linux-kernel@...r.kernel.org>, <linux-doc@...r.kernel.org>
Subject: Re: [PATCH 2/3] docs: iio: Add documentation for MAX22007 driver

On Fri, 19 Dec 2025 16:31:16 +0100
Janani Sunil <janani.sunil@...log.com> wrote:

> Add documentation for MAX22007 driver which describes how the user
> can access the driver using dtoverlays
> 
> Signed-off-by: Janani Sunil <janani.sunil@...log.com>

Hi Janani,

We've recently had a few comments on whether driver specific docs add value
(for particular drivers, sometimes they definitely do!).  From what I'm
seeing here, I'm not thinking this one needs a document.  Not most drivers
don't have such a file because they make use of standard ABI that is well
documented.  DT stuff always belongs in the dt-binding rather than these
files.  With both those elements gone there isn't much value to this file.
So I'd drop it.  We can easily add a file if something complex shows up
in later patches, that justifies this.

Thanks,

Jonathan

> ---
>  Documentation/iio/index.rst    |   1 +
>  Documentation/iio/max22007.rst | 145 +++++++++++++++++++++++++++++++++++++++++
>  MAINTAINERS                    |   1 +
>  3 files changed, 147 insertions(+)
> 
> diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst
> index 315ae37d6fd4..7601bc2882e7 100644
> --- a/Documentation/iio/index.rst
> +++ b/Documentation/iio/index.rst
> @@ -37,4 +37,5 @@ Industrial I/O Kernel Drivers
>     adxl345
>     bno055
>     ep93xx_adc
> +   max22007
>     opt4060
> diff --git a/Documentation/iio/max22007.rst b/Documentation/iio/max22007.rst
> new file mode 100644
> index 000000000000..e04c563f1fd0
> --- /dev/null
> +++ b/Documentation/iio/max22007.rst
> @@ -0,0 +1,145 @@
> +.. SPDX-License-Identifier: GPL-2.0-only
> +
> +===============
> +MAX22007 driver
> +===============
> +
> +Device driver for Analog Devices Inc. MAX22007 quad-channel industrial DAC.
> +The module name is ``max22007``.
> +
> +Supported devices
> +=================
> +
> +* `MAX22007 <https://www.analog.com/en/products/max22007.html>`_
> +
> +Wiring connections
> +==================
> +
> +The MAX22007 uses a standard SPI interface.
I'd not bother with this section.  Most SPI devices after all use
the standard interface, so we can document this by not documenting anything
else :)

> +
> +Device Tree Configuration
> +=========================

Anything here should be in the dt-binding. As such this section isn't useful.

> +
> +The device supports both global and per-channel configuration through device tree.
> +
> +Global Properties:
> +
> +* ``reset-gpios``: GPIO pin for hardware reset (optional, falls back to
> +  software reset if not specified)
> +* ``vdd-supply``: Low-Voltage Power Supply from +2.7V to +5.5V (optional)
> +* ``hvdd-supply``: Positive High-Voltage Power Supply from +8V to (HVSS +24V)
> +  for the Output Channels (optional)
> +* ``hvss-supply``: Negative High-Voltage Power Supply from -2V to 0V for the
> +  Output Channels (optional)
> +
> +Per-channel properties:
> +
> +* ``adi,type``: Specify the channel output type - must be either "voltage" or "current" (mandatory)
> +
> +Note: The driver operates in transparent mode (immediate register-to-output updates).
> +Channel mode is determined by the ``adi,type`` property:
> +
> +* ``adi,type = "current"``: the channel operates in current mode
> +* ``adi,type = "voltage"``: the channel operates in voltage mode
> +
> +Device attributes
> +=================
> +
> +The MAX22007 driver provides IIO DAC interfaces that vary based on the
> +configured channel mode. Each channel appears as a separate IIO device
> +attribute:
> +
> +* ``out_voltage_raw`` (voltage mode channels)
> +* ``out_current_raw`` (current mode channels)
> +* ``out_voltage_scale`` / ``out_current_scale`` (channel scaling factors)
> +* ``out_voltage_powerdown`` / ``out_current_powerdown`` (channel power control)
> +
> +The driver automatically configures the IIO channel type based on the configured
> +channel mode from device tree.
This bit feels very standard and so not in need of extra documentation.

> +
> +Power Mode Control
> +==================
> +
> +Each channel provides standard IIO ``powerdown`` attributes for runtime power
> +control:
> +
> +* Write ``1`` to power down (disable) the channel output
> +* Write ``0`` to power up (enable) the channel output
> +* Read the attribute to get the current power state (1=powered down, 0=powered up)
> +
> +This allows individual channels to be powered on/off independently for power
> +management and safety purposes.

Likewise, this is very standard.

> +
> +Usage Examples
> +==============
> +
> +Setting DAC output values:
> +
> +.. code-block:: bash
> +
> +   # Set channel 0 (voltage mode) to raw value 655 (≈2V)
> +   # Output is updated immediately in transparent mode
> +   echo 655 > /sys/bus/iio/devices/iio:deviceX/out_voltage0_raw
> +
> +   # Set channel 1 (current mode)
> +   # Output is updated immediately in transparent mode
> +   echo 1024 > /sys/bus/iio/devices/iio:deviceX/out_current1_raw
> +
> +Controlling channel power modes:
> +
> +.. code-block:: bash
> +
> +   # Enable channel 0 (power up)
> +   echo 0 > /sys/bus/iio/devices/iio:deviceX/out_voltage0_powerdown
> +
> +   # Disable channel 1 (power down)
> +   echo 1 > /sys/bus/iio/devices/iio:deviceX/out_current1_powerdown
> +
> +   # Check current power state (0=powered up, 1=powered down)
> +   cat /sys/bus/iio/devices/iio:deviceX/out_voltage0_powerdown
> +
> +Reading channel values and scale factors:
> +
> +.. code-block:: bash
> +
> +   # Read raw DAC value
> +   cat /sys/bus/iio/devices/iio:deviceX/out_voltage0_raw
> +
> +   # Read scale factor (volts per LSB)
> +   cat /sys/bus/iio/devices/iio:deviceX/out_voltage0_scale
> +
> +Check available channels:
> +
> +.. code-block:: bash
> +
> +   ls /sys/bus/iio/devices/iio:deviceX/out_*_raw
> +
> +Scale Calculations
> +==================
> +
> +The driver provides accurate scale factors based on the hardware configuration:

This information doesn't need to be provided explicitly.  Anyone who
wonders in detail about it can check the driver. For most users the fact
it obeys the standard ABI rules is eough.

> +
> +**Voltage Mode:**
> +
> +- Scale = (5 × 2.5V) / 4096 = 0.003051757 V per LSB
> +- Range: 0V to 12.5V over 12-bit (0-4095)
> +- Formula: Output = Raw_Value × Scale
> +
> +**Current Mode:**
> +
> +- Scale = (2.5V / (2 × 50Ω)) / 4096 = 0.000006103515625 A per LSB
> +- Range: 0A to 0.025A over 12-bit (0-4095)
> +- Formula: Output = Raw_Value × Scale
> +
> +Driver Architecture
> +===================
> +
> +The driver implements:
> +
> +* **CRC8 Error Checking**: Always-enabled CRC8 for SPI data integrity
> +* **Channel Configuration**: Supports per-channel mode and power configuration
> +
> +Channel configuration (voltage/current mode) is set via the ``adi,type``
> +device tree property and cannot be changed dynamically The driver requires
> +proper device tree configuration with mandatory ``adi,type`` property for each
> +channel.
> diff --git a/MAINTAINERS b/MAINTAINERS
> index e1addbd21562..6561455732c9 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -1599,6 +1599,7 @@ L:	linux-iio@...r.kernel.org
>  S:	Supported
>  W:	https://ez.analog.com/linux-software-drivers
>  F:	Documentation/devicetree/bindings/iio/dac/adi,max22007.yaml
> +F:	Documentation/iio/max22007.rst
>  
>  ANALOG DEVICES INC ADA4250 DRIVER
>  M:	Antoniu Miclaus <antoniu.miclaus@...log.com>
> 

Powered by blists - more mailing lists