Re: [PATCH 2/3] docs: iio: Add documentation for MAX22007 driver

[Janani Sunil <jan.sun97@gmail.com>]

Hi Johnathan,

Thank you for getting back to me.

On 12/19/25 17:47, Jonathan Cameron wrote:
> On Fri, 19 Dec 2025 16:31:16 +0100
> Janani Sunil <janani.sunil@analog.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@analog.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


I agree that this driver does not need a specific document. Will drop it.

>
>> ---
>>   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@vger.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@analog.com>
>>