Skip to contentSkip to conversation

dt-bindings: input: Convert adc-keys to DT schema

PATCH In review Rob Herring 2 participants 4 messages Jun 6, 2022 – Jun 8, 2022

Subsystems (3)
lore
Share & tools
lore

Rob Herring

author maintainer
#0 lore raw

PATCH 1/1 dt-bindings: input: Convert adc-keys to DT schema

Convert the adc-keys binding to DT schema format.

---
 .../devicetree/bindings/input/adc-keys.txt    |  67 ------------
 .../devicetree/bindings/input/adc-keys.yaml   | 103 ++++++++++++++++++
 2 files changed, 103 insertions(+), 67 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/input/adc-keys.txt
 create mode 100644 Documentation/devicetree/bindings/input/adc-keys.yaml
Documentation/devicetree/bindings/input/adc-keys.txt deleted +0 -67
deleted file mode 100644
index 6c8be6a9ace2..000000000000
@@ -1,67 +0,0 @@
-ADC attached resistor ladder buttons
-------------------------------------
-
-Required properties:
- - compatible: "adc-keys"
- - io-channels: Phandle to an ADC channel
- - io-channel-names = "buttons";
- - keyup-threshold-microvolt: Voltage above or equal to which all the keys are
-			      considered up.
-
-Optional properties:
-	- poll-interval: Poll interval time in milliseconds
-	- autorepeat: Boolean, Enable auto repeat feature of Linux input
-	  subsystem.
-
-Each button (key) is represented as a sub-node of "adc-keys":
-
-Required subnode-properties:
-	- label: Descriptive name of the key.
-	- linux,code: Keycode to emit.
-	- press-threshold-microvolt: voltage above or equal to which this key is
-				     considered pressed.
-
-No two values of press-threshold-microvolt may be the same.
-All values of press-threshold-microvolt must be less than
-keyup-threshold-microvolt.
-
-Example:
-
-#include <dt-bindings/input/input.h>
-
-	adc-keys {
-		compatible = "adc-keys";
-		io-channels = <&lradc 0>;
-		io-channel-names = "buttons";
-		keyup-threshold-microvolt = <2000000>;
-
-		button-up {
-			label = "Volume Up";
-			linux,code = <KEY_VOLUMEUP>;
-			press-threshold-microvolt = <1500000>;
-		};
-
-		button-down {
-			label = "Volume Down";
-			linux,code = <KEY_VOLUMEDOWN>;
-			press-threshold-microvolt = <1000000>;
-		};
-
-		button-enter {
-			label = "Enter";
-			linux,code = <KEY_ENTER>;
-			press-threshold-microvolt = <500000>;
-		};
-	};
-
-+--------------------------------+------------------------+
-| 2.000.000 <= value             | no key pressed         |
-+--------------------------------+------------------------+
-| 1.500.000 <= value < 2.000.000 | KEY_VOLUMEUP pressed   |
-+--------------------------------+------------------------+
-| 1.000.000 <= value < 1.500.000 | KEY_VOLUMEDOWN pressed |
-+--------------------------------+------------------------+
-|   500.000 <= value < 1.000.000 | KEY_ENTER pressed      |
-+--------------------------------+------------------------+
-|              value <   500.000 | no key pressed         |
-+--------------------------------+------------------------+
Documentation/devicetree/bindings/input/adc-keys.yaml new file +103 -0

103 lines not on this page · raw message

Signature · 1 line
2.34.1
#1 lore raw
Quoted 89 lines · Rob Herring

Convert the adc-keys binding to DT schema format.

---
  .../devicetree/bindings/input/adc-keys.txt    |  67 ------------
  .../devicetree/bindings/input/adc-keys.yaml   | 103 ++++++++++++++++++
  2 files changed, 103 insertions(+), 67 deletions(-)

delete mode 100644 Documentation/devicetree/bindings/input/adc-keys.txt create mode 100644 Documentation/devicetree/bindings/input/adc-keys.yaml

