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