Received-SPF: pass (google.com: domain of linux-kernel+bounces-30855-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:4601:e00::3 as permitted sender) client-ip=2604:1380:4601:e00::3;
From: Javier Carrasco <javier.carrasco@wolfvision.net>
Date: Fri, 19 Jan 2024 08:43:33 +0100
Subject: [PATCH v7 1/4] dt-bindings: touchscreen: add touch-overlay
 property
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 8bit
Message-Id: <20240119-feature-ts_virtobj_patch-v7-1-eda70985808f@wolfvision.net>
References: <20240119-feature-ts_virtobj_patch-v7-0-eda70985808f@wolfvision.net>
In-Reply-To: <20240119-feature-ts_virtobj_patch-v7-0-eda70985808f@wolfvision.net>
To: Dmitry Torokhov <dmitry.torokhov@gmail.com>, 
 Rob Herring <robh+dt@kernel.org>, 
 Krzysztof Kozlowski <krzysztof.kozlowski+dt@linaro.org>, 
 Conor Dooley <conor+dt@kernel.org>, Henrik Rydberg <rydberg@bitmath.org>, 
 Bastian Hecht <hechtb@gmail.com>, 
 Michael Riesch <michael.riesch@wolfvision.net>, 
 Jeff LaBundy <jeff@labundy.com>
Cc: linux-kernel@vger.kernel.org, linux-input@vger.kernel.org, 
 devicetree@vger.kernel.org, 
 Javier Carrasco <javier.carrasco@wolfvision.net>, 
 Rob Herring <robh@kernel.org>
Precedence: bulk
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0:
	=?utf-8?B?Mkl6SENkNHg5cW96VkQ1TllWRmZmd2VxOXczajFNLzU3Zmh0THhxQTBVWG1J?=
 =?utf-8?B?aThCNWF4c3c3MDdOSTdTemY3cnlHOEpoZjRiOTNpSStYcm1LSVUvRGFtOEZk?=
 =?utf-8?B?NEp1WjY5MG0waU1UN0RmVnk4TlVicGRlclAxRXNwSDN3WFhVc3c0Tk5RbjVp?=
 =?utf-8?B?eDV5dU84Wjltak02TXhVUEJzS2FXTUozblhCS0RuVWNlTktjQlNzbU10blp3?=
 =?utf-8?B?MDJSc2VMTFhNdFoweFhzZEFFSGxQMmJHYktMa3dxTE1WNW5vaTJrTSt5WWs2?=
 =?utf-8?B?S3F0NXBTZklmaWM2NFRkR1FvQXAyd2toNU9aSWlhWit5cU9MSEdkdTBkWm5X?=
 =?utf-8?B?V1lDeUV6RnlEU1ZGb09rcXJYUGlSeTIvVFFDUUk2cTFjRzZRcUVUcm1xU2VZ?=
 =?utf-8?B?QVZVMi9XdnhFYmRzaVd1TWlKOXo0ZFJLV2ovK04zY09tL0RiQXd0eGdYckZz?=
 =?utf-8?B?M2tWSFd6SXh1M1VLMnhtN3BFTStwOUJhcjNHeXFEZVNQSSt6eVhFV3pBL1dW?=
 =?utf-8?B?SHE4dUdGNnB3VVhzRit1VXdldC9BMG5FQ2NyckFsZ0NFN3Vta1U2Qm9CRytq?=
 =?utf-8?B?MkFyeTNDQU03U0FSbzRKZS9SbE1vclMyazhQRnRUZXlvTlVXQVhDR0lyWmM4?=
 =?utf-8?B?NEZzaDNNcjEvWjlxLzJpcHRzdmYrc090Y3lJNmdhNU9FVlR3Z2Jxck1udEVF?=
 =?utf-8?B?OHZ4YXozVU0vU1hMTWFxUnNFM0ZWeHc0QXBSdWV3dmtoWkZMeXBPUkVNa3Ur?=
 =?utf-8?B?WnJCeU9tZ25oV1VJQ0VQUjFubzU1RUs0dTVHWVFFckcxbUtodjZTeU5HUVFu?=
 =?utf-8?B?ZXRCM2NsekZLcEY4ZkpVZGFtN09zdTgxd042UDJhdnE5S3VjbjNwc1VyejBS?=
 =?utf-8?B?aGw4NGgzYi8rcG1RbzJ1bGRsNUEvdFh1RVVyY2E0RktUQnhDcGxyYlBaYVpG?=
 =?utf-8?B?cDZYanN1VEVGZDJ5RDBYY0lwR3FWVnYzUEg5K2twOFBNOVdTd0duS0xNZjJF?=
 =?utf-8?B?UzJIZWFLaGlveDFoc2FuKy82SU5qbjd6M0pPQVlIWmQ2MEFRZ1FOTWFmYlh2?=
 =?utf-8?B?L0NpU05lUW1ITytGRUJOTDZrZExDS1lGSGZJc3pPWXg2SlhXR0dOQmFDUWVR?=
 =?utf-8?B?RUdsaDIvZ2syei9ZOEt3OTIzQzA5dHVsSy9MUjNxdWd6VUVBVFlpaG1SenJj?=
 =?utf-8?B?QmJnaTkzcEdrbmoxOWJoVnA5aFRxM2xlRUJ4cUQvR2c0Mm11UjluNExOOEFE?=
 =?utf-8?B?a1FXczRYd2JKeHVDcG5HalRob1E4TlFFQ2R5SWQ2eGErTlNjZldicEM2eDY0?=
 =?utf-8?B?L2lqSXBRRytnVy9vUVhsMjZMTHVkdnBGOUFSWVJDTTVMQVc5cTk2RWwzaU9O?=
 =?utf-8?B?SmNTQzlDNDdsSGk2WEFoQ0dLN1RTcEEzbDhtSUNBeGJPczQxaU80bHhCbE15?=
 =?utf-8?B?MVJQbjhSUFQyWjQ5Ymx5czZkV1hvdEZpVDI0TFpqUUpHZXg1RlZIR3JCdW44?=
 =?utf-8?B?dEx5eUtiR09pSHZsRjlmMS9oRHM2U1Z0UUxEMW14VXJWcEpSREdrRnBtNy8v?=
 =?utf-8?B?NVpQVXlnUUJWMjdjNlZlUXZrVDY4Sitrb3F5SkhMTjRLVmwxSGhwSTFyVmIw?=
 =?utf-8?B?Z3pRRU9mVVlWNHdLSldNUmk4Y3dzQlNyeGh0bU5JTUdxcnNnYVZyblVUQlZN?=
 =?utf-8?B?RSswZDJCZWNIMDRUa0Zjd3B3UndKSDVhVTlkMzg1TEZ5QTFWS2ZJQXFsUUQv?=
 =?utf-8?B?MEdVVTBKNzBLMk9Gd21ZUVNFeks0aDVVYmpobTFudXpNNnBsejYwYzJKZmRO?=
 =?utf-8?B?MnFkWDRFd1l6QlZQWXVKYXBBQ3RLQUpRdlZlR1NOVzNZQjV1SHJndERrQlZx?=
 =?utf-8?B?RFlSZGErWkRYNVVVSHppQ1hjdndYL2J3SEpOckVaQkVxWExmald3eTFYSVB3?=
 =?utf-8?B?b1h0LzhTbGErT0VnaVc1SVBnZ0FTVFNZK0NoZnpVUU96SHhheTBWUEU2SHRX?=
 =?utf-8?B?akNGSnJhSTBrK1NjNUFGUGxBNGltL1lwM3VSZlF0N2xVZGsvc0JZblpTOGJl?=
 =?utf-8?B?T1pFbnJFZjdUVlRzck9EN0wxSitnUGdkZTcxSjF1OWJXbDRLMFNHZjVpVUx2?=
 =?utf-8?B?V1czNHJLQzN2NEg5M3hITzJBVnBDMkhndU1hdmVwMFE3OVRqb2FxR0ZVengr?=
 =?utf-8?Q?JNbJc2CR6ciWGYAY2lDXfs8=3D?=
