diff mbox series

[v3,1/2] dt-bindings: input: Goodix GT7986U SPI HID Touchscreen

Message ID 20241108120311.87795-2-charles.goodix@gmail.com
State New
Headers show
Series dt-bindings: input: Goodix GT7986U SPI HID Touchscreen | expand

Commit Message

Charles Wang Nov. 8, 2024, 12:03 p.m. UTC 
The Goodix GT7986U touch controller report touch data according to the
HID protocol through the SPI bus. However, it is incompatible with
Microsoft's HID-over-SPI protocol.

NOTE: these bindings are distinct from the bindings used with the
GT7986U when the chip is running I2C firmware. For some background,
see discussion on the mailing lists in the thread:

https://lore.kernel.org/r/20241018020815.3098263-2-charles.goodix@gmail.com

Signed-off-by: Charles Wang <charles.goodix@gmail.com>
---
 .../bindings/input/goodix,gt7986u-spifw.yaml  | 75 +++++++++++++++++++
 1 file changed, 75 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.yaml

Comments

Rob Herring (Arm) Nov. 8, 2024, 1:33 p.m. UTC | #1 
On Fri, 08 Nov 2024 20:03:10 +0800, Charles Wang wrote:
> The Goodix GT7986U touch controller report touch data according to the
> HID protocol through the SPI bus. However, it is incompatible with
> Microsoft's HID-over-SPI protocol.
> 
> NOTE: these bindings are distinct from the bindings used with the
> GT7986U when the chip is running I2C firmware. For some background,
> see discussion on the mailing lists in the thread:
> 
> https://lore.kernel.org/r/20241018020815.3098263-2-charles.goodix@gmail.com
> 
> Signed-off-by: Charles Wang <charles.goodix@gmail.com>
> ---
>  .../bindings/input/goodix,gt7986u-spifw.yaml  | 75 +++++++++++++++++++
>  1 file changed, 75 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.yaml
> 

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

yamllint warnings/errors:
./Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.yaml:16:7: [error] syntax error: mapping values are not allowed here (syntax)

dtschema/dtc warnings/errors:
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.yaml: ignoring, error parsing file
./Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.yaml:16:7: mapping values are not allowed in this context
make[2]: *** Deleting file 'Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.example.dts'
Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.yaml:16:7: mapping values are not allowed in this context
make[2]: *** [Documentation/devicetree/bindings/Makefile:26: Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.example.dts] Error 1
make[2]: *** Waiting for unfinished jobs....
make[1]: *** [/builds/robherring/dt-review-ci/linux/Makefile:1442: dt_binding_check] Error 2
make: *** [Makefile:224: __sub-make] Error 2

doc reference errors (make refcheckdocs):

See https://patchwork.ozlabs.org/project/devicetree-bindings/patch/20241108120311.87795-2-charles.goodix@gmail.com

The base for the series is generally the latest rc1. A different dependency
should be noted in *this* patch.

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure 'yamllint' is installed and dt-schema is up to
date:

pip3 install dtschema --upgrade

Please check and re-submit after running the above command yourself. Note
that DT_SCHEMA_FILES can be set to your schema file to speed up checking
your schema. However, it must be unset to test all examples with your schema.
Doug Anderson Nov. 8, 2024, 3:13 p.m. UTC | #2 
Hi,

On Fri, Nov 8, 2024 at 5:33 AM Rob Herring (Arm) <robh@kernel.org> wrote:
>
>
> On Fri, 08 Nov 2024 20:03:10 +0800, Charles Wang wrote:
> > The Goodix GT7986U touch controller report touch data according to the
> > HID protocol through the SPI bus. However, it is incompatible with
> > Microsoft's HID-over-SPI protocol.
> >
> > NOTE: these bindings are distinct from the bindings used with the
> > GT7986U when the chip is running I2C firmware. For some background,
> > see discussion on the mailing lists in the thread:
> >
> > https://lore.kernel.org/r/20241018020815.3098263-2-charles.goodix@gmail.com
> >
> > Signed-off-by: Charles Wang <charles.goodix@gmail.com>
> > ---
> >  .../bindings/input/goodix,gt7986u-spifw.yaml  | 75 +++++++++++++++++++
> >  1 file changed, 75 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.yaml
> >
>
> My bot found errors running 'make dt_binding_check' on your patch:
>
> yamllint warnings/errors:
> ./Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.yaml:16:7: [error] syntax error: mapping values are not allowed here (syntax)

