[v2,4/5] dt-bindings: input: Add docs for ADC driven joystick.
diff mbox series

Message ID 20200126161236.63631-4-contact@artur-rojek.eu
State Superseded
Headers show
Series
  • [v2,1/5] IIO: Ingenic JZ47xx: Add xlate cb to retrieve correct channel idx
Related show

Commit Message

Artur Rojek Jan. 26, 2020, 4:12 p.m. UTC
Add documentation for the adc-joystick driver, used to provide support
for joysticks connected over ADC.

Signed-off-by: Artur Rojek <contact@artur-rojek.eu>
Tested-by: Paul Cercueil <paul@crapouillou.net>
---

 Changes:

 v2: - Add `reg` property to axis subnode in order to enumerate the axes,
     - rename `linux,abs-code` property to `linux,code`,
     - drop `linux,` prefix from the remaining properties of axis subnode

 .../bindings/input/adc-joystick.yaml          | 117 ++++++++++++++++++
 1 file changed, 117 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/input/adc-joystick.yaml

Comments

Rob Herring Jan. 27, 2020, 2:26 p.m. UTC | #1
On Sun, 26 Jan 2020 17:12:35 +0100, Artur Rojek wrote:
> Add documentation for the adc-joystick driver, used to provide support
> for joysticks connected over ADC.
> 
> Signed-off-by: Artur Rojek <contact@artur-rojek.eu>
> Tested-by: Paul Cercueil <paul@crapouillou.net>
> ---
> 
>  Changes:
> 
>  v2: - Add `reg` property to axis subnode in order to enumerate the axes,
>      - rename `linux,abs-code` property to `linux,code`,
>      - drop `linux,` prefix from the remaining properties of axis subnode
> 
>  .../bindings/input/adc-joystick.yaml          | 117 ++++++++++++++++++
>  1 file changed, 117 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/input/adc-joystick.yaml
> 

My bot found errors running 'make dt_binding_check' on your patch:

Documentation/devicetree/bindings/display/simple-framebuffer.example.dts:21.16-37.11: Warning (chosen_node_is_root): /example-0/chosen: chosen node must be at root node
Error: Documentation/devicetree/bindings/input/adc-joystick.example.dts:22.31-32 syntax error
FATAL ERROR: Unable to parse input tree
scripts/Makefile.lib:300: recipe for target 'Documentation/devicetree/bindings/input/adc-joystick.example.dt.yaml' failed
make[1]: *** [Documentation/devicetree/bindings/input/adc-joystick.example.dt.yaml] Error 1
Makefile:1263: recipe for target 'dt_binding_check' failed
make: *** [dt_binding_check] Error 2

See https://patchwork.ozlabs.org/patch/1229387
Please check and re-submit.
Heiko Stübner March 1, 2020, 12:07 p.m. UTC | #2
Hi,

Am Sonntag, 26. Januar 2020, 17:12:35 CET schrieb Artur Rojek:
> Add documentation for the adc-joystick driver, used to provide support
> for joysticks connected over ADC.
> 
> Signed-off-by: Artur Rojek <contact@artur-rojek.eu>
> Tested-by: Paul Cercueil <paul@crapouillou.net>

this seems to be stuck for a month now.
And it would be really cool to get this landed, as the Odroid Go Advance
also profits a lot from it ;-)

As for the reported syntax error due to the missing header, maybe you
can just replace the constants in the example with numbers, as they don't
really matter for the example anyway - maybe that will make everyone
happy ;-) .

E.g. on the Go Advance the joystick is just connected to two generic
saradc channels.


Thanks
Heiko

