Documentation/DocBook/media/v4l/dev-raw-vbi.xml

   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 capabilites 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.&nbsp;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.&nbsp;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. VBI input drivers can
 154 return start values 0 if the hardware cannot reliable identify
 155 scanning lines, VBI acquisition may not require this
 156 information.</entry>
 157             </row>
 158             <row>
 159               <entry>__u32</entry>
 160               <entry><structfield>count</structfield>[2]</entry>
 161               <entry>The number of lines in the first and second
 162 field image, respectively.</entry>
 163           </row>
 164           <row>
 165             <entry spanname="hspan"><para>Drivers should be as
 166 flexibility as possible. For example, it may be possible to extend or
 167 move the VBI capture window down to the picture area, implementing a
 168 'full field mode' to capture data service transmissions embedded in
 169 the picture.</para><para>An application can set the first or second
 170 <structfield>count</structfield> value to zero if no data is required
 171 from the respective field; <structfield>count</structfield>[1] if the
 172 scanning system is progressive, &ie; not interlaced. The
 173 corresponding start value shall be ignored by the application and
 174 driver. Anyway, drivers may not support single field capturing and
 175 return both count values non-zero.</para><para>Both
 176 <structfield>count</structfield> values set to zero, or line numbers
 177 outside the bounds depicted in <xref linkend="vbi-525" /> and <xref
 178                     linkend="vbi-625" />, or a field image covering
 179 lines of two fields, are invalid and shall not be returned by the
 180 driver.</para><para>To initialize the <structfield>start</structfield>
 181 and <structfield>count</structfield> fields, applications must first
 182 determine the current video standard selection. The &v4l2-std-id; or
 183 the <structfield>framelines</structfield> field of &v4l2-standard; can
 184 be evaluated for this purpose.</para></entry>
 185             </row>
 186             <row>
 187               <entry>__u32</entry>
 188               <entry><structfield>flags</structfield></entry>
 189               <entry>See <xref linkend="vbifmt-flags" /> below. Currently
 190 only drivers set flags, applications must set this field to
 191 zero.</entry>
 192             </row>
 193             <row>
 194               <entry>__u32</entry>
 195               <entry><structfield>reserved</structfield>[2]</entry>
 196               <entry>This array is reserved for future extensions.
 197 Drivers and applications must set it to zero.</entry>
 198             </row>
 199           </tbody>
 200         </tgroup>
 201       </table>
 202
 203       <table pgwide="1" frame="none" id="vbifmt-flags">
 204         <title>Raw VBI Format Flags</title>
 205         <tgroup cols="3">
 206           &cs-def;
 207           <tbody valign="top">
 208             <row>
 209               <entry><constant>V4L2_VBI_UNSYNC</constant></entry>
 210               <entry>0x0001</entry>
 211               <entry><para>This flag indicates hardware which does not
 212 properly distinguish between fields. Normally the VBI image stores the
 213 first field (lower scanning line numbers) first in memory. This may be
 214 a top or bottom field depending on the video standard. When this flag
 215 is set the first or second field may be stored first, however the
 216 fields are still in correct temporal order with the older field first
 217 in memory.<footnote>
 218                   <para>Most VBI services transmit on both fields, but
 219 some have different semantics depending on the field number. These
 220 cannot be reliable decoded or encoded when
 221 <constant>V4L2_VBI_UNSYNC</constant> is set.</para>
 222                 </footnote></para></entry>
 223             </row>
 224             <row>
 225               <entry><constant>V4L2_VBI_INTERLACED</constant></entry>
 226               <entry>0x0002</entry>
 227               <entry>By default the two field images will be passed
 228 sequentially; all lines of the first field followed by all lines of
 229 the second field (compare <xref linkend="field-order" />
 230 <constant>V4L2_FIELD_SEQ_TB</constant> and
 231 <constant>V4L2_FIELD_SEQ_BT</constant>, whether the top or bottom
 232 field is first in memory depends on the video standard). When this
 233 flag is set, the two fields are interlaced (cf.
 234 <constant>V4L2_FIELD_INTERLACED</constant>). The first line of the
 235 first field followed by the first line of the second field, then the
 236 two second lines, and so on. Such a layout may be necessary when the
 237 hardware has been programmed to capture or output interlaced video
 238 images and is unable to separate the fields for VBI capturing at
 239 the same time. For simplicity setting this flag implies that both
 240 <structfield>count</structfield> values are equal and non-zero.</entry>
 241             </row>
 242           </tbody>
 243         </tgroup>
 244       </table>
 245
 246       <figure id="vbi-hsync">
 247         <title>Line synchronization</title>
 248         <mediaobject>
 249           <imageobject>
 250             <imagedata fileref="vbi_hsync.pdf" format="PS" />
 251           </imageobject>
 252           <imageobject>
 253             <imagedata fileref="vbi_hsync.gif" format="GIF" />
 254           </imageobject>
 255           <textobject>
 256             <phrase>Line synchronization diagram</phrase>
 257           </textobject>
 258         </mediaobject>
 259       </figure>
 260
 261       <figure id="vbi-525">
 262         <title>ITU-R 525 line numbering (M/NTSC and M/PAL)</title>
 263         <mediaobject>
 264           <imageobject>
 265             <imagedata fileref="vbi_525.pdf" format="PS" />
 266           </imageobject>
 267           <imageobject>
 268             <imagedata fileref="vbi_525.gif" format="GIF" />
 269           </imageobject>
 270           <textobject>
 271             <phrase>NTSC field synchronization diagram</phrase>
 272           </textobject>
 273           <caption>
 274             <para>(1) For the purpose of this specification field 2
 275 starts in line 264 and not 263.5 because half line capturing is not
 276 supported.</para>
 277           </caption>
 278         </mediaobject>
 279       </figure>
 280
 281       <figure id="vbi-625">
 282         <title>ITU-R 625 line numbering</title>
 283         <mediaobject>
 284           <imageobject>
 285             <imagedata fileref="vbi_625.pdf" format="PS" />
 286           </imageobject>
 287           <imageobject>
 288             <imagedata fileref="vbi_625.gif" format="GIF" />
 289           </imageobject>
 290           <textobject>
 291             <phrase>PAL/SECAM field synchronization diagram</phrase>
 292           </textobject>
 293           <caption>
 294             <para>(1) For the purpose of this specification field 2
 295 starts in line 314 and not 313.5 because half line capturing is not
 296 supported.</para>
 297           </caption>
 298         </mediaobject>
 299       </figure>
 300
 301       <para>Remember the VBI image format depends on the selected
 302 video standard, therefore the application must choose a new standard or
 303 query the current standard first. Attempts to read or write data ahead
 304 of format negotiation, or after switching the video standard which may
 305 invalidate the negotiated VBI parameters, should be refused by the
 306 driver. A format change during active I/O is not permitted.</para>
 307     </section>
 308
 309     <section>
 310       <title>Reading and writing VBI images</title>
 311
 312       <para>To assure synchronization with the field number and easier
 313 implementation, the smallest unit of data passed at a time is one
 314 frame, consisting of two fields of VBI images immediately following in
 315 memory.</para>
 316
 317       <para>The total size of a frame computes as follows:</para>
 318
 319       <programlisting>
 320 (<structfield>count</structfield>[0] + <structfield>count</structfield>[1]) *
 321 <structfield>samples_per_line</structfield> * sample size in bytes</programlisting>
 322
 323       <para>The sample size is most likely always one byte,
 324 applications must check the <structfield>sample_format</structfield>
 325 field though, to function properly with other drivers.</para>
 326
 327       <para>A VBI device may support <link
 328       linkend="rw">read/write</link> and/or streaming (<link
 329       linkend="mmap">memory mapping</link> or <link
 330       linkend="userp">user pointer</link>) I/O. The latter bears the
 331 possibility of synchronizing video and
 332 VBI data by using buffer timestamps.</para>
 333
 334       <para>Remember the &VIDIOC-STREAMON; ioctl and the first read(),
 335 write() and select() call can be resource allocation points returning
 336 an &EBUSY; if the required hardware resources are temporarily
 337 unavailable, for example the device is already in use by another
 338 process.</para>
 339   </section>
 340
 341   <!--
 342 Local Variables:
 343 mode: sgml
 344 sgml-parent-document: "v4l2.sgml"
 345 indent-tabs-mode: nil
 346 End:
 347   -->