FWIW, I think it's objecting to the "NOTE: " in the description
looking like yaml. Maybe just change it to "Note that". It's also a
good idea to get yourself setup to validate your bindings _before_
posting them to the list.

-Doug
Rob Herring (Arm) Nov. 8, 2024, 4:10 p.m. UTC | #3 
On Fri, Nov 08, 2024 at 08:03:10PM +0800, Charles Wang wrote:
> The Goodix GT7986U touch controller report touch data according to the
> HID protocol through the SPI bus. However, it is incompatible with
> Microsoft's HID-over-SPI protocol.
> 
> NOTE: these bindings are distinct from the bindings used with the
> GT7986U when the chip is running I2C firmware. For some background,
> see discussion on the mailing lists in the thread:
> 
> https://lore.kernel.org/r/20241018020815.3098263-2-charles.goodix@gmail.com
> 
> Signed-off-by: Charles Wang <charles.goodix@gmail.com>
> ---
>  .../bindings/input/goodix,gt7986u-spifw.yaml  | 75 +++++++++++++++++++
>  1 file changed, 75 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.yaml
> 
> diff --git a/Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.yaml b/Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.yaml
> new file mode 100644
> index 000000000..8105b9ce2
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.yaml
> @@ -0,0 +1,75 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/input/goodix,gt7986u-spifw.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Goodix GT7986U SPI HID Touchscreen
> +
> +maintainers:
> +  - Charles Wang <charles.goodix@gmail.com>
> +
> +description: Supports the Goodix GT7986U touchscreen.

Move to next line.

> +  This touch controller reports data packaged according to the HID protocol
> +  over the SPI bus, but it is incompatible with Microsoft's HID-over-SPI protocol.
> +

If you want to maintain paragraphs you need '>' or '|' after 
'description:'. IIRC, it has to be '|' due to the "NOTE: " here:

> +  NOTE: these bindings are distinct from the bindings used with the
> +  GT7986U when the chip is running I2C firmware. This is because there's
> +  not a single device that talks over both I2C and SPI but rather
> +  distinct touchscreens that happen to be built with the same ASIC but
> +  that are distinct products running distinct firmware.
> +
> +allOf:
> +  - $ref: /schemas/spi/spi-peripheral-props.yaml#
> +
> +properties:
> +  compatible:
> +    enum:
> +      - goodix,gt7986u-spifw
> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  reset-gpios:
> +    maxItems: 1
> +
> +  goodix,hid-report-addr:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description:
> +      The register address for retrieving HID report data.
> +
> +  spi-max-frequency: true
> +
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +  - reset-gpios
> +  - goodix,hid-report-addr
> +
> +unevaluatedProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/interrupt-controller/irq.h>
> +    #include <dt-bindings/gpio/gpio.h>
> +
> +    spi {
> +      #address-cells = <1>;
> +      #size-cells = <0>;
> +
> +      touchscreen@0 {
> +        compatible = "goodix,gt7986u-spifw";
> +        reg = <0>;
> +        interrupt-parent = <&gpio>;
> +        interrupts = <25 IRQ_TYPE_LEVEL_LOW>;
> +        reset-gpios = <&gpio1 1 GPIO_ACTIVE_LOW>;
> +        spi-max-frequency = <10000000>;
> +        goodix,hid-report-addr = <0x22c8c>;
> +      };
> +    };
> +
> +...
> -- 
> 2.43.0
>
Charles Wang Nov. 11, 2024, 3:03 a.m. UTC | #4 
Hi Doug,

