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

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