tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
[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>
authored by
Nick Dyer
and committed by
Mauro Carvalho Chehab
233b213a
b4972652
+490
-7
+17
-7
Documentation/media/uapi/mediactl/media-types.rst
+17
-7
Documentation/media/uapi/mediactl/media-types.rst
···
437
437
438
438
- .. row 11
439
439
440
+
.. _MEDIA-INTF-T-V4L-TOUCH:
441
+
442
+
- ``MEDIA_INTF_T_V4L_TOUCH``
443
+
444
+
- Device node interface for Touch device (V4L)
445
+
446
+
- typically, /dev/v4l-touch?
447
+
448
+
- .. row 12
449
+
440
450
.. _MEDIA-INTF-T-ALSA-PCM-CAPTURE:
441
451
442
452
- ``MEDIA_INTF_T_ALSA_PCM_CAPTURE``
···
455
445
456
446
- typically, /dev/snd/pcmC?D?c
457
447
458
-
- .. row 12
448
+
- .. row 13
459
449
460
450
.. _MEDIA-INTF-T-ALSA-PCM-PLAYBACK:
461
451
···
465
455
466
456
- typically, /dev/snd/pcmC?D?p
467
457
468
-
- .. row 13
458
+
- .. row 14
469
459
470
460
.. _MEDIA-INTF-T-ALSA-CONTROL:
471
461
···
475
465
476
466
- typically, /dev/snd/controlC?
477
467
478
-
- .. row 14
468
+
- .. row 15
479
469
480
470
.. _MEDIA-INTF-T-ALSA-COMPRESS:
481
471
···
485
475
486
476
- typically, /dev/snd/compr?
487
477
488
-
- .. row 15
478
+
- .. row 16
489
479
490
480
.. _MEDIA-INTF-T-ALSA-RAWMIDI:
491
481
···
495
485
496
486
- typically, /dev/snd/midi?
497
487
498
-
- .. row 16
488
+
- .. row 17
499
489
500
490
.. _MEDIA-INTF-T-ALSA-HWDEP:
501
491
···
505
495
506
496
- typically, /dev/snd/hwC?D?
507
497
508
-
- .. row 17
498
+
- .. row 18
509
499
510
500
.. _MEDIA-INTF-T-ALSA-SEQUENCER:
511
501
···
515
505
516
506
- typically, /dev/snd/seq
517
507
518
-
- .. row 18
508
+
- .. row 19
519
509
520
510
.. _MEDIA-INTF-T-ALSA-TIMER:
521
511
+56
Documentation/media/uapi/v4l/dev-touch.rst
+56
Documentation/media/uapi/v4l/dev-touch.rst
···
1
+
.. -*- coding: utf-8; mode: rst -*-
2
+
3
+
.. _touch:
4
+
5
+
*************
6
+
Touch Devices
7
+
*************
8
+
9
+
Touch devices are accessed through character device special files named
10
+
``/dev/v4l-touch0`` to ``/dev/v4l-touch255`` with major number 81 and
11
+
dynamically allocated minor numbers 0 to 255.
12
+
13
+
Overview
14
+
========
15
+
16
+
Sensors may be Optical, or Projected Capacitive touch (PCT).
17
+
18
+
Processing is required to analyse the raw data and produce input events. In
19
+
some systems, this may be performed on the ASIC and the raw data is purely a
20
+
side-channel for diagnostics or tuning. In other systems, the ASIC is a simple
21
+
analogue front end device which delivers touch data at high rate, and any touch
22
+
processing must be done on the host.
23
+
24
+
For capacitive touch sensing, the touchscreen is composed of an array of
25
+
horizontal and vertical conductors (alternatively called rows/columns, X/Y
26
+
lines, or tx/rx). Mutual Capacitance measured is at the nodes where the
27
+
conductors cross. Alternatively, Self Capacitance measures the signal from each
28
+
column and row independently.
29
+
30
+
A touch input may be determined by comparing the raw capacitance measurement to
31
+
a no-touch reference (or "baseline") measurement:
32
+
33
+
Delta = Raw - Reference
34
+
35
+
The reference measurement takes account of variations in the capacitance across
36
+
the touch sensor matrix, for example manufacturing irregularities,
37
+
environmental or edge effects.
38
+
39
+
Querying Capabilities
40
+
=====================
41
+
42
+
Devices supporting the touch interface set the ``V4L2_CAP_VIDEO_CAPTURE`` flag
43
+
and the ``V4L2_CAP_TOUCH`` flag in the ``capabilities`` field of
44
+
:ref:`v4l2_capability <v4l2-capability>` returned by the
45
+
:ref:`VIDIOC_QUERYCAP` ioctl.
46
+
47
+
At least one of the read/write or streaming I/O methods must be
48
+
supported.
49
+
50
+
The formats supported by touch devices are documented in
51
+
:ref:`Touch Formats <tch-formats>`.
52
+
53
+
Data Format Negotiation
54
+
=======================
55
+
56
+
A touch device may support any I/O method.
+1
Documentation/media/uapi/v4l/devices.rst
+1
Documentation/media/uapi/v4l/devices.rst
+80
Documentation/media/uapi/v4l/pixfmt-tch-td08.rst
+80
Documentation/media/uapi/v4l/pixfmt-tch-td08.rst
···
1
+
.. -*- coding: utf-8; mode: rst -*-
2
+
3
+
.. _V4L2-TCH-FMT-DELTA-TD08:
4
+
5
+
********************************
6
+
V4L2_TCH_FMT_DELTA_TD08 ('TD08')
7
+
********************************
8
+
9
+
*man V4L2_TCH_FMT_DELTA_TD08(2)*
10
+
11
+
8-bit signed Touch Delta
12
+
13
+
Description
14
+
===========
15
+
16
+
This format represents delta data from a touch controller.
17
+
18
+
Delta values may range from -128 to 127. Typically the values will vary through
19
+
a small range depending on whether the sensor is touched or not. The full value
20
+
may be seen if one of the touchscreen nodes has a fault or the line is not
21
+
connected.
22
+
23
+
**Byte Order.**
24
+
Each cell is one byte.
25
+
26
+
27
+
28
+
.. flat-table::
29
+
:header-rows: 0
30
+
:stub-columns: 0
31
+
:widths: 2 1 1 1 1
32
+
33
+
34
+
- .. row 1
35
+
36
+
- start + 0:
37
+
38
+
- D'\ :sub:`00`
39
+
40
+
- D'\ :sub:`01`
41
+
42
+
- D'\ :sub:`02`
43
+
44
+
- D'\ :sub:`03`
45
+
46
+
- .. row 2
47
+
48
+
- start + 4:
49
+
50
+
- D'\ :sub:`10`
51
+
52
+
- D'\ :sub:`11`
53
+
54
+
- D'\ :sub:`12`
55
+
56
+
- D'\ :sub:`13`
57
+
58
+
- .. row 3
59
+
60
+
- start + 8:
61
+
62
+
- D'\ :sub:`20`
63
+
64
+
- D'\ :sub:`21`
65
+
66
+
- D'\ :sub:`22`
67
+
68
+
- D'\ :sub:`23`
69
+
70
+
- .. row 4
71
+
72
+
- start + 12:
73
+
74
+
- D'\ :sub:`30`
75
+
76
+
- D'\ :sub:`31`
77
+
78
+
- D'\ :sub:`32`
79
+
80
+
- D'\ :sub:`33`
+111
Documentation/media/uapi/v4l/pixfmt-tch-td16.rst
+111
Documentation/media/uapi/v4l/pixfmt-tch-td16.rst
···
1
+
.. -*- coding: utf-8; mode: rst -*-
2
+
3
+
.. _V4L2-TCH-FMT-DELTA-TD16:
4
+
5
+
********************************
6
+
V4L2_TCH_FMT_DELTA_TD16 ('TD16')
7
+
********************************
8
+
9
+
*man V4L2_TCH_FMT_DELTA_TD16(2)*
10
+
11
+
16-bit signed Touch Delta
12
+
13
+
14
+
Description
15
+
===========
16
+
17
+
This format represents delta data from a touch controller.
18
+
19
+
Delta values may range from -32768 to 32767. Typically the values will vary
20
+
through a small range depending on whether the sensor is touched or not. The
21
+
full value may be seen if one of the touchscreen nodes has a fault or the line
22
+
is not connected.
23
+
24
+
**Byte Order.**
25
+
Each cell is one byte.
26
+
27
+
.. flat-table::
28
+
:header-rows: 0
29
+
:stub-columns: 0
30
+
:widths: 2 1 1 1 1 1 1 1 1
31
+
32
+
33
+
- .. row 1
34
+
35
+
- start + 0:
36
+
37
+
- D'\ :sub:`00high`
38
+
39
+
- D'\ :sub:`00low`
40
+
41
+
- D'\ :sub:`01high`
42
+
43
+
- D'\ :sub:`01low`
44
+
45
+
- D'\ :sub:`02high`
46
+
47
+
- D'\ :sub:`02low`
48
+
49
+
- D'\ :sub:`03high`
50
+
51
+
- D'\ :sub:`03low`
52
+
53
+
- .. row 2
54
+
55
+
- start + 8:
56
+
57
+
- D'\ :sub:`10high`
58
+
59
+
- D'\ :sub:`10low`
60
+
61
+
- D'\ :sub:`11high`
62
+
63
+
- D'\ :sub:`11low`
64
+
65
+
- D'\ :sub:`12high`
66
+
67
+
- D'\ :sub:`12low`
68
+
69
+
- D'\ :sub:`13high`
70
+
71
+
- D'\ :sub:`13low`
72
+
73
+
- .. row 3
74
+
75
+
- start + 16:
76
+
77
+
- D'\ :sub:`20high`
78
+
79
+
- D'\ :sub:`20low`
80
+
81
+
- D'\ :sub:`21high`
82
+
83
+
- D'\ :sub:`21low`
84
+
85
+
- D'\ :sub:`22high`
86
+
87
+
- D'\ :sub:`22low`
88
+
89
+
- D'\ :sub:`23high`
90
+
91
+
- D'\ :sub:`23low`
92
+
93
+
- .. row 4
94
+
95
+
- start + 24:
96
+
97
+
- D'\ :sub:`30high`
98
+
99
+
- D'\ :sub:`30low`
100
+
101
+
- D'\ :sub:`31high`
102
+
103
+
- D'\ :sub:`31low`
104
+
105
+
- D'\ :sub:`32high`
106
+
107
+
- D'\ :sub:`32low`
108
+
109
+
- D'\ :sub:`33high`
110
+
111
+
- D'\ :sub:`33low`
+78
Documentation/media/uapi/v4l/pixfmt-tch-tu08.rst
+78
Documentation/media/uapi/v4l/pixfmt-tch-tu08.rst
···
1
+
.. -*- coding: utf-8; mode: rst -*-
2
+
3
+
.. _V4L2-TCH-FMT-TU08:
4
+
5
+
**************************
6
+
V4L2_TCH_FMT_TU08 ('TU08')
7
+
**************************
8
+
9
+
*man V4L2_TCH_FMT_TU08(2)*
10
+
11
+
8-bit unsigned raw touch data
12
+
13
+
Description
14
+
===========
15
+
16
+
This format represents unsigned 8-bit data from a touch controller.
17
+
18
+
This may be used for output for raw and reference data. Values may range from
19
+
0 to 255.
20
+
21
+
**Byte Order.**
22
+
Each cell is one byte.
23
+
24
+
25
+
26
+
.. flat-table::
27
+
:header-rows: 0
28
+
:stub-columns: 0
29
+
:widths: 2 1 1 1 1
30
+
31
+
32
+
- .. row 1
33
+
34
+
- start + 0:
35
+
36
+
- R'\ :sub:`00`
37
+
38
+
- R'\ :sub:`01`
39
+
40
+
- R'\ :sub:`02`
41
+
42
+
- R'\ :sub:`03`
43
+
44
+
- .. row 2
45
+
46
+
- start + 4:
47
+
48
+
- R'\ :sub:`10`
49
+
50
+
- R'\ :sub:`11`
51
+
52
+
- R'\ :sub:`12`
53
+
54
+
- R'\ :sub:`13`
55
+
56
+
- .. row 3
57
+
58
+
- start + 8:
59
+
60
+
- R'\ :sub:`20`
61
+
62
+
- R'\ :sub:`21`
63
+
64
+
- R'\ :sub:`22`
65
+
66
+
- R'\ :sub:`23`
67
+
68
+
- .. row 4
69
+
70
+
- start + 12:
71
+
72
+
- R'\ :sub:`30`
73
+
74
+
- R'\ :sub:`31`
75
+
76
+
- R'\ :sub:`32`
77
+
78
+
- R'\ :sub:`33`
+110
Documentation/media/uapi/v4l/pixfmt-tch-tu16.rst
+110
Documentation/media/uapi/v4l/pixfmt-tch-tu16.rst
···
1
+
.. -*- coding: utf-8; mode: rst -*-
2
+
3
+
.. _V4L2-TCH-FMT-TU16:
4
+
5
+
********************************
6
+
V4L2_TCH_FMT_TU16 ('TU16')
7
+
********************************
8
+
9
+
*man V4L2_TCH_FMT_TU16(2)*
10
+
11
+
16-bit unsigned raw touch data
12
+
13
+
14
+
Description
15
+
===========
16
+
17
+
This format represents unsigned 16-bit data from a touch controller.
18
+
19
+
This may be used for output for raw and reference data. Values may range from
20
+
0 to 65535.
21
+
22
+
**Byte Order.**
23
+
Each cell is one byte.
24
+
25
+
26
+
.. flat-table::
27
+
:header-rows: 0
28
+
:stub-columns: 0
29
+
:widths: 2 1 1 1 1 1 1 1 1
30
+
31
+
32
+
- .. row 1
33
+
34
+
- start + 0:
35
+
36
+
- R'\ :sub:`00high`
37
+
38
+
- R'\ :sub:`00low`
39
+
40
+
- R'\ :sub:`01high`
41
+
42
+
- R'\ :sub:`01low`
43
+
44
+
- R'\ :sub:`02high`
45
+
46
+
- R'\ :sub:`02low`
47
+
48
+
- R'\ :sub:`03high`
49
+
50
+
- R'\ :sub:`03low`
51
+
52
+
- .. row 2
53
+
54
+
- start + 8:
55
+
56
+
- R'\ :sub:`10high`
57
+
58
+
- R'\ :sub:`10low`
59
+
60
+
- R'\ :sub:`11high`
61
+
62
+
- R'\ :sub:`11low`
63
+
64
+
- R'\ :sub:`12high`
65
+
66
+
- R'\ :sub:`12low`
67
+
68
+
- R'\ :sub:`13high`
69
+
70
+
- R'\ :sub:`13low`
71
+
72
+
- .. row 3
73
+
74
+
- start + 16:
75
+
76
+
- R'\ :sub:`20high`
77
+
78
+
- R'\ :sub:`20low`
79
+
80
+
- R'\ :sub:`21high`
81
+
82
+
- R'\ :sub:`21low`
83
+
84
+
- R'\ :sub:`22high`
85
+
86
+
- R'\ :sub:`22low`
87
+
88
+
- R'\ :sub:`23high`
89
+
90
+
- R'\ :sub:`23low`
91
+
92
+
- .. row 4
93
+
94
+
- start + 24:
95
+
96
+
- R'\ :sub:`30high`
97
+
98
+
- R'\ :sub:`30low`
99
+
100
+
- R'\ :sub:`31high`
101
+
102
+
- R'\ :sub:`31low`
103
+
104
+
- R'\ :sub:`32high`
105
+
106
+
- R'\ :sub:`32low`
107
+
108
+
- R'\ :sub:`33high`
109
+
110
+
- R'\ :sub:`33low`
+1
Documentation/media/uapi/v4l/pixfmt.rst
+1
Documentation/media/uapi/v4l/pixfmt.rst
+18
Documentation/media/uapi/v4l/tch-formats.rst
+18
Documentation/media/uapi/v4l/tch-formats.rst
···
1
+
.. -*- coding: utf-8; mode: rst -*-
2
+
3
+
.. _tch-formats:
4
+
5
+
*************
6
+
Touch Formats
7
+
*************
8
+
9
+
These formats are used for :ref:`touch` interface only.
10
+
11
+
12
+
.. toctree::
13
+
:maxdepth: 1
14
+
15
+
pixfmt-tch-td16
16
+
pixfmt-tch-td08
17
+
pixfmt-tch-tu16
18
+
pixfmt-tch-tu08
+8
Documentation/media/uapi/v4l/vidioc-enuminput.rst
+8
Documentation/media/uapi/v4l/vidioc-enuminput.rst
···
175
175
- Analog baseband input, for example CVBS / Composite Video,
176
176
S-Video, RGB.
177
177
178
+
- .. row 3
179
+
180
+
- ``V4L2_INPUT_TYPE_TOUCH``
181
+
182
+
- 3
183
+
184
+
- This input is a touch device for capturing raw touch data.
185
+
178
186
179
187
180
188
.. tabularcolumns:: |p{4.8cm}|p{2.6cm}|p{10.1cm}|
+8
Documentation/media/uapi/v4l/vidioc-querycap.rst
+8
Documentation/media/uapi/v4l/vidioc-querycap.rst
+2
Documentation/media/videodev2.h.rst.exceptions
+2
Documentation/media/videodev2.h.rst.exceptions
···
152
152
replace define V4L2_CAP_ASYNCIO device-capabilities
153
153
replace define V4L2_CAP_STREAMING device-capabilities
154
154
replace define V4L2_CAP_DEVICE_CAPS device-capabilities
155
+
replace define V4L2_CAP_TOUCH device-capabilities
155
156
156
157
# V4L2 pix flags
157
158
replace define V4L2_PIX_FMT_PRIV_MAGIC v4l2-pix-format
···
286
285
287
286
replace define V4L2_INPUT_TYPE_TUNER input-type
288
287
replace define V4L2_INPUT_TYPE_CAMERA input-type
288
+
replace define V4L2_INPUT_TYPE_TOUCH input-type
289
289
290
290
replace define V4L2_IN_ST_NO_POWER input-status
291
291
replace define V4L2_IN_ST_NO_SIGNAL input-status