From 233b213a3143d9f1dc6984816262c43f95144bb9 Mon Sep 17 00:00:00 2001 From: Nick Dyer Date: Sun, 14 Aug 2016 16:57:29 -0300 Subject: [PATCH] [media] Documentation: add support for V4L touch devices Document the new touch API. Signed-off-by: Nick Dyer Signed-off-by: Hans Verkuil [hans.verkuil@cisco.com: fix up videodev2.h.rst.exceptions] Signed-off-by: Mauro Carvalho Chehab Acked-by: Dmitry Torokhov --- .../media/uapi/mediactl/media-types.rst | 24 ++-- Documentation/media/uapi/v4l/dev-touch.rst | 56 +++++++++ Documentation/media/uapi/v4l/devices.rst | 1 + .../media/uapi/v4l/pixfmt-tch-td08.rst | 80 +++++++++++++ .../media/uapi/v4l/pixfmt-tch-td16.rst | 111 ++++++++++++++++++ .../media/uapi/v4l/pixfmt-tch-tu08.rst | 78 ++++++++++++ .../media/uapi/v4l/pixfmt-tch-tu16.rst | 110 +++++++++++++++++ Documentation/media/uapi/v4l/pixfmt.rst | 1 + Documentation/media/uapi/v4l/tch-formats.rst | 18 +++ .../media/uapi/v4l/vidioc-enuminput.rst | 8 ++ .../media/uapi/v4l/vidioc-querycap.rst | 8 ++ .../media/videodev2.h.rst.exceptions | 2 + 12 files changed, 490 insertions(+), 7 deletions(-) create mode 100644 Documentation/media/uapi/v4l/dev-touch.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-tch-td08.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-tch-td16.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-tch-tu08.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-tch-tu16.rst create mode 100644 Documentation/media/uapi/v4l/tch-formats.rst diff --git a/Documentation/media/uapi/mediactl/media-types.rst b/Documentation/media/uapi/mediactl/media-types.rst index 20f99301bfdb..c3a23108b99d 100644 --- a/Documentation/media/uapi/mediactl/media-types.rst +++ b/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: diff --git a/Documentation/media/uapi/v4l/dev-touch.rst b/Documentation/media/uapi/v4l/dev-touch.rst new file mode 100644 index 000000000000..1f4e75243a47 --- /dev/null +++ b/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 ` 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 `. + +Data Format Negotiation +======================= + +A touch device may support any I/O method. diff --git a/Documentation/media/uapi/v4l/devices.rst b/Documentation/media/uapi/v4l/devices.rst index aed0ce11d1f8..5c3d6c29e12c 100644 --- a/Documentation/media/uapi/v4l/devices.rst +++ b/Documentation/media/uapi/v4l/devices.rst @@ -22,5 +22,6 @@ Interfaces dev-radio dev-rds dev-sdr + dev-touch dev-event dev-subdev diff --git a/Documentation/media/uapi/v4l/pixfmt-tch-td08.rst b/Documentation/media/uapi/v4l/pixfmt-tch-td08.rst new file mode 100644 index 000000000000..e1d1b75454cd --- /dev/null +++ b/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` diff --git a/Documentation/media/uapi/v4l/pixfmt-tch-td16.rst b/Documentation/media/uapi/v4l/pixfmt-tch-td16.rst new file mode 100644 index 000000000000..dfbbc405f889 --- /dev/null +++ b/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` diff --git a/Documentation/media/uapi/v4l/pixfmt-tch-tu08.rst b/Documentation/media/uapi/v4l/pixfmt-tch-tu08.rst new file mode 100644 index 000000000000..18408afe39f5 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-tch-tu08.rst @@ -0,0 +1,78 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-TCH-FMT-TU08: + +************************** +V4L2_TCH_FMT_TU08 ('TU08') +************************** + +*man V4L2_TCH_FMT_TU08(2)* + +8-bit unsigned raw touch data + +Description +=========== + +This format represents unsigned 8-bit data from a touch controller. + +This may be used for output for raw and reference data. Values may range from +0 to 255. + +**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: + + - R'\ :sub:`00` + + - R'\ :sub:`01` + + - R'\ :sub:`02` + + - R'\ :sub:`03` + + - .. row 2 + + - start + 4: + + - R'\ :sub:`10` + + - R'\ :sub:`11` + + - R'\ :sub:`12` + + - R'\ :sub:`13` + + - .. row 3 + + - start + 8: + + - R'\ :sub:`20` + + - R'\ :sub:`21` + + - R'\ :sub:`22` + + - R'\ :sub:`23` + + - .. row 4 + + - start + 12: + + - R'\ :sub:`30` + + - R'\ :sub:`31` + + - R'\ :sub:`32` + + - R'\ :sub:`33` diff --git a/Documentation/media/uapi/v4l/pixfmt-tch-tu16.rst b/Documentation/media/uapi/v4l/pixfmt-tch-tu16.rst new file mode 100644 index 000000000000..67be13d9e550 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-tch-tu16.rst @@ -0,0 +1,110 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-TCH-FMT-TU16: + +******************************** +V4L2_TCH_FMT_TU16 ('TU16') +******************************** + +*man V4L2_TCH_FMT_TU16(2)* + +16-bit unsigned raw touch data + + +Description +=========== + +This format represents unsigned 16-bit data from a touch controller. + +This may be used for output for raw and reference data. Values may range from +0 to 65535. + +**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: + + - R'\ :sub:`00high` + + - R'\ :sub:`00low` + + - R'\ :sub:`01high` + + - R'\ :sub:`01low` + + - R'\ :sub:`02high` + + - R'\ :sub:`02low` + + - R'\ :sub:`03high` + + - R'\ :sub:`03low` + + - .. row 2 + + - start + 8: + + - R'\ :sub:`10high` + + - R'\ :sub:`10low` + + - R'\ :sub:`11high` + + - R'\ :sub:`11low` + + - R'\ :sub:`12high` + + - R'\ :sub:`12low` + + - R'\ :sub:`13high` + + - R'\ :sub:`13low` + + - .. row 3 + + - start + 16: + + - R'\ :sub:`20high` + + - R'\ :sub:`20low` + + - R'\ :sub:`21high` + + - R'\ :sub:`21low` + + - R'\ :sub:`22high` + + - R'\ :sub:`22low` + + - R'\ :sub:`23high` + + - R'\ :sub:`23low` + + - .. row 4 + + - start + 24: + + - R'\ :sub:`30high` + + - R'\ :sub:`30low` + + - R'\ :sub:`31high` + + - R'\ :sub:`31low` + + - R'\ :sub:`32high` + + - R'\ :sub:`32low` + + - R'\ :sub:`33high` + + - R'\ :sub:`33low` diff --git a/Documentation/media/uapi/v4l/pixfmt.rst b/Documentation/media/uapi/v4l/pixfmt.rst index 81222a99f7ce..6866bcb7d229 100644 --- a/Documentation/media/uapi/v4l/pixfmt.rst +++ b/Documentation/media/uapi/v4l/pixfmt.rst @@ -32,4 +32,5 @@ see also :ref:`VIDIOC_G_FBUF `.) depth-formats pixfmt-013 sdr-formats + tch-formats pixfmt-reserved diff --git a/Documentation/media/uapi/v4l/tch-formats.rst b/Documentation/media/uapi/v4l/tch-formats.rst new file mode 100644 index 000000000000..dbaabf33a5b8 --- /dev/null +++ b/Documentation/media/uapi/v4l/tch-formats.rst @@ -0,0 +1,18 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _tch-formats: + +************* +Touch Formats +************* + +These formats are used for :ref:`touch` interface only. + + +.. toctree:: + :maxdepth: 1 + + pixfmt-tch-td16 + pixfmt-tch-td08 + pixfmt-tch-tu16 + pixfmt-tch-tu08 diff --git a/Documentation/media/uapi/v4l/vidioc-enuminput.rst b/Documentation/media/uapi/v4l/vidioc-enuminput.rst index 51747b7b7f29..8f6c603819d8 100644 --- a/Documentation/media/uapi/v4l/vidioc-enuminput.rst +++ b/Documentation/media/uapi/v4l/vidioc-enuminput.rst @@ -175,6 +175,14 @@ at index zero, incrementing by one until the driver returns ``EINVAL``. - Analog baseband input, for example CVBS / Composite Video, S-Video, RGB. + - .. row 3 + + - ``V4L2_INPUT_TYPE_TOUCH`` + + - 3 + + - This input is a touch device for capturing raw touch data. + .. tabularcolumns:: |p{4.8cm}|p{2.6cm}|p{10.1cm}| diff --git a/Documentation/media/uapi/v4l/vidioc-querycap.rst b/Documentation/media/uapi/v4l/vidioc-querycap.rst index d627b80c4141..97a394bbcc9c 100644 --- a/Documentation/media/uapi/v4l/vidioc-querycap.rst +++ b/Documentation/media/uapi/v4l/vidioc-querycap.rst @@ -410,6 +410,14 @@ specification the ioctl returns an ``EINVAL`` error code. - .. row 26 + - ``V4L2_CAP_TOUCH`` + + - 0x10000000 + + - This is a touch device. + + - .. row 27 + - ``V4L2_CAP_DEVICE_CAPS`` - 0x80000000 diff --git a/Documentation/media/videodev2.h.rst.exceptions b/Documentation/media/videodev2.h.rst.exceptions index 9bb9a6cc39d8..f0b243c48118 100644 --- a/Documentation/media/videodev2.h.rst.exceptions +++ b/Documentation/media/videodev2.h.rst.exceptions @@ -152,6 +152,7 @@ replace define V4L2_CAP_READWRITE device-capabilities replace define V4L2_CAP_ASYNCIO device-capabilities replace define V4L2_CAP_STREAMING device-capabilities replace define V4L2_CAP_DEVICE_CAPS device-capabilities +replace define V4L2_CAP_TOUCH device-capabilities # V4L2 pix flags replace define V4L2_PIX_FMT_PRIV_MAGIC v4l2-pix-format @@ -285,6 +286,7 @@ replace define V4L2_DV_BT_CAP_CUSTOM framebuffer-cap replace define V4L2_INPUT_TYPE_TUNER input-type replace define V4L2_INPUT_TYPE_CAMERA input-type +replace define V4L2_INPUT_TYPE_TOUCH input-type replace define V4L2_IN_ST_NO_POWER input-status replace define V4L2_IN_ST_NO_SIGNAL input-status