diff options
Diffstat (limited to 'Documentation/DocBook/v4l/dev-raw-vbi.xml')
| -rw-r--r-- | Documentation/DocBook/v4l/dev-raw-vbi.xml | 347 |
1 files changed, 347 insertions, 0 deletions
diff --git a/Documentation/DocBook/v4l/dev-raw-vbi.xml b/Documentation/DocBook/v4l/dev-raw-vbi.xml new file mode 100644 index 00000000000..c5a70bdfaf2 --- /dev/null +++ b/Documentation/DocBook/v4l/dev-raw-vbi.xml @@ -0,0 +1,347 @@ + <title>Raw VBI Data Interface</title> + + <para>VBI is an abbreviation of Vertical Blanking Interval, a gap +in the sequence of lines of an analog video signal. During VBI +no picture information is transmitted, allowing some time while the +electron beam of a cathode ray tube TV returns to the top of the +screen. Using an oscilloscope you will find here the vertical +synchronization pulses and short data packages ASK +modulated<footnote><para>ASK: Amplitude-Shift Keying. A high signal +level represents a '1' bit, a low level a '0' bit.</para></footnote> +onto the video signal. These are transmissions of services such as +Teletext or Closed Caption.</para> + + <para>Subject of this interface type is raw VBI data, as sampled off +a video signal, or to be added to a signal for output. +The data format is similar to uncompressed video images, a number of +lines times a number of samples per line, we call this a VBI image.</para> + + <para>Conventionally V4L2 VBI devices are accessed through character +device special files named <filename>/dev/vbi</filename> and +<filename>/dev/vbi0</filename> to <filename>/dev/vbi31</filename> with +major number 81 and minor numbers 224 to 255. +<filename>/dev/vbi</filename> is typically a symbolic link to the +preferred VBI device. This convention applies to both input and output +devices.</para> + + <para>To address the problems of finding related video and VBI +devices VBI capturing and output is also available as device function +under <filename>/dev/video</filename>. To capture or output raw VBI +data with these devices applications must call the &VIDIOC-S-FMT; +ioctl. Accessed as <filename>/dev/vbi</filename>, raw VBI capturing +or output is the default device function.</para> + + <section> + <title>Querying Capabilities</title> + + <para>Devices supporting the raw VBI capturing or output API set +the <constant>V4L2_CAP_VBI_CAPTURE</constant> or +<constant>V4L2_CAP_VBI_OUTPUT</constant> flags, respectively, in the +<structfield>capabilities</structfield> field of &v4l2-capability; +returned by the &VIDIOC-QUERYCAP; ioctl. At least one of the +read/write, streaming or asynchronous I/O methods must be +supported. VBI devices may or may not have a tuner or modulator.</para> + </section> + + <section> + <title>Supplemental Functions</title> + + <para>VBI devices shall support <link linkend="video">video +input or output</link>, <link linkend="tuner">tuner or +modulator</link>, and <link linkend="control">controls</link> ioctls +as needed. The <link linkend="standard">video standard</link> ioctls provide +information vital to program a VBI device, therefore must be +supported.</para> + </section> + + <section> + <title>Raw VBI Format Negotiation</title> + + <para>Raw VBI sampling abilities can vary, in particular the +sampling frequency. To properly interpret the data V4L2 specifies an +ioctl to query the sampling parameters. Moreover, to allow for some +flexibility applications can also suggest different parameters.</para> + + <para>As usual these parameters are <emphasis>not</emphasis> +reset at &func-open; time to permit Unix tool chains, programming a +device and then reading from it as if it was a plain file. Well +written V4L2 applications should always ensure they really get what +they want, requesting reasonable parameters and then checking if the +actual parameters are suitable.</para> + + <para>To query the current raw VBI capture parameters +applications set the <structfield>type</structfield> field of a +&v4l2-format; to <constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant> or +<constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>, and call the +&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill +the &v4l2-vbi-format; <structfield>vbi</structfield> member of the +<structfield>fmt</structfield> union.</para> + + <para>To request different parameters applications set the +<structfield>type</structfield> field of a &v4l2-format; as above and +initialize all fields of the &v4l2-vbi-format; +<structfield>vbi</structfield> member of the +<structfield>fmt</structfield> union, or better just modify the +results of <constant>VIDIOC_G_FMT</constant>, and call the +&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers return +an &EINVAL; only when the given parameters are ambiguous, otherwise +they modify the parameters according to the hardware capabilites and +return the actual parameters. When the driver allocates resources at +this point, it may return an &EBUSY; to indicate the returned +parameters are valid but the required resources are currently not +available. That may happen for instance when the video and VBI areas +to capture would overlap, or when the driver supports multiple opens +and another process already requested VBI capturing or output. Anyway, +applications must expect other resource allocation points which may +return <errorcode>EBUSY</errorcode>, at the &VIDIOC-STREAMON; ioctl +and the first read(), write() and select() call.</para> + + <para>VBI devices must implement both the +<constant>VIDIOC_G_FMT</constant> and +<constant>VIDIOC_S_FMT</constant> ioctl, even if +<constant>VIDIOC_S_FMT</constant> ignores all requests and always +returns default parameters as <constant>VIDIOC_G_FMT</constant> does. +<constant>VIDIOC_TRY_FMT</constant> is optional.</para> + + <table pgwide="1" frame="none" id="v4l2-vbi-format"> + <title>struct <structname>v4l2_vbi_format</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>sampling_rate</structfield></entry> + <entry>Samples per second, i. e. unit 1 Hz.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>offset</structfield></entry> + <entry><para>Horizontal offset of the VBI image, +relative to the leading edge of the line synchronization pulse and +counted in samples: The first sample in the VBI image will be located +<structfield>offset</structfield> / +<structfield>sampling_rate</structfield> seconds following the leading +edge. See also <xref linkend="vbi-hsync" />.</para></entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>samples_per_line</structfield></entry> + <entry></entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>sample_format</structfield></entry> + <entry><para>Defines the sample format as in <xref +linkend="pixfmt" />, a four-character-code.<footnote> + <para>A few devices may be unable to +sample VBI data at all but can extend the video capture window to the +VBI region.</para> + </footnote> Usually this is +<constant>V4L2_PIX_FMT_GREY</constant>, i. e. each sample +consists of 8 bits with lower values oriented towards the black level. +Do not assume any other correlation of values with the signal level. +For example, the MSB does not necessarily indicate if the signal is +'high' or 'low' because 128 may not be the mean value of the +signal. Drivers shall not convert the sample format by software.</para></entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>start</structfield>[2]</entry> + <entry>This is the scanning system line number +associated with the first line of the VBI image, of the first and the +second field respectively. See <xref linkend="vbi-525" /> and +<xref linkend="vbi-625" /> for valid values. VBI input drivers can +return start values 0 if the hardware cannot reliable identify +scanning lines, VBI acquisition may not require this +information.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>count</structfield>[2]</entry> + <entry>The number of lines in the first and second +field image, respectively.</entry> + </row> + <row> + <entry spanname="hspan"><para>Drivers should be as +flexibility as possible. For example, it may be possible to extend or +move the VBI capture window down to the picture area, implementing a +'full field mode' to capture data service transmissions embedded in +the picture.</para><para>An application can set the first or second +<structfield>count</structfield> value to zero if no data is required +from the respective field; <structfield>count</structfield>[1] if the +scanning system is progressive, &ie; not interlaced. The +corresponding start value shall be ignored by the application and +driver. Anyway, drivers may not support single field capturing and +return both count values non-zero.</para><para>Both +<structfield>count</structfield> values set to zero, or line numbers +outside the bounds depicted in <xref linkend="vbi-525" /> and <xref + linkend="vbi-625" />, or a field image covering +lines of two fields, are invalid and shall not be returned by the +driver.</para><para>To initialize the <structfield>start</structfield> +and <structfield>count</structfield> fields, applications must first +determine the current video standard selection. The &v4l2-std-id; or +the <structfield>framelines</structfield> field of &v4l2-standard; can +be evaluated for this purpose.</para></entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>flags</structfield></entry> + <entry>See <xref linkend="vbifmt-flags" /> below. Currently +only drivers set flags, applications must set this field to +zero.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved</structfield>[2]</entry> + <entry>This array is reserved for future extensions. +Drivers and applications must set it to zero.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="vbifmt-flags"> + <title>Raw VBI Format Flags</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>V4L2_VBI_UNSYNC</constant></entry> + <entry>0x0001</entry> + <entry><para>This flag indicates hardware which does not +properly distinguish between fields. Normally the VBI image stores the +first field (lower scanning line numbers) first in memory. This may be +a top or bottom field depending on the video standard. When this flag +is set the first or second field may be stored first, however the +fields are still in correct temporal order with the older field first +in memory.<footnote> + <para>Most VBI services transmit on both fields, but +some have different semantics depending on the field number. These +cannot be reliable decoded or encoded when +<constant>V4L2_VBI_UNSYNC</constant> is set.</para> + </footnote></para></entry> + </row> + <row> + <entry><constant>V4L2_VBI_INTERLACED</constant></entry> + <entry>0x0002</entry> + <entry>By default the two field images will be passed +sequentially; all lines of the first field followed by all lines of +the second field (compare <xref linkend="field-order" /> +<constant>V4L2_FIELD_SEQ_TB</constant> and +<constant>V4L2_FIELD_SEQ_BT</constant>, whether the top or bottom +field is first in memory depends on the video standard). When this +flag is set, the two fields are interlaced (cf. +<constant>V4L2_FIELD_INTERLACED</constant>). The first line of the +first field followed by the first line of the second field, then the +two second lines, and so on. Such a layout may be necessary when the +hardware has been programmed to capture or output interlaced video +images and is unable to separate the fields for VBI capturing at +the same time. For simplicity setting this flag implies that both +<structfield>count</structfield> values are equal and non-zero.</entry> + </row> + </tbody> + </tgroup> + </table> + + <figure id="vbi-hsync"> + <title>Line synchronization</title> + <mediaobject> + <imageobject> + <imagedata fileref="vbi_hsync.pdf" format="PS" /> + </imageobject> + <imageobject> + <imagedata fileref="vbi_hsync.gif" format="GIF" /> + </imageobject> + <textobject> + <phrase>Line synchronization diagram</phrase> + </textobject> + </mediaobject> + </figure> + + <figure id="vbi-525"> + <title>ITU-R 525 line numbering (M/NTSC and M/PAL)</title> + <mediaobject> + <imageobject> + <imagedata fileref="vbi_525.pdf" format="PS" /> + </imageobject> + <imageobject> + <imagedata fileref="vbi_525.gif" format="GIF" /> + </imageobject> + <textobject> + <phrase>NTSC field synchronization diagram</phrase> + </textobject> + <caption> + <para>(1) For the purpose of this specification field 2 +starts in line 264 and not 263.5 because half line capturing is not +supported.</para> + </caption> + </mediaobject> + </figure> + + <figure id="vbi-625"> + <title>ITU-R 625 line numbering</title> + <mediaobject> + <imageobject> + <imagedata fileref="vbi_625.pdf" format="PS" /> + </imageobject> + <imageobject> + <imagedata fileref="vbi_625.gif" format="GIF" /> + </imageobject> + <textobject> + <phrase>PAL/SECAM field synchronization diagram</phrase> + </textobject> + <caption> + <para>(1) For the purpose of this specification field 2 +starts in line 314 and not 313.5 because half line capturing is not +supported.</para> + </caption> + </mediaobject> + </figure> + + <para>Remember the VBI image format depends on the selected +video standard, therefore the application must choose a new standard or +query the current standard first. Attempts to read or write data ahead +of format negotiation, or after switching the video standard which may +invalidate the negotiated VBI parameters, should be refused by the +driver. A format change during active I/O is not permitted.</para> + </section> + + <section> + <title>Reading and writing VBI images</title> + + <para>To assure synchronization with the field number and easier +implementation, the smallest unit of data passed at a time is one +frame, consisting of two fields of VBI images immediately following in +memory.</para> + + <para>The total size of a frame computes as follows:</para> + + <programlisting> +(<structfield>count</structfield>[0] + <structfield>count</structfield>[1]) * +<structfield>samples_per_line</structfield> * sample size in bytes</programlisting> + + <para>The sample size is most likely always one byte, +applications must check the <structfield>sample_format</structfield> +field though, to function properly with other drivers.</para> + + <para>A VBI device may support <link + linkend="rw">read/write</link> and/or streaming (<link + linkend="mmap">memory mapping</link> or <link + linkend="userp">user pointer</link>) I/O. The latter bears the +possibility of synchronizing video and +VBI data by using buffer timestamps.</para> + + <para>Remember the &VIDIOC-STREAMON; ioctl and the first read(), +write() and select() call can be resource allocation points returning +an &EBUSY; if the required hardware resources are temporarily +unavailable, for example the device is already in use by another +process.</para> + </section> + + <!-- +Local Variables: +mode: sgml +sgml-parent-document: "v4l2.sgml" +indent-tabs-mode: nil +End: + --> |