hwmon: ina3221: Add selective summation support

From: Ninad Malwade <[email protected]>

Convert the TI INA3221 bindings from the free-form text format to json-schema.

Note that the INA3221 input channels default to enabled in the chip. Unless channels are explicitly disabled in device-tree, input channels will be enabled.

Signed-off-by Thierry Reding <[email protected]>

Signed-off-by Ninad Malwade <[email protected]>

Signed-off-by Jon Hunter <[email protected]>

---
 .../devicetree/bindings/hwmon/ina3221.txt     | 54 ----------
 .../devicetree/bindings/hwmon/ti,ina3221.yaml | 98 +++++++++++++++++++
 2 files changed, 98 insertions(+), 54 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/hwmon/ina3221.txt
 create mode 100644 Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml

Documentation/devicetree/bindings/hwmon/ina3221.txt deleted +0 -54

deleted file mode 100644
index fa63b6171407..000000000000
@@ -1,54 +0,0 @@
-Texas Instruments INA3221 Device Tree Bindings
-
-1) ina3221 node
-  Required properties:
-  - compatible: Must be "ti,ina3221"
-  - reg: I2C address
-
-  Optional properties:
-  - ti,single-shot: This chip has two power modes: single-shot (chip takes one
-                    measurement and then shuts itself down) and continuous (
-                    chip takes continuous measurements). The continuous mode is
-                    more reliable and suitable for hardware monitor type device,
-                    but the single-shot mode is more power-friendly and useful
-                    for battery-powered device which cares power consumptions
-                    while still needs some measurements occasionally.
-                    If this property is present, the single-shot mode will be
-                    used, instead of the default continuous one for monitoring.
-
-  = The node contains optional child nodes for three channels =
-  = Each child node describes the information of input source =
-
-  - #address-cells: Required only if a child node is present. Must be 1.
-  - #size-cells: Required only if a child node is present. Must be 0.
-
-2) child nodes
-  Required properties:
-  - reg: Must be 0, 1 or 2, corresponding to IN1, IN2 or IN3 port of INA3221
-
-  Optional properties:
-  - label: Name of the input source
-  - shunt-resistor-micro-ohms: Shunt resistor value in micro-Ohm
-
-Example:
-
-ina3221@40 {
-	compatible = "ti,ina3221";
-	reg = <0x40>;
-	#address-cells = <1>;
-	#size-cells = <0>;
-
-	input@0 {
-		reg = <0x0>;
-		status = "disabled";
-	};
-	input@1 {
-		reg = <0x1>;
-		shunt-resistor-micro-ohms = <5000>;
-	};
-	input@2 {
-		reg = <0x2>;
-		label = "VDD_5V";
-		shunt-resistor-micro-ohms = <5000>;
-	};
-};

Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml new file +1 -0

new file mode 100644
index 000000000000..d0e64a72af5b
@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)

Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml new file +13 -0

+
+properties:
+  compatible:
+    const: ti,ina3221
+
+  reg:
+    maxItems: 1
+
+  ti,single-shot:
+    description: |
+      This chip has two power modes: single-shot (chip takes one measurement
+      and then shuts itself down) and continuous (chip takes continuous
+      measurements). The continuous mode is more reliable and suitable for

Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml new file +40 -0

+    const: 1
+
+  "#size-cells":
+    description: Required only if a child node is present.
+    const: 0
+
+patternProperties:
+  "^input@[0-2]$":
+    description: The node contains optional child nodes for three channels.
+      Each child node describes the information of input source. Input channels
+      default to enabled in the chip. Unless channels are explicitly disabled
+      in device-tree, input channels will be enabled.
+    type: object
+    additionalProperties: false
+    properties:
+      reg:
+        description: Must be 0, 1 and 2, corresponding to the IN1, IN2 or IN3
+          ports of the INA3221, respectively.
+        enum: [ 0, 1, 2 ]
+
+      label:
+        description: name of the input source
+
+      shunt-resistor-micro-ohms:
+        description: shunt resistor value in micro-Ohm
+
+    required:
+      - reg
+
+required:
+  - compatible
+  - reg
+
+additionalProperties: false
+
+examples:
+  - |
+    i2c {
+        #address-cells = <1>;
+        #size-cells = <0>;

Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml new file +14 -0

+            };
+
+            input@1 {
+                reg = <0x1>;
+                shunt-resistor-micro-ohms = <5000>;
+            };
+
+            input@2 {
+                reg = <0x2>;
+                label = "VDD_5V";
+                shunt-resistor-micro-ohms = <5000>;
+            };
+        };
+    };

Signature · 1 line

2.34.1

Quoted 18 lines · Jon Hunter

From: Ninad Malwade <[email protected]>

Convert the TI INA3221 bindings from the free-form text format to json-schema.

Note that the INA3221 input channels default to enabled in the chip. Unless channels are explicitly disabled in device-tree, input channels will be enabled.

Signed-off-by Thierry Reding <[email protected]>

Signed-off-by Ninad Malwade <[email protected]>

Signed-off-by Jon Hunter <[email protected]>

---
  .../devicetree/bindings/hwmon/ina3221.txt     | 54 ----------
  .../devicetree/bindings/hwmon/ti,ina3221.yaml | 98 +++++++++++++++++++
  2 files changed, 98 insertions(+), 54 deletions(-)

delete mode 100644 Documentation/devicetree/bindings/hwmon/ina3221.txt create mode 100644 Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml

