Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2 .. c:namespace:: V4L
   3
   4 .. _VIDIOC_G_SLICED_VBI_CAP:
   5
   6 *****************************
   7 ioctl VIDIOC_G_SLICED_VBI_CAP
   8 *****************************
   9
  10 Name
  11 ====
  12
  13 VIDIOC_G_SLICED_VBI_CAP - Query sliced VBI capabilities
  14
  15 Synopsis
  16 ========
  17
  18 .. c:macro:: VIDIOC_G_SLICED_VBI_CAP
  19
  20 ``int ioctl(int fd, VIDIOC_G_SLICED_VBI_CAP, struct v4l2_sliced_vbi_cap *argp)``
  21
  22 Arguments
  23 =========
  24
  25 ``fd``
  26     File descriptor returned by :c:func:`open()`.
  27
  28 ``argp``
  29     Pointer to struct :c:type:`v4l2_sliced_vbi_cap`.
  30
  31 Description
  32 ===========
  33
  34 To find out which data services are supported by a sliced VBI capture or
  35 output device, applications initialize the ``type`` field of a struct
  36 :c:type:`v4l2_sliced_vbi_cap`, clear the
  37 ``reserved`` array and call the :ref:`VIDIOC_G_SLICED_VBI_CAP <VIDIOC_G_SLICED_VBI_CAP>` ioctl. The
  38 driver fills in the remaining fields or returns an ``EINVAL`` error code if
  39 the sliced VBI API is unsupported or ``type`` is invalid.
  40
  41 .. note::
  42
  43    The ``type`` field was added, and the ioctl changed from read-only
  44    to write-read, in Linux 2.6.19.
  45
  46 .. c:type:: v4l2_sliced_vbi_cap
  47
  48 .. tabularcolumns:: |p{1.4cm}|p{4.4cm}|p{4.5cm}|p{3.6cm}|p{3.6cm}|
  49
  50 .. flat-table:: struct v4l2_sliced_vbi_cap
  51     :header-rows:  0
  52     :stub-columns: 0
  53     :widths:       3 3 2 2 2
  54
  55     * - __u16
  56       - ``service_set``
  57       - :cspan:`2` A set of all data services supported by the driver.
  58
  59         Equal to the union of all elements of the ``service_lines`` array.
  60     * - __u16
  61       - ``service_lines``\ [2][24]
  62       - :cspan:`2` Each element of this array contains a set of data
  63         services the hardware can look for or insert into a particular
  64         scan line. Data services are defined in :ref:`vbi-services`.
  65         Array indices map to ITU-R line numbers\ [#f1]_ as follows:
  66     * -
  67       -
  68       - Element
  69       - 525 line systems
  70       - 625 line systems
  71     * -
  72       -
  73       - ``service_lines``\ [0][1]
  74       - 1
  75       - 1
  76     * -
  77       -
  78       - ``service_lines``\ [0][23]
  79       - 23
  80       - 23
  81     * -
  82       -
  83       - ``service_lines``\ [1][1]
  84       - 264
  85       - 314
  86     * -
  87       -
  88       - ``service_lines``\ [1][23]
  89       - 286
  90       - 336
  91     * -
  92     * -
  93       -
  94       - :cspan:`2` The number of VBI lines the hardware can capture or
  95         output per frame, or the number of services it can identify on a
  96         given line may be limited. For example on PAL line 16 the hardware
  97         may be able to look for a VPS or Teletext signal, but not both at
  98         the same time. Applications can learn about these limits using the
  99         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl as described in
 100         :ref:`sliced`.
 101     * -
 102     * -
 103       -
 104       - :cspan:`2` Drivers must set ``service_lines`` [0][0] and
 105         ``service_lines``\ [1][0] to zero.
 106     * - __u32
 107       - ``type``
 108       - Type of the data stream, see :c:type:`v4l2_buf_type`. Should be
 109         ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` or
 110         ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``.
 111     * - __u32
 112       - ``reserved``\ [3]
 113       - :cspan:`2` This array is reserved for future extensions.
 114
 115         Applications and drivers must set it to zero.
 116
 117 .. [#f1]
 118
 119    See also :ref:`vbi-525` and :ref:`vbi-625`.
 120
 121 .. raw:: latex
 122
 123     \scriptsize
 124
 125 .. tabularcolumns:: |p{3.9cm}|p{1.0cm}|p{2.0cm}|p{3.0cm}|p{7.0cm}|
 126
 127 .. _vbi-services:
 128
 129 .. flat-table:: Sliced VBI services
 130     :header-rows:  1
 131     :stub-columns: 0
 132     :widths:       2 1 1 2 2
 133
 134     * - Symbol
 135       - Value
 136       - Reference
 137       - Lines, usually
 138       - Payload
 139     * - ``V4L2_SLICED_TELETEXT_B`` (Teletext System B)
 140       - 0x0001
 141       - :ref:`ets300706`,
 142
 143         :ref:`itu653`
 144       - PAL/SECAM line 7-22, 320-335 (second field 7-22)
 145       - Last 42 of the 45 byte Teletext packet, that is without clock
 146         run-in and framing code, lsb first transmitted.
 147     * - ``V4L2_SLICED_VPS``
 148       - 0x0400
 149       - :ref:`ets300231`
 150       - PAL line 16
 151       - Byte number 3 to 15 according to Figure 9 of ETS 300 231, lsb
 152         first transmitted.
 153     * - ``V4L2_SLICED_CAPTION_525``
 154       - 0x1000
 155       - :ref:`cea608`
 156       - NTSC line 21, 284 (second field 21)
 157       - Two bytes in transmission order, including parity bit, lsb first
 158         transmitted.
 159     * - ``V4L2_SLICED_WSS_625``
 160       - 0x4000
 161       - :ref:`en300294`,
 162
 163         :ref:`itu1119`
 164       - PAL/SECAM line 23
 165       - See :ref:`v4l2-sliced-vbi-cap-wss-625-payload` below.
 166     * - ``V4L2_SLICED_VBI_525``
 167       - 0x1000
 168       - :cspan:`2` Set of services applicable to 525 line systems.
 169     * - ``V4L2_SLICED_VBI_625``
 170       - 0x4401
 171       - :cspan:`2` Set of services applicable to 625 line systems.
 172
 173
 174 .. raw:: latex
 175
 176     \normalsize
 177
 178 .. _v4l2-sliced-vbi-cap-wss-625-payload:
 179
 180 V4L2_SLICED_VBI_CAP WSS_625 payload
 181 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 182
 183 The payload for ``V4L2_SLICED_WSS_625`` is:
 184
 185             +-----+------------------+-----------------------+
 186             |Byte |        0         |           1           |
 187             +-----+--------+---------+-----------+-----------+
 188             |     | msb    | lsb     | msb       | lsb       |
 189             |     +-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+
 190             | Bit |7|6|5|4 | 3|2|1|0 | x|x|13|12 | 11|10|9|8 |
 191             +-----+-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+
 192
 193
 194 Return Value
 195 ============
 196
 197 On success 0 is returned, on error -1 and the ``errno`` variable is set
 198 appropriately. The generic error codes are described at the
 199 :ref:`Generic Error Codes <gen-errors>` chapter.
 200
 201 EINVAL
 202     The value in the ``type`` field is wrong.