X-OriginatorOrg: wolfvision.net
X-MS-Exchange-CrossTenant-Network-Message-Id: 458c6b6d-b3e6-44f9-cea0-08dc18c25aa3
X-MS-Exchange-CrossTenant-AuthSource: VE1PR08MB4974.eurprd08.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 19 Jan 2024 07:43:40.4621
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: e94ec9da-9183-471e-83b3-51baa8eb804f
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: 2RGnNXKicHJF/jU9pzoBIQ7hFaDTuxfqXJ/epol6vtqqQ7rReGmIlhOm3GXz66UXtW7Y++bIThFwhrA09J3pjZX9ZluxDvPs8Lju6JiBJm8=
X-MS-Exchange-Transport-CrossTenantHeadersStamped: AM8PR08MB6578

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:
+    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)
+
+     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)
+
+      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)
+
+    type: object
+
+    patternProperties:
+      '^segment-':
+        type: object
+        description:
+          Each segment is represented as a sub-node.
+        properties:
+          x-origin:
+            description: horizontal origin of the node area
+            $ref: /schemas/types.yaml#/definitions/uint32
+
+          y-origin:
+            description: vertical origin of the node area
+            $ref: /schemas/types.yaml#/definitions/uint32
+
+          x-size:
+            description: horizontal resolution of the node area
+            $ref: /schemas/types.yaml#/definitions/uint32
+
+          y-size:
+            description: vertical resolution of the node area
+            $ref: /schemas/types.yaml#/definitions/uint32
+
+          label:
+            description: descriptive name of the segment
+            $ref: /schemas/types.yaml#/definitions/string
+
+          linux,code: true
+
+        required:
+          - x-origin
+          - y-origin
+          - x-size
+          - y-size
+
+        unevaluatedProperties: false
+
 dependencies:
   touchscreen-size-x: [ touchscreen-size-y ]
   touchscreen-size-y: [ touchscreen-size-x ]

-- 
2.39.2