diff mbox series

[v4,4/5] dt-bindings: input: Add docs for ADC driven joystick.

Message ID 20200307211412.44148-4-contact@artur-rojek.eu (mailing list archive)
State Superseded
Headers show
Series [v4,1/5] IIO: Ingenic JZ47xx: Add xlate cb to retrieve correct channel idx | expand

Commit Message

Artur Rojek March 7, 2020, 9:14 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

 v3: no change

 v4: - remove "bindings" from the unique identifier string,
     - replace `|` with `>` for all description properties,
     - specify the number of items for `io-channels`,
     - correct the regex pattern of `axis` property,
     - specify the value range of `reg` property for each axis,
     - put `abs-range` properties under `allOf` 

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

Comments

Rob Herring (Arm) March 9, 2020, 8:38 p.m. UTC | #1
On Sat,  7 Mar 2020 22:14:11 +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
> 
>  v3: no change
> 
>  v4: - remove "bindings" from the unique identifier string,
>      - replace `|` with `>` for all description properties,
>      - specify the number of items for `io-channels`,
>      - correct the regex pattern of `axis` property,
>      - specify the value range of `reg` property for each axis,
>      - put `abs-range` properties under `allOf` 
> 
>  .../bindings/input/adc-joystick.yaml          | 121 ++++++++++++++++++
>  1 file changed, 121 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/input/adc-joystick.yaml
> 

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

Error: Documentation/devicetree/bindings/input/adc-joystick.example.dts:22.31-32 syntax error
FATAL ERROR: Unable to parse input tree
scripts/Makefile.lib:311: 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:1262: recipe for target 'dt_binding_check' failed
make: *** [dt_binding_check] Error 2

See https://patchwork.ozlabs.org/patch/1250951
Please check and re-submit.
Artur Rojek March 9, 2020, 9:41 p.m. UTC | #2
Hi Rob,

On 2020-03-09 21:38, Rob Herring wrote:
> On Sat,  7 Mar 2020 22:14:11 +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
>> 
>>  v3: no change
>> 
>>  v4: - remove "bindings" from the unique identifier string,
>>      - replace `|` with `>` for all description properties,
>>      - specify the number of items for `io-channels`,
>>      - correct the regex pattern of `axis` property,
>>      - specify the value range of `reg` property for each axis,
>>      - put `abs-range` properties under `allOf`
>> 
>>  .../bindings/input/adc-joystick.yaml          | 121 
>> ++++++++++++++++++
>>  1 file changed, 121 insertions(+)
>>  create mode 100644 
>> Documentation/devicetree/bindings/input/adc-joystick.yaml
>> 
> 
> My bot found errors running 'make dt_binding_check' on your patch:
Like with the previous versions of this patch set, the DTS example 
requires that
patch [2/5] is applied first. When that is done, the DT check does 
succeed here.

Regards,
Artur
> 
> Error:
> Documentation/devicetree/bindings/input/adc-joystick.example.dts:22.31-32
> syntax error
> FATAL ERROR: Unable to parse input tree
> scripts/Makefile.lib:311: 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:1262: recipe for target 'dt_binding_check' failed
> make: *** [dt_binding_check] Error 2
> 
> See https://patchwork.ozlabs.org/patch/1250951
> Please check and re-submit.
Jonathan Cameron March 15, 2020, 9:28 a.m. UTC | #3
On Mon, 09 Mar 2020 22:41:00 +0100
Artur Rojek <contact@artur-rojek.eu> wrote:

> Hi Rob,
> 
> On 2020-03-09 21:38, Rob Herring wrote:
> > On Sat,  7 Mar 2020 22:14:11 +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
> >> 
> >>  v3: no change
> >> 
> >>  v4: - remove "bindings" from the unique identifier string,
> >>      - replace `|` with `>` for all description properties,
> >>      - specify the number of items for `io-channels`,
> >>      - correct the regex pattern of `axis` property,
> >>      - specify the value range of `reg` property for each axis,
> >>      - put `abs-range` properties under `allOf`
> >> 
> >>  .../bindings/input/adc-joystick.yaml          | 121 
> >> ++++++++++++++++++
> >>  1 file changed, 121 insertions(+)
> >>  create mode 100644 
> >> Documentation/devicetree/bindings/input/adc-joystick.yaml
> >>   
> > 
> > My bot found errors running 'make dt_binding_check' on your patch:  
> Like with the previous versions of this patch set, the DTS example 
> requires that
> patch [2/5] is applied first. When that is done, the DT check does 
> succeed here.

Fair enough as far as I am concerned.   There were enough comments
from Rob in the previous version though that I'd definitely like
him to take another look before I pick this series up.

Thanks,

Jonathan

> 
> Regards,
> Artur
> > 
> > Error:
> > Documentation/devicetree/bindings/input/adc-joystick.example.dts:22.31-32
> > syntax error
> > FATAL ERROR: Unable to parse input tree
> > scripts/Makefile.lib:311: 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:1262: recipe for target 'dt_binding_check' failed
> > make: *** [dt_binding_check] Error 2
> > 
> > See https://patchwork.ozlabs.org/patch/1250951
> > Please check and re-submit.
Rob Herring March 20, 2020, 12:15 a.m. UTC | #4
On Sat, Mar 7, 2020 at 2:06 PM Artur Rojek <contact@artur-rojek.eu> 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
>
>  v3: no change
>
>  v4: - remove "bindings" from the unique identifier string,
>      - replace `|` with `>` for all description properties,
>      - specify the number of items for `io-channels`,
>      - correct the regex pattern of `axis` property,
>      - specify the value range of `reg` property for each axis,
>      - put `abs-range` properties under `allOf`
>
>  .../bindings/input/adc-joystick.yaml          | 121 ++++++++++++++++++
>  1 file changed, 121 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..b0d2aa28d8c6
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/input/adc-joystick.yaml
> @@ -0,0 +1,121 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> +# Copyright 2019-2020 Artur Rojek
> +%YAML 1.2
> +---
> +$id: "http://devicetree.org/schemas/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:
> +    minItems: 1
> +    maxItems: 1024
> +    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]+$":

unit-addresses are hex, so add 'a-f' in there.

With that,

Reviewed-by: Rob Herring <robh@kernel.org>
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/input/adc-joystick.yaml b/Documentation/devicetree/bindings/input/adc-joystick.yaml
new file mode 100644
index 000000000000..b0d2aa28d8c6
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/adc-joystick.yaml
@@ -0,0 +1,121 @@ 
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2019-2020 Artur Rojek
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/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:
+    minItems: 1
+    maxItems: 1024
+    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:
+        minimum: 0
+        maximum: 1023
+        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:
+        allOf:
+          - $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>;
+      };
+    };