Quoted 9 lines

Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml new file +9 -0

+examples:
+  - |
+    i2c {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        power-sensor@40 {
+            compatible = "ti,ina3221";
+            reg = <0x40>;

Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml line 84

Quoted 6 lines

Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml new file +6 -0

+            #address-cells = <1>;
+            #size-cells = <0>;
+
+            input@0 {
+                reg = <0x0>;
+                status = "disabled";

Examples should be enabled.

Quoted 19 lines · Rob Herring

Quoted 18 lines · Jon Hunter

From: Ninad Malwade <[email protected]>

Convert the TI INA3221 bindings from the free-form text format to json-schema.

Note that the INA3221 input channels default to enabled in the chip. Unless channels are explicitly disabled in device-tree, input channels will be enabled.

Signed-off-by Thierry Reding <[email protected]>

Signed-off-by Ninad Malwade <[email protected]>

Signed-off-by Jon Hunter <[email protected]>

---
  .../devicetree/bindings/hwmon/ina3221.txt     | 54 ----------
  .../devicetree/bindings/hwmon/ti,ina3221.yaml | 98 +++++++++++++++++++
  2 files changed, 98 insertions(+), 54 deletions(-)

delete mode 100644 Documentation/devicetree/bindings/hwmon/ina3221.txt create mode 100644 Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml

...

Quoted 9 lines

Quoted 9 lines

Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml new file +9 -0

+examples:
+  - |
+    i2c {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        power-sensor@40 {
+            compatible = "ti,ina3221";
+            reg = <0x40>;

Quoted 8 lines

Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml line 84

Quoted 6 lines

Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml new file +6 -0

+            #address-cells = <1>;
+            #size-cells = <0>;
+
+            input@0 {
+                reg = <0x0>;
+                status = "disabled";

Examples should be enabled.

Yes normally that would be the case. However, per the discussion with Guenter and the comment in the changelog, for this device channels are enabled in the chip by default. And so to disable them, we need to explicitly disable in device-tree.

Quoted 45 lines · Jon Hunter

Quoted 19 lines · Rob Herring

Quoted 18 lines · Jon Hunter

From: Ninad Malwade <[email protected]>

Convert the TI INA3221 bindings from the free-form text format to json-schema.

Note that the INA3221 input channels default to enabled in the chip. Unless channels are explicitly disabled in device-tree, input channels will be enabled.

Signed-off-by Thierry Reding <[email protected]>

Signed-off-by Ninad Malwade <[email protected]>

Signed-off-by Jon Hunter <[email protected]>

---
   .../devicetree/bindings/hwmon/ina3221.txt     | 54 ----------
   .../devicetree/bindings/hwmon/ti,ina3221.yaml | 98 +++++++++++++++++++
   2 files changed, 98 insertions(+), 54 deletions(-)

delete mode 100644 Documentation/devicetree/bindings/hwmon/ina3221.txt create mode 100644 Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml

...

Quoted 17 lines

Quoted 5 lines

Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml new file +5 -0

+examples:
+  - |
+    i2c {
+        #address-cells = <1>;
+        #size-cells = <0>;

Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml line 84

Quoted 10 lines

Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml new file +10 -0

+
+        power-sensor@40 {
+            compatible = "ti,ina3221";
+            reg = <0x40>;
+            #address-cells = <1>;
+            #size-cells = <0>;
+
+            input@0 {
+                reg = <0x0>;
+                status = "disabled";

Examples should be enabled.

Quoted 4 lines

Yes normally that would be the case. However, per the discussion with Guenter and the comment in the changelog, for this device channels are enabled in the chip by default. And so to disable them, we need to explicitly disable in device-tree.

Maybe a comment at this location would be good then, to point out that this is what you are trying to demonstrate with this example?

The INA3221 has a critical alert pin that can be controlled by the summation control function. This function adds the single shunt-voltage conversions for the desired channels in order to compare the combined sum to the programmed limit. The Shunt-Voltage Sum Limit register contains the programmed value that is compared to the value in the Shunt-Voltage Sum register in order to determine if the total summed limit is exceeded. If the shunt-voltage sum limit value is exceeded, the critical alert pin pulls low.

For the summation limit to have a meaningful value, it is necessary to use the same shunt-resistor value on all included channels. Add a new vendor specific property, 'ti,summation-disable', to allow specific channels to be excluded from the summation control function if the shunt resistor is different to other channels or the channel should not be considered for triggering the critical alert pin.

Quoted 10 lines · Jon Hunter

The INA3221 has a critical alert pin that can be controlled by the summation control function. This function adds the single shunt-voltage conversions for the desired channels in order to compare the combined sum to the programmed limit. The Shunt-Voltage Sum Limit register contains the programmed value that is compared to the value in the Shunt-Voltage Sum register in order to determine if the total summed limit is exceeded. If the shunt-voltage sum limit value is exceeded, the critical alert pin pulls low.

Quoted 6 lines

For the summation limit to have a meaningful value, it is necessary to use the same shunt-resistor value on all included channels. Add a new vendor specific property, 'ti,summation-disable', to allow specific channels to be excluded from the summation control function if the shunt resistor is different to other channels or the channel should not be considered for triggering the critical alert pin.

You are adding this feature to the driver, but requiring a new property to disable it. So what happens with an existing user (old DT) and a kernel with the new feature?