Documentation/media/uapi/v4l/dev-raw-vbi.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _raw-vbi:
   4
   5 **********************
   6 Raw VBI Data Interface
   7 **********************
   8
   9 VBI is an abbreviation of Vertical Blanking Interval, a gap in the
  10 sequence of lines of an analog video signal. During VBI no picture
  11 information is transmitted, allowing some time while the electron beam
  12 of a cathode ray tube TV returns to the top of the screen. Using an
  13 oscilloscope you will find here the vertical synchronization pulses and
  14 short data packages ASK modulated [#f1]_ onto the video signal. These are
  15 transmissions of services such as Teletext or Closed Caption.
  16
  17 Subject of this interface type is raw VBI data, as sampled off a video
  18 signal, or to be added to a signal for output. The data format is
  19 similar to uncompressed video images, a number of lines times a number
  20 of samples per line, we call this a VBI image.
  21
  22 Conventionally V4L2 VBI devices are accessed through character device
  23 special files named ``/dev/vbi`` and ``/dev/vbi0`` to ``/dev/vbi31``
  24 with major number 81 and minor numbers 224 to 255. ``/dev/vbi`` is
  25 typically a symbolic link to the preferred VBI device. This convention
  26 applies to both input and output devices.
  27
  28 To address the problems of finding related video and VBI devices VBI
  29 capturing and output is also available as device function under
  30 ``/dev/video``. To capture or output raw VBI data with these devices
  31 applications must call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
  32 Accessed as ``/dev/vbi``, raw VBI capturing or output is the default
  33 device function.
  34
  35
  36 Querying Capabilities
  37 =====================
  38
  39 Devices supporting the raw VBI capturing or output API set the
  40 ``V4L2_CAP_VBI_CAPTURE`` or ``V4L2_CAP_VBI_OUTPUT`` flags, respectively,
  41 in the ``capabilities`` field of struct
  42 :ref:`v4l2_capability <v4l2-capability>` returned by the
  43 :ref:`VIDIOC_QUERYCAP` ioctl. At least one of the
  44 read/write, streaming or asynchronous I/O methods must be supported. VBI
  45 devices may or may not have a tuner or modulator.
  46
  47
  48 Supplemental Functions
  49 ======================
  50
  51 VBI devices shall support :ref:`video input or output <video>`,
  52 :ref:`tuner or modulator <tuner>`, and :ref:`controls <control>`
  53 ioctls as needed. The :ref:`video standard <standard>` ioctls provide
  54 information vital to program a VBI device, therefore must be supported.
  55
  56
  57 Raw VBI Format Negotiation
  58 ==========================
  59
  60 Raw VBI sampling abilities can vary, in particular the sampling
  61 frequency. To properly interpret the data V4L2 specifies an ioctl to
  62 query the sampling parameters. Moreover, to allow for some flexibility
  63 applications can also suggest different parameters.
  64
  65 As usual these parameters are *not* reset at :ref:`open() <func-open>`
  66 time to permit Unix tool chains, programming a device and then reading
  67 from it as if it was a plain file. Well written V4L2 applications should
  68 always ensure they really get what they want, requesting reasonable
  69 parameters and then checking if the actual parameters are suitable.
  70
  71 To query the current raw VBI capture parameters applications set the
  72 ``type`` field of a struct :ref:`v4l2_format <v4l2-format>` to
  73 ``V4L2_BUF_TYPE_VBI_CAPTURE`` or ``V4L2_BUF_TYPE_VBI_OUTPUT``, and call
  74 the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this
  75 structure. Drivers fill the struct
  76 :ref:`v4l2_vbi_format <v4l2-vbi-format>` ``vbi`` member of the
  77 ``fmt`` union.
  78
  79 To request different parameters applications set the ``type`` field of a
  80 struct :ref:`v4l2_format <v4l2-format>` as above and initialize all
  81 fields of the struct :ref:`v4l2_vbi_format <v4l2-vbi-format>`
  82 ``vbi`` member of the ``fmt`` union, or better just modify the results
  83 of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
  84 ioctl with a pointer to this structure. Drivers return an ``EINVAL`` error
  85 code only when the given parameters are ambiguous, otherwise they modify
  86 the parameters according to the hardware capabilities and return the
  87 actual parameters. When the driver allocates resources at this point, it
  88 may return an ``EBUSY`` error code to indicate the returned parameters are
  89 valid but the required resources are currently not available. That may
  90 happen for instance when the video and VBI areas to capture would
  91 overlap, or when the driver supports multiple opens and another process
  92 already requested VBI capturing or output. Anyway, applications must
  93 expect other resource allocation points which may return ``EBUSY``, at the
  94 :ref:`VIDIOC_STREAMON` ioctl and the first :ref:`read() <func-read>`
  95 , :ref:`write() <func-write>` and :ref:`select() <func-select>` calls.
  96
  97 VBI devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
  98 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all requests
  99 and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does.
 100 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional.
 101
 102 .. tabularcolumns:: |p{2.4cm}|p{4.4cm}|p{10.7cm}|
 103
 104 .. _v4l2-vbi-format:
 105
 106 .. cssclass:: longtable
 107
 108 .. flat-table:: struct v4l2_vbi_format
 109     :header-rows:  0
 110     :stub-columns: 0
 111     :widths:       1 1 2
 112
 113
 114     -  .. row 1
 115
 116        -  __u32
 117
 118        -  ``sampling_rate``
 119
 120        -  Samples per second, i. e. unit 1 Hz.
 121
 122     -  .. row 2
 123
 124        -  __u32
 125
 126        -  ``offset``
 127
 128        -  Horizontal offset of the VBI image, relative to the leading edge
 129           of the line synchronization pulse and counted in samples: The
 130           first sample in the VBI image will be located ``offset`` /
 131           ``sampling_rate`` seconds following the leading edge. See also
 132           :ref:`vbi-hsync`.
 133
 134     -  .. row 3
 135
 136        -  __u32
 137
 138        -  ``samples_per_line``
 139
 140        -
 141
 142     -  .. row 4
 143
 144        -  __u32
 145
 146        -  ``sample_format``
 147
 148        -  Defines the sample format as in :ref:`pixfmt`, a
 149           four-character-code. [#f2]_ Usually this is ``V4L2_PIX_FMT_GREY``,
 150           i. e. each sample consists of 8 bits with lower values oriented
 151           towards the black level. Do not assume any other correlation of
 152           values with the signal level. For example, the MSB does not
 153           necessarily indicate if the signal is 'high' or 'low' because 128
 154           may not be the mean value of the signal. Drivers shall not convert
 155           the sample format by software.
 156
 157     -  .. row 5
 158
 159        -  __u32
 160
 161        -  ``start``\ [#f2]_
 162
 163        -  This is the scanning system line number associated with the first
 164           line of the VBI image, of the first and the second field
 165           respectively. See :ref:`vbi-525` and :ref:`vbi-625` for valid
 166           values. The ``V4L2_VBI_ITU_525_F1_START``,
 167           ``V4L2_VBI_ITU_525_F2_START``, ``V4L2_VBI_ITU_625_F1_START`` and
 168           ``V4L2_VBI_ITU_625_F2_START`` defines give the start line numbers
 169           for each field for each 525 or 625 line format as a convenience.
 170           Don't forget that ITU line numbering starts at 1, not 0. VBI input
 171           drivers can return start values 0 if the hardware cannot reliable
 172           identify scanning lines, VBI acquisition may not require this
 173           information.
 174
 175     -  .. row 6
 176
 177        -  __u32
 178
 179        -  ``count``\ [#f2]_
 180
 181        -  The number of lines in the first and second field image,
 182           respectively.
 183
 184     -  .. row 7
 185
 186        -  :cspan:`2`
 187
 188           Drivers should be as flexibility as possible. For example, it may
 189           be possible to extend or move the VBI capture window down to the
 190           picture area, implementing a 'full field mode' to capture data
 191           service transmissions embedded in the picture.
 192
 193           An application can set the first or second ``count`` value to zero
 194           if no data is required from the respective field; ``count``\ [1]
 195           if the scanning system is progressive, i. e. not interlaced. The
 196           corresponding start value shall be ignored by the application and
 197           driver. Anyway, drivers may not support single field capturing and
 198           return both count values non-zero.
 199
 200           Both ``count`` values set to zero, or line numbers are outside the
 201           bounds depicted\ [#f4]_, or a field image covering lines of two
 202           fields, are invalid and shall not be returned by the driver.
 203
 204           To initialize the ``start`` and ``count`` fields, applications
 205           must first determine the current video standard selection. The
 206           :ref:`v4l2_std_id <v4l2-std-id>` or the ``framelines`` field
 207           of struct :ref:`v4l2_standard <v4l2-standard>` can be evaluated
 208           for this purpose.
 209
 210     -  .. row 8
 211
 212        -  __u32
 213
 214        -  ``flags``
 215
 216        -  See :ref:`vbifmt-flags` below. Currently only drivers set flags,
 217           applications must set this field to zero.
 218
 219     -  .. row 9
 220
 221        -  __u32
 222
 223        -  ``reserved``\ [#f2]_
 224
 225        -  This array is reserved for future extensions. Drivers and
 226           applications must set it to zero.
 227
 228
 229 .. tabularcolumns:: |p{4.0cm}|p{1.5cm}|p{12.0cm}|
 230
 231 .. _vbifmt-flags:
 232
 233 .. flat-table:: Raw VBI Format Flags
 234     :header-rows:  0
 235     :stub-columns: 0
 236     :widths:       3 1 4
 237
 238
 239     -  .. row 1
 240
 241        -  ``V4L2_VBI_UNSYNC``
 242
 243        -  0x0001
 244
 245        -  This flag indicates hardware which does not properly distinguish
 246           between fields. Normally the VBI image stores the first field
 247           (lower scanning line numbers) first in memory. This may be a top
 248           or bottom field depending on the video standard. When this flag is
 249           set the first or second field may be stored first, however the
 250           fields are still in correct temporal order with the older field
 251           first in memory. [#f3]_
 252
 253     -  .. row 2
 254
 255        -  ``V4L2_VBI_INTERLACED``
 256
 257        -  0x0002
 258
 259        -  By default the two field images will be passed sequentially; all
 260           lines of the first field followed by all lines of the second field
 261           (compare :ref:`field-order` ``V4L2_FIELD_SEQ_TB`` and
 262           ``V4L2_FIELD_SEQ_BT``, whether the top or bottom field is first in
 263           memory depends on the video standard). When this flag is set, the
 264           two fields are interlaced (cf. ``V4L2_FIELD_INTERLACED``). The
 265           first line of the first field followed by the first line of the
 266           second field, then the two second lines, and so on. Such a layout
 267           may be necessary when the hardware has been programmed to capture
 268           or output interlaced video images and is unable to separate the
 269           fields for VBI capturing at the same time. For simplicity setting
 270           this flag implies that both ``count`` values are equal and
 271           non-zero.
 272
 273
 274
 275 .. _vbi-hsync:
 276
 277 .. figure::  dev-raw-vbi_files/vbi_hsync.*
 278     :alt:    vbi_hsync.pdf / vbi_hsync.gif
 279     :align:  center
 280
 281     **Figure 4.1. Line synchronization**
 282
 283
 284 .. _vbi-525:
 285
 286 .. figure::  dev-raw-vbi_files/vbi_525.*
 287     :alt:    vbi_525.pdf / vbi_525.gif
 288     :align:  center
 289
 290     **Figure 4.2. ITU-R 525 line numbering (M/NTSC and M/PAL)**
 291
 292
 293
 294 .. _vbi-625:
 295
 296 .. figure::  dev-raw-vbi_files/vbi_625.*
 297     :alt:    vbi_625.pdf / vbi_625.gif
 298     :align:  center
 299
 300     **Figure 4.3. ITU-R 625 line numbering**
 301
 302
 303
 304 Remember the VBI image format depends on the selected video standard,
 305 therefore the application must choose a new standard or query the
 306 current standard first. Attempts to read or write data ahead of format
 307 negotiation, or after switching the video standard which may invalidate
 308 the negotiated VBI parameters, should be refused by the driver. A format
 309 change during active I/O is not permitted.
 310
 311
 312 Reading and writing VBI images
 313 ==============================
 314
 315 To assure synchronization with the field number and easier
 316 implementation, the smallest unit of data passed at a time is one frame,
 317 consisting of two fields of VBI images immediately following in memory.
 318
 319 The total size of a frame computes as follows:
 320
 321
 322 .. code-block:: c
 323
 324     (count[0] + count[1]) * samples_per_line * sample size in bytes
 325
 326 The sample size is most likely always one byte, applications must check
 327 the ``sample_format`` field though, to function properly with other
 328 drivers.
 329
 330 A VBI device may support :ref:`read/write <rw>` and/or streaming
 331 (:ref:`memory mapping <mmap>` or :ref:`user pointer <userp>`) I/O.
 332 The latter bears the possibility of synchronizing video and VBI data by
 333 using buffer timestamps.
 334
 335 Remember the :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` ioctl and the
 336 first :ref:`read() <func-read>`, :ref:`write() <func-write>` and
 337 :ref:`select() <func-select>` call can be resource allocation
 338 points returning an ``EBUSY`` error code if the required hardware resources
 339 are temporarily unavailable, for example the device is already in use by
 340 another process.
 341
 342 .. [#f1]
 343    ASK: Amplitude-Shift Keying. A high signal level represents a '1'
 344    bit, a low level a '0' bit.
 345
 346 .. [#f2]
 347    A few devices may be unable to sample VBI data at all but can extend
 348    the video capture window to the VBI region.
 349
 350 .. [#f3]
 351    Most VBI services transmit on both fields, but some have different
 352    semantics depending on the field number. These cannot be reliable
 353    decoded or encoded when ``V4L2_VBI_UNSYNC`` is set.
 354
 355 .. [#f4]
 356    The valid values ar shown at :ref:`vbi-525` and :ref:`vbi-625`.