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/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 = <®_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@xxxxxxxxxxx> + (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
