Re: [PATCH v6 08/11] dt-bindings: input: Document hid-over-spi DT schema

[Conor Dooley <conor@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 6063 bytes --]

On Mon, Oct 19, 2026 at 07:01:20PM +0000, Jingyuan Liang wrote:
> Documentation describes the required and optional properties for
> implementing Device Tree for a Microsoft G6 Touch Digitizer that
> supports HID over SPI Protocol 1.0 specification.
> 
> The properties are common to HID over SPI.
> 
> Signed-off-by: Dmitry Antipov <dmanti@microsoft.com>
> Signed-off-by: Jarrett Schultz <jaschultz@microsoft.com>
> Signed-off-by: Jingyuan Liang <jingyliang@chromium.org>

Signoff chain is not right, since the nominal patch author is the last
signoff.

> ---
>  .../devicetree/bindings/input/hid-over-spi.yaml    | 130 +++++++++++++++++++++
>  1 file changed, 130 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/input/hid-over-spi.yaml b/Documentation/devicetree/bindings/input/hid-over-spi.yaml
> new file mode 100644
> index 000000000000..2a5fa0868a09
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/input/hid-over-spi.yaml
> @@ -0,0 +1,130 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/input/hid-over-spi.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: HID over SPI Devices
> +
> +maintainers:
> +  - Benjamin Tissoires <benjamin.tissoires@redhat.com>
> +  - Jiri Kosina <jkosina@suse.cz>
> +  - Jingyuan Liang <jingyliang@chromium.org>
> +
> +description: |+
> +  HID over SPI provides support for various Human Interface Devices over the
> +  SPI bus. These devices can be for example touchpads, keyboards, touch screens
> +  or sensors.
> +
> +  The specification has been written by Microsoft and is currently available
> +  here: https://www.microsoft.com/en-us/download/details.aspx?id=103325
> +
> +  The HID over SPI specification does not define fixed values for the
> +  read/write opcodes and the input/output report addresses. The host
> +  retrieves them from platform firmware (ACPI _DSM), and they differ
> +  between devices. These properties provide the same values on Device
> +  Tree systems, so devices that fully comply with the specification work
> +  with the "hid-over-spi" fallback compatible.
> +
> +allOf:
> +  - $ref: /schemas/input/touchscreen/touchscreen.yaml#
> +  - $ref: /schemas/spi/spi-peripheral-props.yaml#
> +
> +properties:
> +  compatible:
> +    items:
> +      - enum:
> +          - microsoft,g6-touch-digitizer
> +      - const: hid-over-spi
> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  reset-gpios:
> +    maxItems: 1
> +    description:
> +      GPIO specifier for the device's reset line. The HID over SPI
> +      specification requires a dedicated, host-driven, active-low reset
> +      line. The line must be flagged with GPIO_ACTIVE_LOW.
> +
> +  vdd-supply:
> +    description:
> +      Regulator for the VDD supply voltage.
> +
> +  input-report-header-address:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    minimum: 0
> +    maximum: 0xffffff
> +    description:
> +      A value to be included in the Read Approval packet, listing an address of
> +      the input report header to be put on the SPI bus. This address has 24
> +      bits.
> +
> +  input-report-body-address:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    minimum: 0
> +    maximum: 0xffffff
> +    description:
> +      A value to be included in the Read Approval packet, listing an address of
> +      the input report body to be put on the SPI bus. This address has 24 bits.
> +
> +  output-report-address:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    minimum: 0
> +    maximum: 0xffffff
> +    description:
> +      A value to be included in the Output Report sent by the host, listing an
> +      address where the output report on the SPI bus is to be written to. This
> +      address has 24 bits.
> +
> +  read-opcode:
> +    $ref: /schemas/types.yaml#/definitions/uint8
> +    description:
> +      Value to be used in Read Approval packets. 1 byte.
> +
> +  write-opcode:
> +    $ref: /schemas/types.yaml#/definitions/uint8
> +    description:
> +      Value to be used in Output Report packets. 1 byte.

I still dunno why any of these properties exist, especially when there's
a patch in my queue for another microsoft touch device on top of
this series that does not use any of them.

The commit message really needs to explain why these exist and why
compatibles cannot be used to determine these things - as is done for
the microsoft,romulus13-touchpad. If the very next device that appears
seems to require a specific compatible and cannot use these properties
to get across what's needed to the kernel it calls into question why
the binding is designed like this.

pw-bot: changes-requested

Thanks,
Conor.

> +
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +  - reset-gpios
> +  - vdd-supply
> +  - input-report-header-address
> +  - input-report-body-address
> +  - output-report-address
> +  - read-opcode
> +  - write-opcode
> +
> +unevaluatedProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/interrupt-controller/irq.h>
> +    #include <dt-bindings/gpio/gpio.h>
> +
> +    spi {
> +      #address-cells = <1>;
> +      #size-cells = <0>;
> +
> +      hid@0 {
> +        compatible = "microsoft,g6-touch-digitizer", "hid-over-spi";
> +        reg = <0x0>;
> +        interrupts-extended = <&gpio 42 IRQ_TYPE_EDGE_FALLING>;
> +        reset-gpios = <&gpio 27 GPIO_ACTIVE_LOW>;
> +        vdd-supply = <&pm8350c_l3>;
> +        pinctrl-names = "default";
> +        pinctrl-0 = <&ts_d6_int_bias>;
> +        input-report-header-address = <0x1000>;
> +        input-report-body-address = <0x1004>;
> +        output-report-address = <0x2000>;
> +        read-opcode = /bits/ 8 <0x0b>;
> +        write-opcode = /bits/ 8 <0x02>;
> +      };
> +    };
> 
> -- 
> 2.56.0.212.g129ede20d9-goog
> 

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]