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