GNU Linux-libre 4.14.295-gnu1
[releases.git] / Documentation / media / uapi / v4l / vidioc-g-sliced-vbi-cap.rst
1 .. -*- coding: utf-8; mode: rst -*-
2
3 .. _VIDIOC_G_SLICED_VBI_CAP:
4
5 *****************************
6 ioctl VIDIOC_G_SLICED_VBI_CAP
7 *****************************
8
9 Name
10 ====
11
12 VIDIOC_G_SLICED_VBI_CAP - Query sliced VBI capabilities
13
14
15 Synopsis
16 ========
17
18 .. c:function:: int ioctl( int fd, VIDIOC_G_SLICED_VBI_CAP, struct v4l2_sliced_vbi_cap *argp )
19     :name: VIDIOC_G_SLICED_VBI_CAP
20
21
22 Arguments
23 =========
24
25 ``fd``
26     File descriptor returned by :ref:`open() <func-open>`.
27
28 ``argp``
29     Pointer to struct :c:type:`v4l2_sliced_vbi_cap`.
30
31
32 Description
33 ===========
34
35 To find out which data services are supported by a sliced VBI capture or
36 output device, applications initialize the ``type`` field of a struct
37 :c:type:`v4l2_sliced_vbi_cap`, clear the
38 ``reserved`` array and call the :ref:`VIDIOC_G_SLICED_VBI_CAP <VIDIOC_G_SLICED_VBI_CAP>` ioctl. The
39 driver fills in the remaining fields or returns an ``EINVAL`` error code if
40 the sliced VBI API is unsupported or ``type`` is invalid.
41
42 .. note::
43
44    The ``type`` field was added, and the ioctl changed from read-only
45    to write-read, in Linux 2.6.19.
46
47
48 .. c:type:: v4l2_sliced_vbi_cap
49
50 .. tabularcolumns:: |p{1.2cm}|p{4.2cm}|p{4.1cm}|p{4.0cm}|p{4.0cm}|
51
52 .. flat-table:: struct v4l2_sliced_vbi_cap
53     :header-rows:  0
54     :stub-columns: 0
55     :widths:       3 3 2 2 2
56
57     * - __u16
58       - ``service_set``
59       - :cspan:`2` A set of all data services supported by the driver.
60
61         Equal to the union of all elements of the ``service_lines`` array.
62     * - __u16
63       - ``service_lines``\ [2][24]
64       - :cspan:`2` Each element of this array contains a set of data
65         services the hardware can look for or insert into a particular
66         scan line. Data services are defined in :ref:`vbi-services`.
67         Array indices map to ITU-R line numbers\ [#f1]_ as follows:
68     * -
69       -
70       - Element
71       - 525 line systems
72       - 625 line systems
73     * -
74       -
75       - ``service_lines``\ [0][1]
76       - 1
77       - 1
78     * -
79       -
80       - ``service_lines``\ [0][23]
81       - 23
82       - 23
83     * -
84       -
85       - ``service_lines``\ [1][1]
86       - 264
87       - 314
88     * -
89       -
90       - ``service_lines``\ [1][23]
91       - 286
92       - 336
93     * -
94     * -
95       -
96       - :cspan:`2` The number of VBI lines the hardware can capture or
97         output per frame, or the number of services it can identify on a
98         given line may be limited. For example on PAL line 16 the hardware
99         may be able to look for a VPS or Teletext signal, but not both at
100         the same time. Applications can learn about these limits using the
101         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl as described in
102         :ref:`sliced`.
103     * -
104     * -
105       -
106       - :cspan:`2` Drivers must set ``service_lines`` [0][0] and
107         ``service_lines``\ [1][0] to zero.
108     * - __u32
109       - ``type``
110       - Type of the data stream, see :c:type:`v4l2_buf_type`. Should be
111         ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` or
112         ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``.
113     * - __u32
114       - ``reserved``\ [3]
115       - :cspan:`2` This array is reserved for future extensions.
116
117         Applications and drivers must set it to zero.
118
119 .. [#f1]
120
121    See also :ref:`vbi-525` and :ref:`vbi-625`.
122
123
124 .. raw:: latex
125
126     \scriptsize
127
128 .. tabularcolumns:: |p{3.5cm}|p{1.0cm}|p{2.0cm}|p{2.0cm}|p{8.0cm}|
129
130 .. _vbi-services:
131
132 .. flat-table:: Sliced VBI services
133     :header-rows:  1
134     :stub-columns: 0
135     :widths:       2 1 1 2 2
136
137     * - Symbol
138       - Value
139       - Reference
140       - Lines, usually
141       - Payload
142     * - ``V4L2_SLICED_TELETEXT_B`` (Teletext System B)
143       - 0x0001
144       - :ref:`ets300706`,
145
146         :ref:`itu653`
147       - PAL/SECAM line 7-22, 320-335 (second field 7-22)
148       - Last 42 of the 45 byte Teletext packet, that is without clock
149         run-in and framing code, lsb first transmitted.
150     * - ``V4L2_SLICED_VPS``
151       - 0x0400
152       - :ref:`ets300231`
153       - PAL line 16
154       - Byte number 3 to 15 according to Figure 9 of ETS 300 231, lsb
155         first transmitted.
156     * - ``V4L2_SLICED_CAPTION_525``
157       - 0x1000
158       - :ref:`cea608`
159       - NTSC line 21, 284 (second field 21)
160       - Two bytes in transmission order, including parity bit, lsb first
161         transmitted.
162     * - ``V4L2_SLICED_WSS_625``
163       - 0x4000
164       - :ref:`en300294`,
165
166         :ref:`itu1119`
167       - PAL/SECAM line 23
168       -
169
170         ::
171
172             Byte        0                 1
173                  msb         lsb  msb           lsb
174             Bit  7 6 5 4 3 2 1 0  x x 13 12 11 10 9
175     * - ``V4L2_SLICED_VBI_525``
176       - 0x1000
177       - :cspan:`2` Set of services applicable to 525 line systems.
178     * - ``V4L2_SLICED_VBI_625``
179       - 0x4401
180       - :cspan:`2` Set of services applicable to 625 line systems.
181
182 .. raw:: latex
183
184     \normalsize
185
186
187 Return Value
188 ============
189
190 On success 0 is returned, on error -1 and the ``errno`` variable is set
191 appropriately. The generic error codes are described at the
192 :ref:`Generic Error Codes <gen-errors>` chapter.
193
194 EINVAL
195     The value in the ``type`` field is wrong.