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