Re: [PATCH v7 1/4] dt-bindings: touchscreen: add touch-overlay property

Javier Carrasco
2024-03-19T11:13:13Z

On 1/19/24 08:43, Javier Carrasco wrote:
> The touch-overlay encompasses a number of touch areas that define a
> clipped touchscreen area and/or buttons with a specific functionality.
>
> A clipped touchscreen area avoids getting events from regions that are
> physically hidden by overlay frames.
>
> For touchscreens with printed overlay buttons, sub-nodes with a suitable
> key code can be defined to report key events instead of the original
> touch events.
>
> Reviewed-by: Jeff LaBundy <jeff@labundy.com>
> Reviewed-by: Rob Herring <robh@kernel.org>
> Signed-off-by: Javier Carrasco <javier.carrasco@wolfvision.net>
> ---
> .../bindings/input/touchscreen/touchscreen.yaml | 119 +++++++++++++++++++++
> 1 file changed, 119 insertions(+)
>
> diff --git a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml
> index 431c13335c40..eb1e86fa86c6 100644
> --- a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml
> +++ b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml
> @@ -87,6 +87,125 @@ properties:
> touchscreen-y-plate-ohms:
> description: Resistance of the Y-plate in Ohms
>
> + touch-overlay:

Even though it has already been reviewed, just in case before it gets
applied. Should it not be:

description: |
List of nodes...

instead, to keep formatting?

> + description: list of nodes defining segments (touch areas) on the
> + touchscreen.
> +
> + This object can be used to describe a series of segments to
> + restrict the region within touch events are reported or buttons
> + with a specific functionality.
> +
> + This is of special interest if the touchscreen is shipped with a physical
> + overlay on top of it with a frame that hides some part of the original
> + touchscreen area. Printed buttons on that overlay are also a typical
> + use case.
> +
> + A new touchscreen area is defined as a sub-node without a key code. If a
> + key code is defined in the sub-node, it will be interpreted as a button.
> +
> + The x-origin and y-origin properties of a touchscreen area define the
> + offset of a new origin from where the touchscreen events are referenced.
> + This offset is applied to the events accordingly. The x-size and y-size
> + properties define the size of the touchscreen effective area.
> +
> + The following example shows a new touchscreen area with the new origin
> + (0',0') for the touch events generated by the device.
> +
> + Touchscreen (full area)
> + ┌────────────────────────────────────────┐
> + │ ┌───────────────────────────────┐ │
> + │ │ │ │
> + │ ├ y-size │ │
> + │ │ │ │
> + │ │ touchscreen area │ │
> + │ │ (no key code) │ │
> + │ │ │ │
> + │ │ x-size │ │
> + │ ┌└──────────────┴────────────────┘ │
> + │(0',0') │
> + ┌└────────────────────────────────────────┘
> + (0,0)
> +

When at it, the following line could be aligned to match the rest of the
description.

> + where (0',0') = (0+x-origin,0+y-origin)
> +
> + Sub-nodes with key codes report the touch events on their surface as key
> + events instead.
> +
> + The following example shows a touchscreen with a single button on it.
> +
> + Touchscreen (full area)
> + ┌───────────────────────────────────┐
> + │ │
> + │ │
> + │ ┌─────────┐ │
> + │ │button 0 │ │
> + │ │KEY_POWER│ │
> + │ └─────────┘ │
> + │ │
> + │ │
> + ┌└───────────────────────────────────┘
> + (0,0)
> +

And the origin above too.

> + Segments defining buttons and clipped toushcreen areas can be combined
> + as shown in the following example.
> + In that case only the events within the touchscreen area are reported
> + as touch events. Events within the button areas report their associated
> + key code. Any events outside the defined areas are ignored.
> +
> + Touchscreen (full area)
> + ┌─────────┬──────────────────────────────┐
> + │ │ │
> + │ │ ┌───────────────────────┐ │
> + │ button 0│ │ │ │
> + │KEY_POWER│ │ │ │
> + │ │ │ │ │
> + ├─────────┤ │ touchscreen area │ │
> + │ │ │ (no key code) │ │
> + │ │ │ │ │
> + │ button 1│ │ │ │
> + │ KEY_INFO│ ┌└───────────────────────┘ │
> + │ │(0',0') │
> + ┌└─────────┴──────────────────────────────┘
> + (0,0)
> +

Same with this one.

> + type: object
> +

Best regards,
Javier Carrasco