# SPDX-License-Identifier: GPL-2.0
%YAML 1.2
---
$id: http://devicetree.org/schemas/input/touchscreen/touchscreen.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Common touchscreen

maintainers:
  - Dmitry Torokhov <dmitry.torokhov@gmail.com>

properties:
  panel:
    description: If this touchscreen is integrally connected to a panel, this
      is a reference to that panel. The presence of this reference indicates
      that the touchscreen should be power sequenced together with the panel
      and that they may share power and/or reset signals.
    $ref: /schemas/types.yaml#/definitions/phandle

  touchscreen-min-x:
    description: minimum x coordinate reported
    $ref: /schemas/types.yaml#/definitions/uint32
    default: 0

  touchscreen-min-y:
    description: minimum y coordinate reported
    $ref: /schemas/types.yaml#/definitions/uint32
    default: 0

  touchscreen-size-x:
    description: horizontal resolution of touchscreen (maximum x coordinate reported + 1)
    $ref: /schemas/types.yaml#/definitions/uint32

  touchscreen-size-y:
    description: vertical resolution of touchscreen (maximum y coordinate reported + 1)
    $ref: /schemas/types.yaml#/definitions/uint32

  touchscreen-max-pressure:
    description: maximum reported pressure (arbitrary range dependent on the controller)
    $ref: /schemas/types.yaml#/definitions/uint32

  touchscreen-min-pressure:
    description: minimum pressure on the touchscreen to be achieved in order
      for the touchscreen driver to report a touch event.
    $ref: /schemas/types.yaml#/definitions/uint32

  touchscreen-fuzz-x:
    description: horizontal noise value of the absolute input device (in pixels)
    $ref: /schemas/types.yaml#/definitions/uint32

  touchscreen-fuzz-y:
    description: vertical noise value of the absolute input device (in pixels)
    $ref: /schemas/types.yaml#/definitions/uint32

  touchscreen-fuzz-pressure:
    description: pressure noise value of the absolute input device (arbitrary
      range dependent on the controller)
    $ref: /schemas/types.yaml#/definitions/uint32

  touchscreen-average-samples:
    description: Number of data samples which are averaged for each read (valid
      values dependent on the controller)
    $ref: /schemas/types.yaml#/definitions/uint32

  touchscreen-inverted-x:
    description: X axis is inverted
    type: boolean

  touchscreen-inverted-y:
    description: Y axis is inverted
    type: boolean

  touchscreen-swapped-x-y:
    description: X and Y axis are swapped
                 Swapping is done after inverting the axis
    type: boolean

  touchscreen-x-mm:
    description: horizontal length in mm of the touchscreen

  touchscreen-y-mm:
    description: vertical length in mm of the touchscreen

  touchscreen-x-plate-ohms:
    description: Resistance of the X-plate in Ohms

  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

  debounce-delay-us:
    description: Minimum duration in microseconds a signal must remain stable
      to be considered valid.

dependencies:
  touchscreen-size-x: [ touchscreen-size-y ]
  touchscreen-size-y: [ touchscreen-size-x ]
  touchscreen-x-mm: [ touchscreen-y-mm ]
  touchscreen-y-mm: [ touchscreen-x-mm ]

additionalProperties: true