Documentation/devicetree/bindings/input/adc-keys.txt deleted +0 -67
deleted file mode 100644
index 6c8be6a9ace2..000000000000
@@ -1,67 +0,0 @@
-ADC attached resistor ladder buttons
-------------------------------------
-
-Required properties:
- - compatible: "adc-keys"
- - io-channels: Phandle to an ADC channel
- - io-channel-names = "buttons";
- - keyup-threshold-microvolt: Voltage above or equal to which all the keys are
-			      considered up.
-
-Optional properties:
-	- poll-interval: Poll interval time in milliseconds
-	- autorepeat: Boolean, Enable auto repeat feature of Linux input
-	  subsystem.
-
-Each button (key) is represented as a sub-node of "adc-keys":
-
-Required subnode-properties:
-	- label: Descriptive name of the key.
-	- linux,code: Keycode to emit.
-	- press-threshold-microvolt: voltage above or equal to which this key is
-				     considered pressed.
-
-No two values of press-threshold-microvolt may be the same.
-All values of press-threshold-microvolt must be less than
-keyup-threshold-microvolt.
-
-Example:
-
-#include <dt-bindings/input/input.h>
-
-	adc-keys {
-		compatible = "adc-keys";
-		io-channels = <&lradc 0>;
-		io-channel-names = "buttons";
-		keyup-threshold-microvolt = <2000000>;
-
-		button-up {
-			label = "Volume Up";
-			linux,code = <KEY_VOLUMEUP>;
-			press-threshold-microvolt = <1500000>;
-		};
-
-		button-down {
-			label = "Volume Down";
-			linux,code = <KEY_VOLUMEDOWN>;
-			press-threshold-microvolt = <1000000>;
-		};
-
-		button-enter {
-			label = "Enter";
-			linux,code = <KEY_ENTER>;
-			press-threshold-microvolt = <500000>;
-		};
-	};
-
-+--------------------------------+------------------------+
-| 2.000.000 <= value             | no key pressed         |
-+--------------------------------+------------------------+
-| 1.500.000 <= value < 2.000.000 | KEY_VOLUMEUP pressed   |
-+--------------------------------+------------------------+
-| 1.000.000 <= value < 1.500.000 | KEY_VOLUMEDOWN pressed |
-+--------------------------------+------------------------+
-|   500.000 <= value < 1.000.000 | KEY_ENTER pressed      |
-+--------------------------------+------------------------+
-|              value <   500.000 | no key pressed         |
-+--------------------------------+------------------------+
Documentation/devicetree/bindings/input/adc-keys.yaml new file +0 -0
new file mode 100644
index 000000000000..a3a1af9550bc

Documentation/devicetree/bindings/input/adc-keys.yaml line 10

Quoted 10 lines
Documentation/devicetree/bindings/input/adc-keys.yaml new file +10 -0
@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/adc-keys.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ADC attached resistor ladder buttons
+
+maintainers:
+  - Heinrich Schuchardt <[email protected]>

Thanks for converting to yaml.

I only contributed a single patch. I am not a maintainer. Please, remove that line.

scripts/get_maintainer.pl Documentation/devicetree/bindings/input/adc-keys.txt yields Dmitry Torokhov <[email protected]> (maintainer:INPUT (KEYBOARD, MOUSE, JOYSTICK, TOUCHSCREEN)...)

It would be preferable to have a single reference point for
maintainership: file /MAINTAINERS.

Documentation/devicetree/bindings/input/adc-keys.yaml line 21

Quoted 11 lines
Documentation/devicetree/bindings/input/adc-keys.yaml new file +11 -0
+  - Alexandre Belloni <[email protected]>
+
+allOf:
+  - $ref: /schemas/input/input.yaml#
+
+properties:
+  compatible:
+    const: adc-keys
+
+  io-channels:
+    maxItems: 1

Please, add a description to each property.

Quoted 7 lines
Documentation/devicetree/bindings/input/adc-keys.yaml new file +7 -0
+
+  io-channel-names:
+    const: buttons
+
+  keyup-threshold-microvolt:
+    description:
+      Voltage above or equal to which all the keys are considered up.

Documentation/devicetree/bindings/input/adc-keys.yaml line 38

Quoted 10 lines
Documentation/devicetree/bindings/input/adc-keys.yaml new file +10 -0
+
+patternProperties:
+  '^button-':
+    type: object
+    additionalProperties: false
+    description:
+      Each button (key) is represented as a sub-node.
+
+    properties:
+      label: true

Please, add a description.

Documentation/devicetree/bindings/input/adc-keys.yaml line 42

Quoted 4 lines
Documentation/devicetree/bindings/input/adc-keys.yaml new file +4 -0
+
+      linux,code:
+        description: Keycode to emit.
+        $ref: /schemas/types.yaml#/definitions/uint32

Unfortunately usable values are only defined in include/uapi/linux/input-event-codes.h up to now. Please, consider adding that link to the description.

It is unclear to me if using values above KEY_MAX (=0x2ff) could make sense of should be forbidden by this yaml file.

