| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Date: Sun, 14 Aug 2016 20:57:29 +0100
From: Nick Dyer <nick@...anahar.org>
To: Hans Verkuil <hverkuil@...all.nl>
Cc: Dmitry Torokhov <dmitry.torokhov@...il.com>,
linux-input@...r.kernel.org, linux-kernel@...r.kernel.org,
linux-media@...r.kernel.org,
Benjamin Tissoires <benjamin.tissoires@...hat.com>,
Benson Leung <bleung@...omium.org>,
Javier Martinez Canillas <javier@....samsung.com>,
Chris Healy <cphealy@...il.com>,
Henrik Rydberg <rydberg@...math.org>,
Andrew Duggan <aduggan@...aptics.com>,
James Chen <james.chen@....com.tw>,
Dudley Du <dudl@...ress.com>,
Andrew de los Reyes <adlr@...omium.org>,
sheckylin@...omium.org, Peter Hutterer <peter.hutterer@...-t.net>,
Florian Echtler <floe@...terbrot.org>, mchehab@....samsung.com,
Nick Dyer <nick@...anahar.org>
Subject: [PATCH v2] Documentation: add support for V4L touch devices
[v2: Fix minor issues and document V4L2_INPUT_TYPE_TOUCH and V4L2_CAP_TOUCH]
Signed-off-by: Nick Dyer <nick@...anahar.org>
---
Documentation/media/uapi/mediactl/media-types.rst | 24 +++--
Documentation/media/uapi/v4l/dev-touch.rst | 56 +++++++++++
Documentation/media/uapi/v4l/devices.rst | 1 +
Documentation/media/uapi/v4l/pixfmt-tch-td08.rst | 80 ++++++++++++++++
Documentation/media/uapi/v4l/pixfmt-tch-td16.rst | 111 ++++++++++++++++++++++
Documentation/media/uapi/v4l/pixfmt-tch-tu08.rst | 78 +++++++++++++++
Documentation/media/uapi/v4l/pixfmt-tch-tu16.rst | 110 +++++++++++++++++++++
Documentation/media/uapi/v4l/pixfmt.rst | 1 +
Documentation/media/uapi/v4l/tch-formats.rst | 18 ++++
Documentation/media/uapi/v4l/vidioc-enuminput.rst | 8 ++
Documentation/media/uapi/v4l/vidioc-querycap.rst | 8 ++
11 files changed, 488 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 c77717b..0265edc 100644
--- a/Documentation/media/uapi/mediactl/media-types.rst
+++ b/Documentation/media/uapi/mediactl/media-types.rst
@@ -429,6 +429,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``
@@ -437,7 +447,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:
@@ -447,7 +457,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:
@@ -457,7 +467,7 @@ Types and flags used to represent the media graph elements
- typically, /dev/snd/controlC?
- - .. row 14
+ - .. row 15
.. _MEDIA-INTF-T-ALSA-COMPRESS:
@@ -467,7 +477,7 @@ Types and flags used to represent the media graph elements
- typically, /dev/snd/compr?
- - .. row 15
+ - .. row 16
.. _MEDIA-INTF-T-ALSA-RAWMIDI:
@@ -477,7 +487,7 @@ Types and flags used to represent the media graph elements
- typically, /dev/snd/midi?
- - .. row 16
+ - .. row 17
.. _MEDIA-INTF-T-ALSA-HWDEP:
@@ -487,7 +497,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:
@@ -497,7 +507,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 0000000..1f4e752
--- /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 <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.
diff --git a/Documentation/media/uapi/v4l/devices.rst b/Documentation/media/uapi/v4l/devices.rst
index aed0ce1..5c3d6c2 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 0000000..e1d1b75
--- /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 0000000..dfbbc40
--- /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 0000000..18408af
--- /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 0000000..67be13d
--- /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 81222a9..6866bcb 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 <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 0000000..dbaabf3
--- /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 5060f54..ba83bcd 100644
--- a/Documentation/media/uapi/v4l/vidioc-enuminput.rst
+++ b/Documentation/media/uapi/v4l/vidioc-enuminput.rst
@@ -173,6 +173,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.
+
.. _input-status:
diff --git a/Documentation/media/uapi/v4l/vidioc-querycap.rst b/Documentation/media/uapi/v4l/vidioc-querycap.rst
index b10fed3..3765726 100644
--- a/Documentation/media/uapi/v4l/vidioc-querycap.rst
+++ b/Documentation/media/uapi/v4l/vidioc-querycap.rst
@@ -412,6 +412,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.7.4
Powered by blists - more mailing lists