vidioc-g-sliced-vbi-cap.rst

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