Orange Pi5 kernel

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