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