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