doc-rst: linux_tv DocBook to reST migration (docs-next)
This is the restructuredText (reST) migration of the ``media``
DocBook-XML set from the linux_tv project.
Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
diff --git a/Documentation/linux_tv/media/v4l/vidioc-g-sliced-vbi-cap.rst b/Documentation/linux_tv/media/v4l/vidioc-g-sliced-vbi-cap.rst
new file mode 100644
index 0000000..c76f568
--- /dev/null
+++ b/Documentation/linux_tv/media/v4l/vidioc-g-sliced-vbi-cap.rst
@@ -0,0 +1,284 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-g-sliced-vbi-cap:
+
+*****************************
+ioctl VIDIOC_G_SLICED_VBI_CAP
+*****************************
+
+*man VIDIOC_G_SLICED_VBI_CAP(2)*
+
+Query sliced VBI capabilities
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_sliced_vbi_cap *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_SLICED_VBI_CAP
+
+``argp``
+
+
+Description
+===========
+
+To find out which data services are supported by a sliced VBI capture or
+output device, applications initialize the ``type`` field of a struct
+:ref:`v4l2_sliced_vbi_cap <v4l2-sliced-vbi-cap>`, clear the
+``reserved`` array and call the ``VIDIOC_G_SLICED_VBI_CAP`` ioctl. The
+driver fills in the remaining fields or returns an EINVAL error code if
+the sliced VBI API is unsupported or ``type`` is invalid.
+
+Note the ``type`` field was added, and the ioctl changed from read-only
+to write-read, in Linux 2.6.19.
+
+
+.. _v4l2-sliced-vbi-cap:
+
+.. flat-table:: struct v4l2_sliced_vbi_cap
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 3 2 2 2
+
+
+ - .. row 1
+
+ - __u16
+
+ - ``service_set``
+
+ - :cspan:`2` A set of all data services supported by the driver.
+ Equal to the union of all elements of the ``service_lines`` array.
+
+ - .. row 2
+
+ - __u16
+
+ - ``service_lines``\ [2][24]
+
+ - :cspan:`2` Each element of this array contains a set of data
+ services the hardware can look for or insert into a particular
+ scan line. Data services are defined in :ref:`vbi-services`.
+ Array indices map to ITU-R line numbers (see also :ref:`vbi-525`
+ and :ref:`vbi-625`) as follows:
+
+ - .. row 3
+
+ -
+ -
+ - Element
+
+ - 525 line systems
+
+ - 625 line systems
+
+ - .. row 4
+
+ -
+ -
+ - ``service_lines``\ [0][1]
+
+ - 1
+
+ - 1
+
+ - .. row 5
+
+ -
+ -
+ - ``service_lines``\ [0][23]
+
+ - 23
+
+ - 23
+
+ - .. row 6
+
+ -
+ -
+ - ``service_lines``\ [1][1]
+
+ - 264
+
+ - 314
+
+ - .. row 7
+
+ -
+ -
+ - ``service_lines``\ [1][23]
+
+ - 286
+
+ - 336
+
+ - .. row 8
+
+ -
+
+ - .. row 9
+
+ -
+ -
+ - :cspan:`2` The number of VBI lines the hardware can capture or
+ output per frame, or the number of services it can identify on a
+ given line may be limited. For example on PAL line 16 the hardware
+ may be able to look for a VPS or Teletext signal, but not both at
+ the same time. Applications can learn about these limits using the
+ :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl as described in
+ :ref:`sliced`.
+
+ - .. row 10
+
+ -
+
+ - .. row 11
+
+ -
+ -
+ - :cspan:`2` Drivers must set ``service_lines`` [0][0] and
+ ``service_lines``\ [1][0] to zero.
+
+ - .. row 12
+
+ - __u32
+
+ - ``type``
+
+ - Type of the data stream, see :ref:`v4l2-buf-type`. Should be
+ ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` or
+ ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``.
+
+ - .. row 13
+
+ - __u32
+
+ - ``reserved``\ [3]
+
+ - :cspan:`2` This array is reserved for future extensions.
+ Applications and drivers must set it to zero.
+
+
+
+.. _vbi-services:
+
+.. flat-table:: Sliced VBI services
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 2 1 1 2 2
+
+
+ - .. row 1
+
+ - Symbol
+
+ - Value
+
+ - Reference
+
+ - Lines, usually
+
+ - Payload
+
+ - .. row 2
+
+ - ``V4L2_SLICED_TELETEXT_B`` (Teletext System B)
+
+ - 0x0001
+
+ - :ref:`ets300706`, :ref:`itu653`
+
+ - PAL/SECAM line 7-22, 320-335 (second field 7-22)
+
+ - Last 42 of the 45 byte Teletext packet, that is without clock
+ run-in and framing code, lsb first transmitted.
+
+ - .. row 3
+
+ - ``V4L2_SLICED_VPS``
+
+ - 0x0400
+
+ - :ref:`ets300231`
+
+ - PAL line 16
+
+ - Byte number 3 to 15 according to Figure 9 of ETS 300 231, lsb
+ first transmitted.
+
+ - .. row 4
+
+ - ``V4L2_SLICED_CAPTION_525``
+
+ - 0x1000
+
+ - :ref:`cea608`
+
+ - NTSC line 21, 284 (second field 21)
+
+ - Two bytes in transmission order, including parity bit, lsb first
+ transmitted.
+
+ - .. row 5
+
+ - ``V4L2_SLICED_WSS_625``
+
+ - 0x4000
+
+ - :ref:`en300294`, :ref:`itu1119`
+
+ - PAL/SECAM line 23
+
+ -
+
+ ::
+
+ Byte 0 1
+ msb lsb msb lsb
+ Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9
+
+ - .. row 6
+
+ - ``V4L2_SLICED_VBI_525``
+
+ - 0x1000
+
+ - :cspan:`2` Set of services applicable to 525 line systems.
+
+ - .. row 7
+
+ - ``V4L2_SLICED_VBI_625``
+
+ - 0x4401
+
+ - :cspan:`2` Set of services applicable to 625 line systems.
+
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The value in the ``type`` field is wrong.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------