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>
---
 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.
+
+Device Tree Configuration
+=========================
+
+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.
+
+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.
+
+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:
+
+**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>

-- 
2.43.0

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

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

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