For interoperability of device-trees with other operating systems we should have a yaml file defining an enum with used values and their meaning.

Documentation/devicetree/bindings/input/adc-keys.yaml line 52

Quoted 10 lines
Documentation/devicetree/bindings/input/adc-keys.yaml new file +10 -0
+
+      press-threshold-microvolt:
+        description:
+          Voltage above or equal to which this key is considered pressed. No
+          two values of press-threshold-microvolt may be the same. All values
+          of press-threshold-microvolt must be less than
+          keyup-threshold-microvolt.
+
+    required:
+      - label

Property label is not used in our the driver code. It only exists for human readability. Why is it marked as required? Stripping the labels would reduce the DT size.

Best regards

Heinrich

Quoted 51 lines
Documentation/devicetree/bindings/input/adc-keys.yaml new file +51 -0
+      - linux,code
+      - press-threshold-microvolt
+
+required:
+  - compatible
+  - io-channels
+  - io-channel-names
+  - keyup-threshold-microvolt
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/input/input.h>
+    // +--------------------------------+------------------------+
+    // | 2.000.000 <= value             | no key pressed         |
+    // +--------------------------------+------------------------+
+    // | 1.500.000 <= value < 2.000.000 | KEY_VOLUMEUP pressed   |
+    // +--------------------------------+------------------------+
+    // | 1.000.000 <= value < 1.500.000 | KEY_VOLUMEDOWN pressed |
+    // +--------------------------------+------------------------+
+    // |   500.000 <= value < 1.000.000 | KEY_ENTER pressed      |
+    // +--------------------------------+------------------------+
+    // |              value <   500.000 | no key pressed         |
+    // +--------------------------------+------------------------+
+
+    adc-keys {
+        compatible = "adc-keys";
+        io-channels = <&lradc 0>;
+        io-channel-names = "buttons";
+        keyup-threshold-microvolt = <2000000>;
+
+        button-up {
+            label = "Volume Up";
+            linux,code = <KEY_VOLUMEUP>;
+            press-threshold-microvolt = <1500000>;
+        };
+
+        button-down {
+            label = "Volume Down";
+            linux,code = <KEY_VOLUMEDOWN>;
+            press-threshold-microvolt = <1000000>;
+        };
+
+        button-enter {
+            label = "Enter";
+            linux,code = <KEY_ENTER>;
+            press-threshold-microvolt = <500000>;
+        };
+    };
+...
author maintainer
#2 lore raw
Quoted 31 lines · Heinrich Schuchardt
Quoted 17 lines · Rob Herring

Convert the adc-keys binding to DT schema format.

---
  .../devicetree/bindings/input/adc-keys.txt    |  67 ------------
  .../devicetree/bindings/input/adc-keys.yaml   | 103 ++++++++++++++++++
  2 files changed, 103 insertions(+), 67 deletions(-)

delete mode 100644 Documentation/devicetree/bindings/input/adc-keys.txt create mode 100644 Documentation/devicetree/bindings/input/adc-keys.yaml

-+--------------------------------+------------------------+

Documentation/devicetree/bindings/input/adc-keys.yaml new file +0 -0
new file mode 100644
index 000000000000..a3a1af9550bc

Documentation/devicetree/bindings/input/adc-keys.yaml line 10

Quoted 10 lines
Documentation/devicetree/bindings/input/adc-keys.yaml new file +10 -0
@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/adc-keys.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ADC attached resistor ladder buttons
+
+maintainers:
+  - Heinrich Schuchardt <[email protected]>

Thanks for converting to yaml.

Quoted 2 lines

I only contributed a single patch. I am not a maintainer. Please, remove that line.

Okay.

Quoted 4 lines

scripts/get_maintainer.pl Documentation/devicetree/bindings/input/adc-keys.txt yields Dmitry Torokhov <[email protected]> (maintainer:INPUT (KEYBOARD, MOUSE, JOYSTICK, TOUCHSCREEN)...)

The maintainer here is supposed to be someone that cares about this particular binding, not who applies patches. IOW, who would care if the binding was deleted.

Quoted 2 lines

It would be preferable to have a single reference point for
maintainership: file /MAINTAINERS.

There's 2 main reasons why it is not. MAINTAINERS doesn't work for the DT only tree we generate[1]. Second, having an entry in MAINTAINERS for bindings is not consistent. With it in the schema, I don't have to check, the tools do it for me.

Quoted 5 lines
Quoted 5 lines
Documentation/devicetree/bindings/input/adc-keys.yaml new file +5 -0
+  - Alexandre Belloni <[email protected]>
+
+allOf:
+  - $ref: /schemas/input/input.yaml#
+
Quoted 8 lines

