Message-ID:
 <BE1P281MB24208CB90AF549578AA5C384EF972@BE1P281MB2420.DEUP281.PROD.OUTLOOK.COM>
Date: Fri, 30 Aug 2024 11:49:53 +0000
From: "Sperling, Tobias" <Tobias.Sperling@...ting.com>
To: "linux-kernel@...r.kernel.org" <linux-kernel@...r.kernel.org>,
	"linux-hwmon@...r.kernel.org" <linux-hwmon@...r.kernel.org>,
	"devicetree@...r.kernel.org" <devicetree@...r.kernel.org>,
	"linux-doc@...r.kernel.org" <linux-doc@...r.kernel.org>
CC: "jdelvare@...e.com" <jdelvare@...e.com>, "linux@...ck-us.net"
	<linux@...ck-us.net>, "robh@...nel.org" <robh@...nel.org>,
	"krzk+dt@...nel.org" <krzk+dt@...nel.org>, "conor+dt@...nel.org"
	<conor+dt@...nel.org>, "corbet@....net" <corbet@....net>, "Sperling, Tobias"
	<Tobias.Sperling@...ting.com>
Subject: [PATCH 1/2] dt-bindings: hwmon: Introduce ADS71x8

>From b2e04ce5500faf274654be5284be9db4f3abefce Mon Sep 17 00:00:00 2001
From: Tobias Sperling <tobias.sperling@...ting.com>
Date: Fri, 23 Aug 2024 12:08:33 +0200
Subject: [PATCH 1/2] dt-bindings: hwmon: Introduce ADS71x8

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@...ting.com>
---
 .../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/Documentation/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 (ADC)
+  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 voltage.
+
+  ti,mode:
+    $ref: /schemas/types.yaml#/definitions/uint8
+    description: |
+      Operation mode
+      Mode 0 - Manual mode. A channel is only sampled when the according input
+        in the sysfs is read.
+      Mode 1 - Auto mode. All channels are automatically sampled sequentially.
+        Reading an input returns the last valid sample. In this mode further
+        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 closest
+      possible interval, see datasheet.
+    default: 1
+
+  interrupts:
+    description: |
+      Only considered in mode 1!
+      Interrupt specifier the device's ALERT pin is connected to. Level must 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 = <1>;
+        #size-cells = <0>;
+
+        ads7138@10 {
+            compatible = "ti,ads7138";
+            reg = <0x10>;
+            avdd-supply = <&reg_stb_3v3>;
+            ti,mode = /bits/ 8 <1>;
+            ti,interval = /bits/ 16 <1000>;
+            interrupt-parent = <&gpio2>;
+            interrupts = <12 IRQ_TYPE_LEVEL_LOW>;
+            status = "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
+=====================
+
+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@...ting.com>
+	(based on ads7828 by Steve Hardy)
+
+Description
+-----------
+
+This driver implements support for the Texas Instruments ADS7128 and ADS7138,
+which are 8-channel 12-bit A/D converters.
+
+The chip requires an external analog supply voltage AVDD which is also used 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 = samples * update_interval * 8
+
+There is no reliable way to identify this chip, so the driver will not scan
+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 interfaces.
+
++------------------+----+-----------------------------------------------------+
+| 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 = 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 = select(fd + 1, NULL, NULL, &exceptfds, NULL);
+			if (retval == -1)
+				perror("select()");
+			else if (retval) {
+				/* Close and reopen is required, since it's a sysfs file */
+				close(fd);
+				fd = open("/sys/class/hwmon/hwmon1/alarms", O_RDONLY);
+				retval = 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
-- 
2.39.2

Powered by blists - more mailing lists