About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

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


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.&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.
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>
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog