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