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

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