[media] Documentation: add support for V4L touch devices

Document the new touch API.

Signed-off-by: Nick Dyer <nick@shmanahar.org>
Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
[hans.verkuil@cisco.com: fix up videodev2.h.rst.exceptions]

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Acked-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>

Documentation/media/uapi/mediactl/media-types.rst

@@ -437,6 +437,16 @@ Types and flags used to represent the media graph elements
 
     -  .. row 11
 
+       ..  _MEDIA-INTF-T-V4L-TOUCH:
+
+       -  ``MEDIA_INTF_T_V4L_TOUCH``
+
+       -  Device node interface for Touch device (V4L)
+
+       -  typically, /dev/v4l-touch?
+
+    -  .. row 12
+
        ..  _MEDIA-INTF-T-ALSA-PCM-CAPTURE:
 
        -  ``MEDIA_INTF_T_ALSA_PCM_CAPTURE``
@@ -445,7 +455,7 @@ Types and flags used to represent the media graph elements
 
        -  typically, /dev/snd/pcmC?D?c
 
-    -  .. row 12
+    -  .. row 13
 
        ..  _MEDIA-INTF-T-ALSA-PCM-PLAYBACK:
 
@@ -455,7 +465,7 @@ Types and flags used to represent the media graph elements
 
        -  typically, /dev/snd/pcmC?D?p
 
-    -  .. row 13
+    -  .. row 14
 
        ..  _MEDIA-INTF-T-ALSA-CONTROL:
 
@@ -465,7 +475,7 @@ Types and flags used to represent the media graph elements
 
        -  typically, /dev/snd/controlC?
 
-    -  .. row 14
+    -  .. row 15
 
        ..  _MEDIA-INTF-T-ALSA-COMPRESS:
 
@@ -475,7 +485,7 @@ Types and flags used to represent the media graph elements
 
        -  typically, /dev/snd/compr?
 
-    -  .. row 15
+    -  .. row 16
 
        ..  _MEDIA-INTF-T-ALSA-RAWMIDI:
 
@@ -485,7 +495,7 @@ Types and flags used to represent the media graph elements
 
        -  typically, /dev/snd/midi?
 
-    -  .. row 16
+    -  .. row 17
 
        ..  _MEDIA-INTF-T-ALSA-HWDEP:
 
@@ -495,7 +505,7 @@ Types and flags used to represent the media graph elements
 
        -  typically, /dev/snd/hwC?D?
 
-    -  .. row 17
+    -  .. row 18
 
        ..  _MEDIA-INTF-T-ALSA-SEQUENCER:
 
@@ -505,7 +515,7 @@ Types and flags used to represent the media graph elements
 
        -  typically, /dev/snd/seq
 
-    -  .. row 18
+    -  .. row 19
 
        ..  _MEDIA-INTF-T-ALSA-TIMER:
 

Documentation/media/uapi/v4l/dev-touch.rst

@@ -0,0 +1,56 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _touch:
+
+*************
+Touch Devices
+*************
+
+Touch devices are accessed through character device special files named
+``/dev/v4l-touch0`` to ``/dev/v4l-touch255`` with major number 81 and
+dynamically allocated minor numbers 0 to 255.
+
+Overview
+========
+
+Sensors may be Optical, or Projected Capacitive touch (PCT).
+
+Processing is required to analyse the raw data and produce input events. In
+some systems, this may be performed on the ASIC and the raw data is purely a
+side-channel for diagnostics or tuning. In other systems, the ASIC is a simple
+analogue front end device which delivers touch data at high rate, and any touch
+processing must be done on the host.
+
+For capacitive touch sensing, the touchscreen is composed of an array of
+horizontal and vertical conductors (alternatively called rows/columns, X/Y
+lines, or tx/rx). Mutual Capacitance measured is at the nodes where the
+conductors cross. Alternatively, Self Capacitance measures the signal from each
+column and row independently.
+
+A touch input may be determined by comparing the raw capacitance measurement to
+a no-touch reference (or "baseline") measurement:
+
+Delta = Raw - Reference
+
+The reference measurement takes account of variations in the capacitance across
+the touch sensor matrix, for example manufacturing irregularities,
+environmental or edge effects.
+
+Querying Capabilities
+=====================
+
+Devices supporting the touch interface set the ``V4L2_CAP_VIDEO_CAPTURE`` flag
+and the ``V4L2_CAP_TOUCH`` flag in the ``capabilities`` field of
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl.
+
+At least one of the read/write or streaming I/O methods must be
+supported.
+
+The formats supported by touch devices are documented in
+:ref:`Touch Formats <tch-formats>`.
+
+Data Format Negotiation
+=======================
+
+A touch device may support any I/O method.