On Fri, Nov 08, 2024 at 07:13:53AM -0800, Doug Anderson wrote:
> Hi,
> 
> On Fri, Nov 8, 2024 at 5:33 AM Rob Herring (Arm) <robh@kernel.org> wrote:
> >
> >
> > On Fri, 08 Nov 2024 20:03:10 +0800, Charles Wang wrote:
> > > The Goodix GT7986U touch controller report touch data according to the
> > > HID protocol through the SPI bus. However, it is incompatible with
> > > Microsoft's HID-over-SPI protocol.
> > >
> > > NOTE: these bindings are distinct from the bindings used with the
> > > GT7986U when the chip is running I2C firmware. For some background,
> > > see discussion on the mailing lists in the thread:
> > >
> > > https://lore.kernel.org/r/20241018020815.3098263-2-charles.goodix@gmail.com
> > >
> > > Signed-off-by: Charles Wang <charles.goodix@gmail.com>
> > > ---
> > >  .../bindings/input/goodix,gt7986u-spifw.yaml  | 75 +++++++++++++++++++
> > >  1 file changed, 75 insertions(+)
> > >  create mode 100644 Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.yaml
> > >
> >
> > My bot found errors running 'make dt_binding_check' on your patch:
> >
> > yamllint warnings/errors:
> > ./Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.yaml:16:7: [error] syntax error: mapping values are not allowed here (syntax)
> 
> FWIW, I think it's objecting to the "NOTE: " in the description
> looking like yaml. Maybe just change it to "Note that". It's also a
> good idea to get yourself setup to validate your bindings _before_
> posting them to the list.
> 

Change to 'description: |' fixed the issue.

Thanks,
Charles
Charles Wang Nov. 11, 2024, 3:07 a.m. UTC | #5 
Hi Rob,

On Fri, Nov 08, 2024 at 10:10:00AM -0600, Rob Herring wrote:
> On Fri, Nov 08, 2024 at 08:03:10PM +0800, Charles Wang wrote:
> > The Goodix GT7986U touch controller report touch data according to the
> > HID protocol through the SPI bus. However, it is incompatible with
> > Microsoft's HID-over-SPI protocol.
> > 
> > NOTE: these bindings are distinct from the bindings used with the
> > GT7986U when the chip is running I2C firmware. For some background,
> > see discussion on the mailing lists in the thread:
> > 
> > https://lore.kernel.org/r/20241018020815.3098263-2-charles.goodix@gmail.com
> > 
> > Signed-off-by: Charles Wang <charles.goodix@gmail.com>
> > ---
> >  .../bindings/input/goodix,gt7986u-spifw.yaml  | 75 +++++++++++++++++++
> >  1 file changed, 75 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.yaml
> > 
> > diff --git a/Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.yaml b/Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.yaml
> > new file mode 100644
> > index 000000000..8105b9ce2
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.yaml
> > @@ -0,0 +1,75 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/input/goodix,gt7986u-spifw.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Goodix GT7986U SPI HID Touchscreen
> > +
> > +maintainers:
> > +  - Charles Wang <charles.goodix@gmail.com>
> > +
> > +description: Supports the Goodix GT7986U touchscreen.
> 
> Move to next line.
> 

Ack,

>
> > +  This touch controller reports data packaged according to the HID protocol
> > +  over the SPI bus, but it is incompatible with Microsoft's HID-over-SPI protocol.
> > +
> 
> If you want to maintain paragraphs you need '>' or '|' after 
> 'description:'. IIRC, it has to be '|' due to the "NOTE: " here:
> 

Ack, using '|' works.

Best regars,
Charles

