[PATCH] docs: iio: add documentation for ti-ads1015 driver

[PATCH] docs: iio: add documentation for ti-ads1015 driver

[Flaviu Nistor]

Add documentation for the ADS1015 ADC IIO driver, which describes channels,
IIO attributes, threshold events and ABI usage examples.

Signed-off-by: Flaviu Nistor <flaviu.nistor@gmail.com>
---
 Documentation/iio/index.rst      |   1 +
 Documentation/iio/ti-ads1015.rst | 129 +++++++++++++++++++++++++++++++
 2 files changed, 130 insertions(+)
 create mode 100644 Documentation/iio/ti-ads1015.rst

diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst
index d0fb32f4b80f..47ba249dae0b 100644
--- a/Documentation/iio/index.rst
+++ b/Documentation/iio/index.rst
@@ -43,3 +43,4 @@ Industrial I/O Kernel Drivers
    bno055
    ep93xx_adc
    opt4060
+   ti-ads1015
diff --git a/Documentation/iio/ti-ads1015.rst b/Documentation/iio/ti-ads1015.rst
new file mode 100644
index 000000000000..214e50c39821
--- /dev/null
+++ b/Documentation/iio/ti-ads1015.rst
@@ -0,0 +1,129 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+=====================
+TI ADS1015 ADC driver
+=====================
+
+Driver for the Texas Instruments ADS1015 and related I2C analog-to-digital
+converters. The module name is ``ads1015``.
+
+Supported devices
+=================
+
+* `ADS1015 <https://www.ti.com/product/ADS1015>`_: 12-bit ADC, programmable data rate from 128 to 3300 samples/s.
+* `ADS1115 <https://www.ti.com/product/ADS1115>`_: 16-bit ADC, programmable data rate from 8 to 860 samples/s.
+* `TLA2024 <https://www.ti.com/product/TLA2024>`_: 12-bit ADC, programmable data rate from 128 to 3300 samples/s.
+
+The ADS1015 and ADS1115 provide a comparator; the TLA2024 does not.
+
+I2C address
+===========
+
+The ADDR pin selects the 7-bit I2C address.
+For ADS1015 and ADS1115, the possible addresses are:
+
+* ``0x48``: ADDR connected to GND
+* ``0x49``: ADDR connected to VDD
+* ``0x4a``: ADDR connected to SDA
+* ``0x4b``: ADDR connected to SCL
+
+For the TLA2024, the possible addresses are:
+
+* ``0x48``: ADDR connected to GND
+* ``0x49``: ADDR connected to VDD
+* ``0x4b``: ADDR connected to SCL
+
+
+Channel configuration
+======================
+
+The driver exposes four single-ended voltage channels (AIN0 through AIN3,
+measured relative to GND) and four differential channels (AIN0-AIN1,
+AIN0-AIN3, AIN1-AIN3, and AIN2-AIN3). Device Tree child nodes configure the
+initial settings for the corresponding conversion input. They do not restrict
+which IIO channels are available.
+
+The child node ``reg`` values select the conversion input as follows:
+
++---------+------------------+
+| ``reg`` | Conversion input |
++=========+==================+
+| 0       | AIN0 - AIN1      |
++---------+------------------+
+| 1       | AIN0 - AIN3      |
++---------+------------------+
+| 2       | AIN1 - AIN3      |
++---------+------------------+
+| 3       | AIN2 - AIN3      |
++---------+------------------+
+| 4       | AIN0 - GND       |
++---------+------------------+
+| 5       | AIN1 - GND       |
++---------+------------------+
+| 6       | AIN2 - GND       |
++---------+------------------+
+| 7       | AIN3 - GND       |
++---------+------------------+
+
+``ti,gain`` selects the full-scale input range using the following index:
+
++-------+--------------------------+
+| Index | Full-scale range         |
++=======+==========================+
+| 0     | +/- 6.144 V              |
++-------+--------------------------+
+| 1     | +/- 4.096 V              |
++-------+--------------------------+
+| 2     | +/- 2.048 V (default)    |
++-------+--------------------------+
+| 3     | +/- 1.024 V              |
++-------+--------------------------+
+| 4     | +/- 0.512 V              |
++-------+--------------------------+
+| 5     | +/- 0.256 V              |
++-------+--------------------------+
+
+For a channel node that omits ``ti,gain``, the default index is 2.
+
+``ti,datarate`` selects the data rate by index. For the ADS1015 and TLA2024,
+indices 0 through 7 select 128, 250, 490, 920, 1600, 2400, 3300, and 3300
+samples/s, respectively. For the ADS1115, they select 8, 16, 32, 64, 128,
+250, 475, and 860 samples/s. For a channel node that omits
+``ti,datarate``, the default index is 4.
+
+The ``label`` property is exposed through the channel's ``in_voltageY_label``
+sysfs attribute. Without a defined label, the datasheet input name is used
+(for example, ``AIN0`` or ``AIN0-AIN1``).
+
+IIO attributes
+==============
+
+Each voltage channel provides a raw reading, a label, scale, and sampling frequency.
+The scale and sampling frequency can be changed at runtime; their available
+values are listed by ``scale_available`` and ``sampling_frequency_available``.
+
+Threshold events
+================
+
+The ADS1015 and ADS1115 can report threshold events when the ALERT/RDY pin is
+connected to an interrupt. The driver supports one active comparator channel
+at a time, and threshold events cannot be enabled while buffered capture is
+active. The TLA2024 does not support threshold events.
+
+The rising threshold value sets the upper threshold. The falling threshold
+value sets the lower threshold; enabling the ``either`` event uses both values
+in window-comparator mode. The event period selects the comparator queue
+duration, which corresponds to 1, 2, or 4 consecutive conversions at the
+channel's configured sampling frequency.
+
+Usage examples
+--------------
+
+.. code-block:: bash
+
+	root:/sys/bus/iio/devices/iio:device0# cat name
+	ads1015
+	root:/sys/bus/iio/devices/iio:device0# cat in_voltage0_label
+	AN0
+	root:/sys/bus/iio/devices/iio:device0# cat in_voltage0_raw
+	750
-- 
2.34.1