Documentation/media/uapi/v4l/devices.rst

@@ -22,5 +22,6 @@ Interfaces
     dev-radio
     dev-rds
     dev-sdr
+    dev-touch
     dev-event
     dev-subdev

Documentation/media/uapi/v4l/pixfmt-tch-td08.rst

@@ -0,0 +1,80 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-TCH-FMT-DELTA-TD08:
+
+********************************
+V4L2_TCH_FMT_DELTA_TD08 ('TD08')
+********************************
+
+*man V4L2_TCH_FMT_DELTA_TD08(2)*
+
+8-bit signed Touch Delta
+
+Description
+===========
+
+This format represents delta data from a touch controller.
+
+Delta values may range from -128 to 127. Typically the values will vary through
+a small range depending on whether the sensor is touched or not. The full value
+may be seen if one of the touchscreen nodes has a fault or the line is not
+connected.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+    :widths:       2 1 1 1 1
+
+
+    -  .. row 1
+
+       -  start + 0:
+
+       -  D'\ :sub:`00`
+
+       -  D'\ :sub:`01`
+
+       -  D'\ :sub:`02`
+
+       -  D'\ :sub:`03`
+
+    -  .. row 2
+
+       -  start + 4:
+
+       -  D'\ :sub:`10`
+
+       -  D'\ :sub:`11`
+
+       -  D'\ :sub:`12`
+
+       -  D'\ :sub:`13`
+
+    -  .. row 3
+
+       -  start + 8:
+
+       -  D'\ :sub:`20`
+
+       -  D'\ :sub:`21`
+
+       -  D'\ :sub:`22`
+
+       -  D'\ :sub:`23`
+
+    -  .. row 4
+
+       -  start + 12:
+
+       -  D'\ :sub:`30`
+
+       -  D'\ :sub:`31`
+
+       -  D'\ :sub:`32`
+
+       -  D'\ :sub:`33`

Documentation/media/uapi/v4l/pixfmt-tch-td16.rst

@@ -0,0 +1,111 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-TCH-FMT-DELTA-TD16:
+
+********************************
+V4L2_TCH_FMT_DELTA_TD16 ('TD16')
+********************************
+
+*man V4L2_TCH_FMT_DELTA_TD16(2)*
+
+16-bit signed Touch Delta
+
+
+Description
+===========
+
+This format represents delta data from a touch controller.
+
+Delta values may range from -32768 to 32767. Typically the values will vary
+through a small range depending on whether the sensor is touched or not. The
+full value may be seen if one of the touchscreen nodes has a fault or the line
+is not connected.
+
+**Byte Order.**
+Each cell is one byte.
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+    :widths:       2 1 1 1 1 1 1 1 1
+
+
+    -  .. row 1
+
+       -  start + 0:
+
+       -  D'\ :sub:`00high`
+
+       -  D'\ :sub:`00low`
+
+       -  D'\ :sub:`01high`
+
+       -  D'\ :sub:`01low`
+
+       -  D'\ :sub:`02high`
+
+       -  D'\ :sub:`02low`
+
+       -  D'\ :sub:`03high`
+
+       -  D'\ :sub:`03low`
+
+    -  .. row 2
+
+       -  start + 8:
+
+       -  D'\ :sub:`10high`
+
+       -  D'\ :sub:`10low`
+
+       -  D'\ :sub:`11high`
+
+       -  D'\ :sub:`11low`
+
+       -  D'\ :sub:`12high`
+
+       -  D'\ :sub:`12low`
+
+       -  D'\ :sub:`13high`
+
+       -  D'\ :sub:`13low`
+
+    -  .. row 3
+
+       -  start + 16:
+
+       -  D'\ :sub:`20high`
+
+       -  D'\ :sub:`20low`
+
+       -  D'\ :sub:`21high`
+
+       -  D'\ :sub:`21low`
+
+       -  D'\ :sub:`22high`
+
+       -  D'\ :sub:`22low`
+
+       -  D'\ :sub:`23high`
+
+       -  D'\ :sub:`23low`
+
+    -  .. row 4
+
+       -  start + 24:
+
+       -  D'\ :sub:`30high`
+
+       -  D'\ :sub:`30low`
+
+       -  D'\ :sub:`31high`
+
+       -  D'\ :sub:`31low`
+
+       -  D'\ :sub:`32high`
+
+       -  D'\ :sub:`32low`
+
+       -  D'\ :sub:`33high`
+
+       -  D'\ :sub:`33low`