renegade-project/linux-next
2
0
Fork 0
mirror of https://github.com/edk2-porting/linux-next.git synced 2024-12-22 12:14:01 +08:00
Code

[media] Documentation: add support for V4L touch devices

Browse Source 
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>
This commit is contained in:
Nick Dyer 2016-08-14 16:57:29 -03:00 committed by Mauro Carvalho Chehab
parent b497265266
commit 233b213a31
12 changed files with 490 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
Documentation/media/uapi/mediactl/media-types.rst
View File

@ -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:

56
Documentation/media/uapi/v4l/dev-touch.rst Normal file
View File

@ -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.

1
Documentation/media/uapi/v4l/devices.rst
View File

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

80
Documentation/media/uapi/v4l/pixfmt-tch-td08.rst Normal file
View File

@ -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`

111
Documentation/media/uapi/v4l/pixfmt-tch-td16.rst Normal file
View File

@ -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`

78
Documentation/media/uapi/v4l/pixfmt-tch-tu08.rst Normal file
View File

@ -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`

110
Documentation/media/uapi/v4l/pixfmt-tch-tu16.rst Normal file
View File

@ -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`

1
Documentation/media/uapi/v4l/pixfmt.rst
View File

@ -32,4 +32,5 @@ see also :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`.)
depth-formats
pixfmt-013
sdr-formats
tch-formats
pixfmt-reserved

18
Documentation/media/uapi/v4l/tch-formats.rst Normal file
View File

@ -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

8
Documentation/media/uapi/v4l/vidioc-enuminput.rst
View File

@ -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}|

8
Documentation/media/uapi/v4l/vidioc-querycap.rst
View File

@ -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

2
Documentation/media/videodev2.h.rst.exceptions
View File

@ -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