From: y@shmanahar.org
To: Dmitry Torokhov <dmitry.torokhov@gmail.com>,
Hans Verkuil <hverkuil@xs4all.nl>
Cc: linux-input@vger.kernel.org, linux-kernel@vger.kernel.org,
linux-media@vger.kernel.org,
Benjamin Tissoires <benjamin.tissoires@redhat.com>,
Benson Leung <bleung@chromium.org>,
Javier Martinez Canillas <javier@osg.samsung.com>,
Chris Healy <cphealy@gmail.com>,
Henrik Rydberg <rydberg@bitmath.org>,
Andrew Duggan <aduggan@synaptics.com>,
James Chen <james.chen@emc.com.tw>, Dudley Du <dudl@cypress.com>,
Andrew de los Reyes <adlr@chromium.org>,
sheckylin@chromium.org, Peter Hutterer <peter.hutterer@who-t.net>,
Florian Echtler <floe@butterbrot.org>,
mchehab@osg.samsung.com, Nick Dyer <nick@shmanahar.org>
Subject: [PATCH] Documentation: add support for V4L touch devices
Date: Mon, 18 Jul 2016 22:11:52 +0100 [thread overview]
Message-ID: <24660.9531263404$1468876843@news.gmane.org> (raw)
In-Reply-To: <1468876238-24599-1-git-send-email-nick@shmanahar.org>
From: Nick Dyer <nick@shmanahar.org>
Signed-off-by: Nick Dyer <nick@shmanahar.org>
---
Documentation/media/uapi/mediactl/media-types.rst | 24 +++--
Documentation/media/uapi/v4l/dev-touch.rst | 55 ++++++++++
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 ++++
9 files changed, 471 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..5c71ee9
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-touch.rst
@@ -0,0 +1,55 @@
+.. -*- 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
+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..32e21f8
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-tch-tu08.rst
@@ -0,0 +1,78 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-TCH-FMT-DELTA-TU08:
+
+**************************
+V4L2_TCH_FMT_DELTA_TU08 ('TU08')
+**************************
+
+*man V4L2_TCH_FMT_DELTA_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..c4bc3a1
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-tch-tu16.rst
@@ -0,0 +1,110 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-TCH-FMT-DELTA-TU16:
+
+********************************
+V4L2_TCH_FMT_DELTA_TU16 ('TU16')
+********************************
+
+*man V4L2_TCH_FMT_DELTA_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
--
1.7.9.5
next prev parent reply other threads:[~2016-07-18 21:11 UTC|newest]
Thread overview: 24+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-07-18 21:10 [PATCH v8 0/10] Output raw touch data via V4L2 Nick Dyer
2016-07-18 21:10 ` [PATCH v8 01/10] Input: atmel_mxt_ts - update MAINTAINERS email address Nick Dyer
2016-07-18 21:10 ` [PATCH v8 02/10] v4l2-core: Add support for touch devices Nick Dyer
2016-07-18 21:10 ` [PATCH v8 03/10] Input: atmel_mxt_ts - add support for T37 diagnostic data Nick Dyer
2016-08-23 19:30 ` Mauro Carvalho Chehab
2016-08-23 19:51 ` Dmitry Torokhov
2016-07-18 21:10 ` [PATCH v8 04/10] Input: atmel_mxt_ts - output diagnostic debug via V4L2 device Nick Dyer
2016-07-18 21:10 ` [PATCH v8 05/10] Input: atmel_mxt_ts - read touchscreen size Nick Dyer
2016-07-18 21:10 ` [PATCH v8 06/10] Input: atmel_mxt_ts - handle diagnostic data orientation Nick Dyer
2016-07-18 21:10 ` [PATCH v8 07/10] Input: atmel_mxt_ts - add diagnostic data support for mXT1386 Nick Dyer
2016-07-18 21:10 ` [PATCH v8 08/10] Input: atmel_mxt_ts - add support for reference data Nick Dyer
2016-07-18 21:10 ` [PATCH v8 09/10] Input: synaptics-rmi4 - add support for F54 diagnostics Nick Dyer
2016-07-18 21:10 ` [PATCH v8 10/10] Input: sur40 - use new V4L2 touch input type Nick Dyer
2016-08-12 9:41 ` Hans Verkuil
2016-08-12 10:20 ` Nick Dyer
2016-07-18 21:11 ` [PATCH] Documentation: add support for V4L touch devices y
2016-08-12 10:06 ` Hans Verkuil
2016-08-14 19:57 ` [PATCH v2] " Nick Dyer
2016-07-18 21:11 ` [PATCH] " y
2016-07-18 21:11 ` y [this message]
2016-07-18 21:11 ` y
2016-07-18 21:12 ` [PATCH] v4l2-compliance: Changes to support touch sensors Nick Dyer
2016-07-20 7:48 ` [PATCH v8 0/10] Output raw touch data via V4L2 Hans Verkuil
2016-07-23 2:10 ` Chris Healy
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='24660.9531263404$1468876843@news.gmane.org' \
--to=y@shmanahar.org \
--cc=adlr@chromium.org \
--cc=aduggan@synaptics.com \
--cc=benjamin.tissoires@redhat.com \
--cc=bleung@chromium.org \
--cc=cphealy@gmail.com \
--cc=dmitry.torokhov@gmail.com \
--cc=dudl@cypress.com \
--cc=floe@butterbrot.org \
--cc=hverkuil@xs4all.nl \
--cc=james.chen@emc.com.tw \
--cc=javier@osg.samsung.com \
--cc=linux-input@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-media@vger.kernel.org \
--cc=mchehab@osg.samsung.com \
--cc=nick@shmanahar.org \
--cc=peter.hutterer@who-t.net \
--cc=rydberg@bitmath.org \
--cc=sheckylin@chromium.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.