>
> > +  NOTE: these bindings are distinct from the bindings used with the
> > +  GT7986U when the chip is running I2C firmware. This is because there's
> > +  not a single device that talks over both I2C and SPI but rather
> > +  distinct touchscreens that happen to be built with the same ASIC but
> > +  that are distinct products running distinct firmware.
> > +
> > +allOf:
> > +  - $ref: /schemas/spi/spi-peripheral-props.yaml#
> > +
> > +properties:
> > +  compatible:
> > +    enum:
> > +      - goodix,gt7986u-spifw
> > +
> > +  reg:
> > +    maxItems: 1
> > +
> > +  interrupts:
> > +    maxItems: 1
> > +
> > +  reset-gpios:
> > +    maxItems: 1
> > +
> > +  goodix,hid-report-addr:
> > +    $ref: /schemas/types.yaml#/definitions/uint32
> > +    description:
> > +      The register address for retrieving HID report data.
> > +
> > +  spi-max-frequency: true
> > +
> > +required:
> > +  - compatible
> > +  - reg
> > +  - interrupts
> > +  - reset-gpios
> > +  - goodix,hid-report-addr
> > +
> > +unevaluatedProperties: false
> > +
> > +examples:
> > +  - |
> > +    #include <dt-bindings/interrupt-controller/irq.h>
> > +    #include <dt-bindings/gpio/gpio.h>
> > +
> > +    spi {
> > +      #address-cells = <1>;
> > +      #size-cells = <0>;
> > +
> > +      touchscreen@0 {
> > +        compatible = "goodix,gt7986u-spifw";
> > +        reg = <0>;
> > +        interrupt-parent = <&gpio>;
> > +        interrupts = <25 IRQ_TYPE_LEVEL_LOW>;
> > +        reset-gpios = <&gpio1 1 GPIO_ACTIVE_LOW>;
> > +        spi-max-frequency = <10000000>;
> > +        goodix,hid-report-addr = <0x22c8c>;
> > +      };
> > +    };
> > +
> > +...
> > -- 
> > 2.43.0
> >
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.yaml b/Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.yaml
new file mode 100644
index 000000000..8105b9ce2
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.yaml
@@ -0,0 +1,75 @@ 
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/goodix,gt7986u-spifw.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Goodix GT7986U SPI HID Touchscreen
+
+maintainers:
+  - Charles Wang <charles.goodix@gmail.com>
+
+description: Supports the Goodix GT7986U touchscreen.
+  This touch controller reports data packaged according to the HID protocol
+  over the SPI bus, but it is incompatible with Microsoft's HID-over-SPI protocol.
+
+  NOTE: these bindings are distinct from the bindings used with the
+  GT7986U when the chip is running I2C firmware. This is because there's
+  not a single device that talks over both I2C and SPI but rather
+  distinct touchscreens that happen to be built with the same ASIC but
+  that are distinct products running distinct firmware.
+
+allOf:
+  - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+properties:
+  compatible:
+    enum:
+      - goodix,gt7986u-spifw
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+  reset-gpios:
+    maxItems: 1
+
+  goodix,hid-report-addr:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description:
+      The register address for retrieving HID report data.
+
+  spi-max-frequency: true
+
+required:
+  - compatible
+  - reg
+  - interrupts
+  - reset-gpios
+  - goodix,hid-report-addr
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/irq.h>
+    #include <dt-bindings/gpio/gpio.h>
+
+    spi {
+      #address-cells = <1>;
+      #size-cells = <0>;
+
+      touchscreen@0 {
+        compatible = "goodix,gt7986u-spifw";
+        reg = <0>;
+        interrupt-parent = <&gpio>;
+        interrupts = <25 IRQ_TYPE_LEVEL_LOW>;
+        reset-gpios = <&gpio1 1 GPIO_ACTIVE_LOW>;
+        spi-max-frequency = <10000000>;
+        goodix,hid-report-addr = <0x22c8c>;
+      };
+    };
+
+...