Documentation/devicetree/bindings/input/adc-keys.yaml line 21

Quoted 6 lines
Documentation/devicetree/bindings/input/adc-keys.yaml new file +6 -0
+properties:
+  compatible:
+    const: adc-keys
+
+  io-channels:
+    maxItems: 1

Please, add a description to each property.

Common properties don't get descriptions unless there is something specific about this binding to say. What would that be?

Quoted 10 lines
Quoted 10 lines
Documentation/devicetree/bindings/input/adc-keys.yaml new file +10 -0
+  io-channel-names:
+    const: buttons
+
+  keyup-threshold-microvolt:
+    description:
+      Voltage above or equal to which all the keys are considered up.
+
+patternProperties:
+  '^button-':
+    type: object
Quoted 8 lines

Documentation/devicetree/bindings/input/adc-keys.yaml line 38

Quoted 6 lines
Documentation/devicetree/bindings/input/adc-keys.yaml new file +6 -0
+    additionalProperties: false
+    description:
+      Each button (key) is represented as a sub-node.
+
+    properties:
+      label: true

Please, add a description.

No, common property.

Quoted 7 lines

Documentation/devicetree/bindings/input/adc-keys.yaml line 42

Quoted 3 lines
Documentation/devicetree/bindings/input/adc-keys.yaml new file +3 -0
+      linux,code:
+        description: Keycode to emit.
+        $ref: /schemas/types.yaml#/definitions/uint32

Unfortunately usable values are only defined in include/uapi/linux/input-event-codes.h up to now. Please, consider adding that link to the description.

linux,code is common for lots of bindings, so really the type, description, and any common constraints need to be documented somewhere common. I'm not sure if input.yaml makes sense given that includes a bunch of other properties.

Quoted 2 lines

It is unclear to me if using values above KEY_MAX (=0x2ff) could make sense of should be forbidden by this yaml file.

Shrug. I have no idea.

Quoted 2 lines

For interoperability of device-trees with other operating systems we should have a yaml file defining an enum with used values and their meaning.

Certainly, but that's an orthogonal issue.

Quoted 6 lines
Quoted 6 lines
Documentation/devicetree/bindings/input/adc-keys.yaml new file +6 -0
+
+      press-threshold-microvolt:
+        description:
+          Voltage above or equal to which this key is considered pressed. No
+          two values of press-threshold-microvolt may be the same. All values
+          of press-threshold-microvolt must be less than
Quoted 8 lines

Documentation/devicetree/bindings/input/adc-keys.yaml line 52

Quoted 4 lines
Documentation/devicetree/bindings/input/adc-keys.yaml new file +4 -0
+          keyup-threshold-microvolt.
+
+    required:
+      - label

Property label is not used in our the driver code. It only exists for human readability. Why is it marked as required? Stripping the labels would reduce the DT size.

From the original:

Quoted 2 lines

Documentation/devicetree/bindings/input/adc-keys.yaml

Quoted 2 lines
Documentation/devicetree/bindings/input/adc-keys.yaml new file +0 -2
-Required subnode-properties:
-	- label: Descriptive name of the key.

But I'll drop it.

Rob

[1] https://git.kernel.org/pub/scm/linux/kernel/git/devicetree/devicetree-rebasing.git/tree/

#3 lore raw
Quoted 109 lines · Rob Herring
Quoted 31 lines · Heinrich Schuchardt
Quoted 17 lines · Rob Herring

Convert the adc-keys binding to DT schema format.

---
   .../devicetree/bindings/input/adc-keys.txt    |  67 ------------
   .../devicetree/bindings/input/adc-keys.yaml   | 103 ++++++++++++++++++
   2 files changed, 103 insertions(+), 67 deletions(-)

delete mode 100644 Documentation/devicetree/bindings/input/adc-keys.txt create mode 100644 Documentation/devicetree/bindings/input/adc-keys.yaml

-+--------------------------------+------------------------+

Documentation/devicetree/bindings/input/adc-keys.yaml new file +0 -0
new file mode 100644
index 000000000000..a3a1af9550bc

Documentation/devicetree/bindings/input/adc-keys.yaml line 10

Quoted 10 lines
Documentation/devicetree/bindings/input/adc-keys.yaml new file +10 -0
@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/adc-keys.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ADC attached resistor ladder buttons
+
+maintainers:
+  - Heinrich Schuchardt <[email protected]>

Thanks for converting to yaml.

