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

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