[PATCH 1/2] dt-bindings: hwmon: Introduce ADS71x8

From: Tobias Sperling
Date: Fri Aug 23 2024 - 06:08:33 EST

Add documentation for the driver of ADS7128 and ADS7138 12-bit, 8-channel
analog-to-digital converters. These ADCs have a wide operating range and
a wide feature set. Communication is based on an I2C interface.
The driver provides the functionality of manually reading single channels
or sequentially reading all channels automatically.

Signed-off-by: Tobias Sperling <tobias.sperling@xxxxxxxxxxx>
---
.../devicetree/bindings/hwmon/ti,ads71x8.yaml | 85 +++++++++++
Documentation/hwmon/ads71x8.rst | 140 ++++++++++++++++++
Documentation/hwmon/index.rst | 1 +
3 files changed, 226 insertions(+)
create mode 100644 Documentation/devicetree/bindings/hwmon/ti,ads71x8.yaml
create mode 100644 Documentation/hwmon/ads71x8.rst

diff --git a/Documentation/devicetree/bindings/hwmon/ti,ads71x8.yaml b/Docu=
mentation/devicetree/bindings/hwmon/ti,ads71x8.yaml
new file mode 100644
index 000000000000..e422c4ebd207
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/ti,ads71x8.yaml
@@ -0,0 +1,85 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+
+$id: http://devicetree.org/schemas/hwmon/ti,ads71x8.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments ADS7128/ADS7138 Analog to Digital Converter (ADC)
+
+maintainers:
+ - None
+
+description: |
+ The ADS7128 is 12-Bit, 8-Channel Sampling Analog to Digital Converter (A=
DC)
+ with an I2C interface.
+
+ Datasheets:
+ https://www.ti.com/product/ADS7128
+ https://www.ti.com/product/ADS7138
+
+properties:
+ compatible:
+ enum:
+ - ti,ads7128
+ - ti,ads7138
+
+ reg:
+ maxItems: 1
+
+ avdd-supply:
+ description:
+ The regulator used as analog supply voltage as well as reference vol=
tage.
+
+ ti,mode:
+ $ref: /schemas/types.yaml#/definitions/uint8
+ description: |
+ Operation mode
+ Mode 0 - Manual mode. A channel is only sampled when the according i=
nput
+ in the sysfs is read.
+ Mode 1 - Auto mode. All channels are automatically sampled sequentia=
lly.
+ Reading an input returns the last valid sample. In this mode furth=
er
+ features like statistics and interrupts are available.
+ default: 0
+
+ ti,interval:
+ $ref: /schemas/types.yaml#/definitions/uint16
+ description: |
+ Only considered in mode 1!
+ Interval in microseconds a new sample is triggered. Is set to closes=
t
+ possible interval, see datasheet.
+ default: 1
+
+ interrupts:
+ description: |
+ Only considered in mode 1!
+ Interrupt specifier the device's ALERT pin is connected to. Level mu=
st be
+ IRQ_TYPE_LEVEL_LOW. If not configured the digital window comparator =
(DWC)
+ is not available.
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - avdd-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells =3D <1>;
+ #size-cells =3D <0>;
+
+ ads7138@10 {
+ compatible =3D "ti,ads7138";
+ reg =3D <0x10>;
+ avdd-supply =3D <&reg_stb_3v3>;
+ ti,mode =3D /bits/ 8 <1>;
+ ti,interval =3D /bits/ 16 <1000>;
+ interrupt-parent =3D <&gpio2>;
+ interrupts =3D <12 IRQ_TYPE_LEVEL_LOW>;
+ status =3D "okay";
+ };
+ };
diff --git a/Documentation/hwmon/ads71x8.rst b/Documentation/hwmon/ads71x8.=
rst
new file mode 100644
index 000000000000..383669c1f8c5
--- /dev/null
+++ b/Documentation/hwmon/ads71x8.rst
@@ -0,0 +1,140 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+Kernel driver ads71x8
+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
+
+Supported chips:
+
+ * Texas Instruments ADS7138
+
+ Prefix: 'ads7128'
+
+ Datasheet: Publicly available at the Texas Instruments website:
+ http://focus.ti.com/lit/ds/symlink/ads7128.pdf
+
+ * Texas Instruments ADS7138
+
+ Prefix: 'ads7138'
+
+ Datasheet: Publicly available at the Texas Instruments website:
+ http://focus.ti.com/lit/ds/symlink/ads7138.pdf
+
+Author: Tobias Sperling <tobias.sperling@xxxxxxxxxxx>
+ (based on ads7828 by Steve Hardy)
+
+Description
+-----------
+
+This driver implements support for the Texas Instruments ADS7128 and ADS71=
38,
+which are 8-channel 12-bit A/D converters.
+
+The chip requires an external analog supply voltage AVDD which is also use=
d as
+reference voltage. If it is missing or too low, the chip won't show up as =
I2C
+device.
+
+The driver can be run in different modes. In manual mode a new (averaged) =
sample
+is created when the according input is read.
+
+In auto mode all channels are sampled sequentially automatically. Reading =
an
+input returns the last valid sample. In this mode there are also further
+features like statistics and the possibility to trigger an interrupt if a
+voltage drops/raises below/above a specific value (DWC - Digital Window
+Comparator).
+The overall update time (after which all channels are updated) depends on =
the
+number of samples, the update interval and the amount of channels (8).
+
+ update time =3D samples * update_interval * 8
+
+There is no reliable way to identify this chip, so the driver will not sca=
n
+some addresses to try to auto-detect it. That means that you will have to
+statically declare the device in the device tree.
+
+sysfs-Interface
+---------------
+
+The following interfaces are available in all modes.
+
++----------------+----+---------------------------------------------+
+| in[0-7]_input | ro | Voltage in mV sampled at channel [0-7] |
++----------------+----+---------------------------------------------+
+| samples | rw | Number of samples used for averaging 1-128. |
+| | | Automatically set to closest power of 2. |
++----------------+----+---------------------------------------------+
+| calibrate | rw | Write any value greater than 0 to trigger |
+| | | self-calibration. Reads as 0 if finished. |
++----------------+----+---------------------------------------------+
+
+If the device is running in auto mode there are also the following interfa=
ces.
+
++------------------+----+-------------------------------------------------=
----+
+| in[0-7]_max | ro | Maximum value in mV that occurred at channel [0-=
7] |
++------------------+----+-------------------------------------------------=
----+
+| in[0-7]_min | ro | Minimal value in mV that occurred at channel [0-=
7] |
++------------------+----+-------------------------------------------------=
----+
+| update_interval | ro | Time in microseconds after which the next sample=
is |
+| | | executed. =
|
++------------------+----+-------------------------------------------------=
----+
+
+If the device is running in auto mode and the interrupt is configured also=
the
+following interfaces are added. If CONFIG_SYSFS is set in the kernel
+configuration it is also possible to poll the 'alrarms', see example below=
.
+
++--------------------+----+-----------------------------------------------=
----+
+| alarms | ro | | Contains the flags of DWC events. Once read =
it |
+| | | is reset to 0. =
|
+| | | | BIT0 equals the low event flag of channel 0.=
|
+| | | | BIT7 equals the low event flag of channel 7.=
|
+| | | | BIT8 equals the high event flag of channel 0=
. |
+| | | | BIT15 equals the high event flag of channel =
7. |
++--------------------+----+-----------------------------------------------=
----+
+| in[0-7]_max_alarm | rw | Set high threshold in mV of DWC for channel [0=
-7] |
++--------------------+----+-----------------------------------------------=
----+
+| in[0-7]_min_alarm | rw | Set low threshold in mV of DWC for channel [0-=
7] |
++--------------------+----+-----------------------------------------------=
----+
+
+Example
+-------
+
+.. code:: c
+
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <fcntl.h>
+ #include <sys/select.h>
+ #include <unistd.h>
+
+ int main(void)
+ {
+ int retval, fd;
+ fd_set exceptfds;
+ char buf[16];
+
+ fd =3D open("/sys/class/hwmon/hwmon1/alarms", O_RDONLY);
+
+ while (1) {
+
+ FD_ZERO(&exceptfds);
+ FD_SET(fd, &exceptfds);
+
+ /* Must be assigned to 'exceptional conditions'. For poll() use
+ POLLPRI. */
+ retval =3D select(fd + 1, NULL, NULL, &exceptfds, NULL);
+ if (retval =3D=3D -1)
+ perror("select()");
+ else if (retval) {
+ /* Close and reopen is required, since it's a sysfs file */
+ close(fd);
+ fd =3D open("/sys/class/hwmon/hwmon1/alarms", O_RDONLY);
+ retval =3D read(fd, buf, sizeof(buf));
+ printf("Received: %.*s\n", retval,buf);
+ }
+ }
+
+ close(fd);
+ exit(EXIT_SUCCESS);
+ }
+
+Notes
+-----
+
+TODO support for GPIOs, ADC hysteresis and counts is missing yet.
diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst
index 913c11390a45..a54df7af27ea 100644
--- a/Documentation/hwmon/index.rst
+++ b/Documentation/hwmon/index.rst
@@ -33,6 +33,7 @@ Hardware Monitoring Kernel Drivers
adm1275
adm9240
adp1050
+ ads71x8
ads7828
adt7410
adt7411
--=20
2.39.2