Quoted 2 lines

I only contributed a single patch. I am not a maintainer. Please, remove that line.

Okay.

Quoted 4 lines

scripts/get_maintainer.pl Documentation/devicetree/bindings/input/adc-keys.txt yields Dmitry Torokhov <[email protected]> (maintainer:INPUT (KEYBOARD, MOUSE, JOYSTICK, TOUCHSCREEN)...)

The maintainer here is supposed to be someone that cares about this particular binding, not who applies patches. IOW, who would care if the binding was deleted.

Quoted 2 lines

It would be preferable to have a single reference point for
maintainership: file /MAINTAINERS.

There's 2 main reasons why it is not. MAINTAINERS doesn't work for the DT only tree we generate[1]. Second, having an entry in MAINTAINERS for bindings is not consistent. With it in the schema, I don't have to check, the tools do it for me.

Quoted 5 lines
Quoted 5 lines
Documentation/devicetree/bindings/input/adc-keys.yaml new file +5 -0
+  - Alexandre Belloni <[email protected]>
+
+allOf:
+  - $ref: /schemas/input/input.yaml#
+
Quoted 8 lines

Documentation/devicetree/bindings/input/adc-keys.yaml line 21

Quoted 6 lines
Documentation/devicetree/bindings/input/adc-keys.yaml new file +6 -0
+properties:
+  compatible:
+    const: adc-keys
+
+  io-channels:
+    maxItems: 1

Please, add a description to each property.

Common properties don't get descriptions unless there is something specific about this binding to say. What would that be?

Quoted 10 lines
Quoted 10 lines
Documentation/devicetree/bindings/input/adc-keys.yaml new file +10 -0
+  io-channel-names:
+    const: buttons
+
+  keyup-threshold-microvolt:
+    description:
+      Voltage above or equal to which all the keys are considered up.
+
+patternProperties:
+  '^button-':
+    type: object
Quoted 8 lines

Documentation/devicetree/bindings/input/adc-keys.yaml line 38

Quoted 6 lines
Documentation/devicetree/bindings/input/adc-keys.yaml new file +6 -0
+    additionalProperties: false
+    description:
+      Each button (key) is represented as a sub-node.
+
+    properties:
+      label: true

Please, add a description.

No, common property.

Quoted 7 lines

Documentation/devicetree/bindings/input/adc-keys.yaml line 42

Quoted 3 lines
Documentation/devicetree/bindings/input/adc-keys.yaml new file +3 -0
+      linux,code:
+        description: Keycode to emit.
+        $ref: /schemas/types.yaml#/definitions/uint32

Unfortunately usable values are only defined in include/uapi/linux/input-event-codes.h up to now. Please, consider adding that link to the description.

linux,code is common for lots of bindings, so really the type, description, and any common constraints need to be documented somewhere common. I'm not sure if input.yaml makes sense given that includes a bunch of other properties.

Quoted 2 lines

It is unclear to me if using values above KEY_MAX (=0x2ff) could make sense of should be forbidden by this yaml file.

Quoted 6 lines

Shrug. I have no idea.

Quoted 2 lines

For interoperability of device-trees with other operating systems we should have a yaml file defining an enum with used values and their meaning.

Certainly, but that's an orthogonal issue.

Yes, it is orthogonal.

git grep -ni keycode Documentation/devicetree/bindings/ finds 15+ documents referring to key-codes.

So this will be a worthwhile undertaking.

Best regards

Heinrich

Quoted 26 lines
Quoted 16 lines

Documentation/devicetree/bindings/input/adc-keys.yaml line 52

Quoted 11 lines
Documentation/devicetree/bindings/input/adc-keys.yaml new file +10 -0
+
+      press-threshold-microvolt:
+        description:
+          Voltage above or equal to which this key is considered pressed. No
+          two values of press-threshold-microvolt may be the same. All values
+          of press-threshold-microvolt must be less than
+          keyup-threshold-microvolt.
+
+    required:
+      - label

Property label is not used in our the driver code. It only exists for human readability. Why is it marked as required? Stripping the labels would reduce the DT size.

Quoted 4 lines

From the original:

Documentation/devicetree/bindings/input/adc-keys.yaml

Quoted 2 lines
Documentation/devicetree/bindings/input/adc-keys.yaml new file +0 -2
-Required subnode-properties:
-	- label: Descriptive name of the key.

But I'll drop it.

Rob

[1] https://git.kernel.org/pub/scm/linux/kernel/git/devicetree/devicetree-rebasing.git/tree/