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
  30
  31 Description
  32 ===========
  33
  34 To find out which data services are supported by a sliced VBI capture or
  35 output 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
  38 driver fills in the remaining fields or returns an ``EINVAL`` error code if
  39 the 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
  47 .. c:type:: v4l2_sliced_vbi_cap
  48
  49 .. tabularcolumns:: |p{1.2cm}|p{4.2cm}|p{4.1cm}|p{4.0cm}|p{4.0cm}|
  50
  51 .. flat-table:: struct v4l2_sliced_vbi_cap
  52     :header-rows:  0
  53     :stub-columns: 0
  54     :widths:       3 3 2 2 2
  55
  56
  57     -  .. row 1
  58
  59        -  __u16
  60
  61        -  ``service_set``
  62
  63        -  :cspan:`2` A set of all data services supported by the driver.
  64
  65           Equal to the union of all elements of the ``service_lines`` array.
  66
  67     -  .. row 2
  68
  69        -  __u16
  70
  71        -  ``service_lines``\ [2][24]
  72
  73        -  :cspan:`2` Each element of this array contains a set of data
  74           services the hardware can look for or insert into a particular
  75           scan line. Data services are defined in :ref:`vbi-services`.
  76           Array indices map to ITU-R line numbers\ [#f1]_ as follows:
  77
  78     -  .. row 3
  79
  80        -
  81        -
  82        -  Element
  83
  84        -  525 line systems
  85
  86        -  625 line systems
  87
  88     -  .. row 4
  89
  90        -
  91        -
  92        -  ``service_lines``\ [0][1]
  93
  94        -  1
  95
  96        -  1
  97
  98     -  .. row 5
  99
 100        -
 101        -
 102        -  ``service_lines``\ [0][23]
 103
 104        -  23
 105
 106        -  23
 107
 108     -  .. row 6
 109
 110        -
 111        -
 112        -  ``service_lines``\ [1][1]
 113
 114        -  264
 115
 116        -  314
 117
 118     -  .. row 7
 119
 120        -
 121        -
 122        -  ``service_lines``\ [1][23]
 123
 124        -  286
 125
 126        -  336
 127
 128     -  .. row 8
 129
 130        -
 131
 132     -  .. row 9
 133
 134        -
 135        -
 136        -  :cspan:`2` The number of VBI lines the hardware can capture or
 137           output per frame, or the number of services it can identify on a
 138           given line may be limited. For example on PAL line 16 the hardware
 139           may be able to look for a VPS or Teletext signal, but not both at
 140           the same time. Applications can learn about these limits using the
 141           :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl as described in
 142           :ref:`sliced`.
 143
 144     -  .. row 10
 145
 146        -
 147
 148     -  .. row 11
 149
 150        -
 151        -
 152        -  :cspan:`2` Drivers must set ``service_lines`` [0][0] and
 153           ``service_lines``\ [1][0] to zero.
 154
 155     -  .. row 12
 156
 157        -  __u32
 158
 159        -  ``type``
 160
 161        -  Type of the data stream, see :c:type:`v4l2_buf_type`. Should be
 162           ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` or
 163           ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``.
 164
 165     -  .. row 13
 166
 167        -  __u32
 168
 169        -  ``reserved``\ [3]
 170
 171        -  :cspan:`2` This array is reserved for future extensions.
 172
 173           Applications and drivers must set it to zero.
 174
 175 .. [#f1]
 176
 177    See also :ref:`vbi-525` and :ref:`vbi-625`.
 178
 179
 180 .. raw:: latex
 181
 182     \begin{adjustbox}{width=\columnwidth}
 183
 184 .. tabularcolumns:: |p{5.0cm}|p{1.4cm}|p{3.0cm}|p{2.5cm}|p{9.0cm}|
 185
 186 .. _vbi-services:
 187
 188 .. flat-table:: Sliced VBI services
 189     :header-rows:  1
 190     :stub-columns: 0
 191     :widths:       2 1 1 2 2
 192
 193
 194     -  .. row 1
 195
 196        -  Symbol
 197
 198        -  Value
 199
 200        -  Reference
 201
 202        -  Lines, usually
 203
 204        -  Payload
 205
 206     -  .. row 2
 207
 208        -  ``V4L2_SLICED_TELETEXT_B`` (Teletext System B)
 209
 210        -  0x0001
 211
 212        -  :ref:`ets300706`,
 213
 214           :ref:`itu653`
 215
 216        -  PAL/SECAM line 7-22, 320-335 (second field 7-22)
 217
 218        -  Last 42 of the 45 byte Teletext packet, that is without clock
 219           run-in and framing code, lsb first transmitted.
 220
 221     -  .. row 3
 222
 223        -  ``V4L2_SLICED_VPS``
 224
 225        -  0x0400
 226
 227        -  :ref:`ets300231`
 228
 229        -  PAL line 16
 230
 231        -  Byte number 3 to 15 according to Figure 9 of ETS 300 231, lsb
 232           first transmitted.
 233
 234     -  .. row 4
 235
 236        -  ``V4L2_SLICED_CAPTION_525``
 237
 238        -  0x1000
 239
 240        -  :ref:`cea608`
 241
 242        -  NTSC line 21, 284 (second field 21)
 243
 244        -  Two bytes in transmission order, including parity bit, lsb first
 245           transmitted.
 246
 247     -  .. row 5
 248
 249        -  ``V4L2_SLICED_WSS_625``
 250
 251        -  0x4000
 252
 253        -  :ref:`en300294`,
 254
 255           :ref:`itu1119`
 256
 257        -  PAL/SECAM line 23
 258
 259        -
 260
 261           ::
 262
 263               Byte        0                 1
 264                    msb         lsb  msb           lsb
 265               Bit  7 6 5 4 3 2 1 0  x x 13 12 11 10 9
 266
 267     -  .. row 6
 268
 269        -  ``V4L2_SLICED_VBI_525``
 270
 271        -  0x1000
 272
 273        -  :cspan:`2` Set of services applicable to 525 line systems.
 274
 275     -  .. row 7
 276
 277        -  ``V4L2_SLICED_VBI_625``
 278
 279        -  0x4401
 280
 281        -  :cspan:`2` Set of services applicable to 625 line systems.
 282
 283 .. raw:: latex
 284
 285     \end{adjustbox}\newline\newline
 286
 287
 288 Return Value
 289 ============
 290
 291 On success 0 is returned, on error -1 and the ``errno`` variable is set
 292 appropriately. The generic error codes are described at the
 293 :ref:`Generic Error Codes <gen-errors>` chapter.
 294
 295 EINVAL
 296     The value in the ``type`` field is wrong.