> ---
> 
>  Changes:
> 
>  v2: - Add `reg` property to axis subnode in order to enumerate the axes,
>      - rename `linux,abs-code` property to `linux,code`,
>      - drop `linux,` prefix from the remaining properties of axis subnode
> 
>  .../bindings/input/adc-joystick.yaml          | 117 ++++++++++++++++++
>  1 file changed, 117 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/input/adc-joystick.yaml
> 
> diff --git a/Documentation/devicetree/bindings/input/adc-joystick.yaml b/Documentation/devicetree/bindings/input/adc-joystick.yaml
> new file mode 100644
> index 000000000000..91fc87dcbddb
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/input/adc-joystick.yaml
> @@ -0,0 +1,117 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> +# Copyright 2019-2020 Artur Rojek
> +%YAML 1.2
> +---
> +$id: "http://devicetree.org/schemas/bindings/input/adc-joystick.yaml#"
> +$schema: "http://devicetree.org/meta-schemas/core.yaml#"
> +
> +title: ADC attached joystick
> +
> +maintainers:
> +  - Artur Rojek <contact@artur-rojek.eu>
> +
> +description: |
> +  Bindings for joystick devices connected to ADC controllers supporting
> +  the Industrial I/O subsystem.
> +
> +properties:
> +  compatible:
> +    const: adc-joystick
> +
> +  io-channels:
> +    description: |
> +      List of phandle and IIO specifier pairs.
> +      Each pair defines one ADC channel to which a joystick axis is connected.
> +      See Documentation/devicetree/bindings/iio/iio-bindings.txt for details.
> +
> +  '#address-cells':
> +    const: 1
> +
> +  '#size-cells':
> +    const: 0
> +
> +required:
> +  - compatible
> +  - io-channels
> +  - '#address-cells'
> +  - '#size-cells'
> +
> +additionalProperties: false
> +
> +patternProperties:
> +  "^axis@([0-9])$":
> +    type: object
> +    description: |
> +      Represents a joystick axis bound to the given ADC channel.
> +      For each entry in the io-channels list, one axis subnode with a matching
> +      reg property must be specified.
> +
> +    properties:
> +      reg:
> +        items:
> +          description: Index of an io-channels list entry bound to this axis.
> +
> +      linux,code:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description: EV_ABS specific event code generated by the axis.
> +
> +      abs-range:
> +        $ref: /schemas/types.yaml#/definitions/uint32-array
> +        items:
> +          - description: minimum value
> +          - description: maximum value
> +        description: |
> +          Minimum and maximum values produced by the axis.
> +          For an ABS_X axis this will be the left-most and right-most
> +          inclination of the joystick. If min > max, it is left to userspace to
> +          treat the axis as inverted.
> +          This property is interpreted as two signed 32 bit values.
> +
> +      abs-fuzz:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description: |
> +          Amount of noise in the input value.
> +          Omitting this property indicates the axis is precise.
> +
> +      abs-flat:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description: |
> +          Axial "deadzone", or area around the center position, where the axis
> +          is considered to be at rest.
> +          Omitting this property indicates the axis always returns to exactly
> +          the center position.
> +
> +    required:
> +      - reg
> +      - linux,code
> +      - abs-range
> +
> +    additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/iio/adc/ingenic,adc.h>
> +    #include <dt-bindings/input/input.h>
> +
> +    joystick: adc-joystick {
> +      compatible = "adc-joystick";
> +      io-channels = <&adc INGENIC_ADC_TOUCH_XP>,
> +                    <&adc INGENIC_ADC_TOUCH_YP>;
> +      #address-cells = <1>;
> +      #size-cells = <0>;
> +
> +      axis@0 {
> +              reg = <0>;
> +              linux,code = <ABS_X>;
> +              abs-range = <3300 0>;
> +              abs-fuzz = <4>;
> +              abs-flat = <200>;
> +      };
> +      axis@1 {
> +              reg = <1>;
> +              linux,code = <ABS_Y>;
> +              abs-range = <0 3300>;
> +              abs-fuzz = <4>;
> +              abs-flat = <200>;
> +      };
> +    };
>

Patch
diff mbox series

diff --git a/Documentation/devicetree/bindings/input/adc-joystick.yaml b/Documentation/devicetree/bindings/input/adc-joystick.yaml
new file mode 100644
index 000000000000..91fc87dcbddb
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/adc-joystick.yaml
@@ -0,0 +1,117 @@ 
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2019-2020 Artur Rojek
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/bindings/input/adc-joystick.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: ADC attached joystick
+
+maintainers:
+  - Artur Rojek <contact@artur-rojek.eu>
+
+description: |
+  Bindings for joystick devices connected to ADC controllers supporting
+  the Industrial I/O subsystem.
+
+properties:
+  compatible:
+    const: adc-joystick
+
+  io-channels:
+    description: |
+      List of phandle and IIO specifier pairs.
+      Each pair defines one ADC channel to which a joystick axis is connected.
+      See Documentation/devicetree/bindings/iio/iio-bindings.txt for details.
+
+  '#address-cells':
+    const: 1
+
+  '#size-cells':
+    const: 0
+
+required:
+  - compatible
+  - io-channels
+  - '#address-cells'
+  - '#size-cells'
+
+additionalProperties: false
+
+patternProperties:
+  "^axis@([0-9])$":
+    type: object
+    description: |
+      Represents a joystick axis bound to the given ADC channel.
+      For each entry in the io-channels list, one axis subnode with a matching
+      reg property must be specified.
+
+    properties:
+      reg:
+        items:
+          description: Index of an io-channels list entry bound to this axis.
+
+      linux,code:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description: EV_ABS specific event code generated by the axis.
+
+      abs-range:
+        $ref: /schemas/types.yaml#/definitions/uint32-array
+        items:
+          - description: minimum value
+          - description: maximum value
+        description: |
+          Minimum and maximum values produced by the axis.
+          For an ABS_X axis this will be the left-most and right-most
+          inclination of the joystick. If min > max, it is left to userspace to
+          treat the axis as inverted.
+          This property is interpreted as two signed 32 bit values.
+
+      abs-fuzz:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description: |
+          Amount of noise in the input value.
+          Omitting this property indicates the axis is precise.
+
+      abs-flat:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description: |
+          Axial "deadzone", or area around the center position, where the axis
+          is considered to be at rest.
+          Omitting this property indicates the axis always returns to exactly
+          the center position.
+
+    required:
+      - reg
+      - linux,code
+      - abs-range
+
+    additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/iio/adc/ingenic,adc.h>
+    #include <dt-bindings/input/input.h>
+
+    joystick: adc-joystick {
+      compatible = "adc-joystick";
+      io-channels = <&adc INGENIC_ADC_TOUCH_XP>,
+                    <&adc INGENIC_ADC_TOUCH_YP>;
+      #address-cells = <1>;
+      #size-cells = <0>;
+
+      axis@0 {
+              reg = <0>;
+              linux,code = <ABS_X>;
+              abs-range = <3300 0>;
+              abs-fuzz = <4>;
+              abs-flat = <200>;
+      };
+      axis@1 {
+              reg = <1>;
+              linux,code = <ABS_Y>;
+              abs-range = <0 3300>;
+              abs-fuzz = <4>;
+              abs-flat = <200>;
+      };
+    };