doc_rst: rename the media Sphinx suff to Documentation/media

The name of the subsystem is "media", and not "linux_tv". Also,
as we plan to add other stuff there in the future, let's
rename also the media uAPI book to media_uapi, to make it
clearer.

No functional changes.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

1 files changed, 349 insertions, 0 deletions

diff --git a/Documentation/media/uapi/v4l/vidioc-g-parm.rst b/Documentation/media/uapi/v4l/vidioc-g-parm.rst
new file mode 100644
index 000000000000..7116e0decddc
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-g-parm.rst
@@ -0,0 +1,349 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_PARM:
+
+**********************************
+ioctl VIDIOC_G_PARM, VIDIOC_S_PARM
+**********************************
+
+Name
+====
+
+VIDIOC_G_PARM - VIDIOC_S_PARM - Get or set streaming parameters
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, v4l2_streamparm *argp )
+
+
+Arguments
+=========
+
+``fd``
+    File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+    VIDIOC_G_PARM, VIDIOC_S_PARM
+
+``argp``
+
+
+Description
+===========
+
+The current video standard determines a nominal number of frames per
+second. If less than this number of frames is to be captured or output,
+applications can request frame skipping or duplicating on the driver
+side. This is especially useful when using the :ref:`read() <func-read>` or
+:ref:`write() <func-write>`, which are not augmented by timestamps or sequence
+counters, and to avoid unnecessary data copying.
+
+Further these ioctls can be used to determine the number of buffers used
+internally by a driver in read/write mode. For implications see the
+section discussing the :ref:`read() <func-read>` function.
+
+To get and set the streaming parameters applications call the
+:ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take a
+pointer to a struct :ref:`struct v4l2_streamparm <v4l2-streamparm>` which contains a
+union holding separate parameters for input and output devices.
+
+
+.. _v4l2-streamparm:
+
+.. flat-table:: struct v4l2_streamparm
+    :header-rows:  0
+    :stub-columns: 0
+    :widths:       1 1 1 2
+
+
+    -  .. row 1
+
+       -  __u32
+
+       -  ``type``
+
+       -
+       -  The buffer (stream) type, same as struct
+	  :ref:`v4l2_format <v4l2-format>` ``type``, set by the
+	  application. See :ref:`v4l2-buf-type`
+
+    -  .. row 2
+
+       -  union
+
+       -  ``parm``
+
+       -
+       -
+
+    -  .. row 3
+
+       -
+       -  struct :ref:`v4l2_captureparm <v4l2-captureparm>`
+
+       -  ``capture``
+
+       -  Parameters for capture devices, used when ``type`` is
+	  ``V4L2_BUF_TYPE_VIDEO_CAPTURE``.
+
+    -  .. row 4
+
+       -
+       -  struct :ref:`v4l2_outputparm <v4l2-outputparm>`
+
+       -  ``output``
+
+       -  Parameters for output devices, used when ``type`` is
+	  ``V4L2_BUF_TYPE_VIDEO_OUTPUT``.
+
+    -  .. row 5
+
+       -
+       -  __u8
+
+       -  ``raw_data``\ [200]
+
+       -  A place holder for future extensions.
+
+
+
+.. _v4l2-captureparm:
+
+.. flat-table:: struct v4l2_captureparm
+    :header-rows:  0
+    :stub-columns: 0
+    :widths:       1 1 2
+
+
+    -  .. row 1
+
+       -  __u32
+
+       -  ``capability``
+
+       -  See :ref:`parm-caps`.
+
+    -  .. row 2
+
+       -  __u32
+
+       -  ``capturemode``
+
+       -  Set by drivers and applications, see :ref:`parm-flags`.
+
+    -  .. row 3
+
+       -  struct :ref:`v4l2_fract <v4l2-fract>`
+
+       -  ``timeperframe``
+
+       -  This is the desired period between successive frames captured by
+	  the driver, in seconds. The field is intended to skip frames on
+	  the driver side, saving I/O bandwidth.
+
+	  Applications store here the desired frame period, drivers return
+	  the actual frame period, which must be greater or equal to the
+	  nominal frame period determined by the current video standard
+	  (struct :ref:`v4l2_standard <v4l2-standard>` ``frameperiod``
+	  field). Changing the video standard (also implicitly by switching
+	  the video input) may reset this parameter to the nominal frame
+	  period. To reset manually applications can just set this field to
+	  zero.
+
+	  Drivers support this function only when they set the
+	  ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field.
+
+    -  .. row 4
+
+       -  __u32
+
+       -  ``extendedmode``
+
+       -  Custom (driver specific) streaming parameters. When unused,
+	  applications and drivers must set this field to zero. Applications
+	  using this field should check the driver name and version, see
+	  :ref:`querycap`.
+
+    -  .. row 5
+
+       -  __u32
+
+       -  ``readbuffers``
+
+       -  Applications set this field to the desired number of buffers used
+	  internally by the driver in :ref:`read() <func-read>` mode.
+	  Drivers return the actual number of buffers. When an application
+	  requests zero buffers, drivers should just return the current
+	  setting rather than the minimum or an error code. For details see
+	  :ref:`rw`.
+
+    -  .. row 6
+
+       -  __u32
+
+       -  ``reserved``\ [4]
+
+       -  Reserved for future extensions. Drivers and applications must set
+	  the array to zero.
+
+
+
+.. _v4l2-outputparm:
+
+.. flat-table:: struct v4l2_outputparm
+    :header-rows:  0
+    :stub-columns: 0
+    :widths:       1 1 2
+
+
+    -  .. row 1
+
+       -  __u32
+
+       -  ``capability``
+
+       -  See :ref:`parm-caps`.
+
+    -  .. row 2
+
+       -  __u32
+
+       -  ``outputmode``
+
+       -  Set by drivers and applications, see :ref:`parm-flags`.
+
+    -  .. row 3
+
+       -  struct :ref:`v4l2_fract <v4l2-fract>`
+
+       -  ``timeperframe``
+
+       -  This is the desired period between successive frames output by the
+	  driver, in seconds.
+
+    -  .. row 4
+
+       -  :cspan:`2`
+
+	  The field is intended to repeat frames on the driver side in
+	  :ref:`write() <func-write>` mode (in streaming mode timestamps
+	  can be used to throttle the output), saving I/O bandwidth.
+
+	  Applications store here the desired frame period, drivers return
+	  the actual frame period, which must be greater or equal to the
+	  nominal frame period determined by the current video standard
+	  (struct :ref:`v4l2_standard <v4l2-standard>` ``frameperiod``
+	  field). Changing the video standard (also implicitly by switching
+	  the video output) may reset this parameter to the nominal frame
+	  period. To reset manually applications can just set this field to
+	  zero.
+
+	  Drivers support this function only when they set the
+	  ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field.
+
+    -  .. row 5
+
+       -  __u32
+
+       -  ``extendedmode``
+
+       -  Custom (driver specific) streaming parameters. When unused,
+	  applications and drivers must set this field to zero. Applications
+	  using this field should check the driver name and version, see
+	  :ref:`querycap`.
+
+    -  .. row 6
+
+       -  __u32
+
+       -  ``writebuffers``
+
+       -  Applications set this field to the desired number of buffers used
+	  internally by the driver in :ref:`write() <func-write>` mode. Drivers
+	  return the actual number of buffers. When an application requests
+	  zero buffers, drivers should just return the current setting
+	  rather than the minimum or an error code. For details see
+	  :ref:`rw`.
+
+    -  .. row 7
+
+       -  __u32
+
+       -  ``reserved``\ [4]
+
+       -  Reserved for future extensions. Drivers and applications must set
+	  the array to zero.
+
+
+
+.. _parm-caps:
+
+.. flat-table:: Streaming Parameters Capabilites
+    :header-rows:  0
+    :stub-columns: 0
+    :widths:       3 1 4
+
+
+    -  .. row 1
+
+       -  ``V4L2_CAP_TIMEPERFRAME``
+
+       -  0x1000
+
+       -  The frame skipping/repeating controlled by the ``timeperframe``
+	  field is supported.
+
+
+
+.. _parm-flags:
+
+.. flat-table:: Capture Parameters Flags
+    :header-rows:  0
+    :stub-columns: 0
+    :widths:       3 1 4
+
+
+    -  .. row 1
+
+       -  ``V4L2_MODE_HIGHQUALITY``
+
+       -  0x0001
+
+       -  High quality imaging mode. High quality mode is intended for still
+	  imaging applications. The idea is to get the best possible image
+	  quality that the hardware can deliver. It is not defined how the
+	  driver writer may achieve that; it will depend on the hardware and
+	  the ingenuity of the driver writer. High quality mode is a
+	  different mode from the regular motion video capture modes. In
+	  high quality mode:
+
+	  -  The driver may be able to capture higher resolutions than for
+	     motion capture.
+
+	  -  The driver may support fewer pixel formats than motion capture
+	     (eg; true color).
+
+	  -  The driver may capture and arithmetically combine multiple
+	     successive fields or frames to remove color edge artifacts and
+	     reduce the noise in the video data.
+
+	  -  The driver may capture images in slices like a scanner in order
+	     to handle larger format images than would otherwise be
+	     possible.
+
+	  -  An image capture operation may be significantly slower than
+	     motion capture.
+
+	  -  Moving objects in the image might have excessive motion blur.
+
+	  -  Capture might only work through the :ref:`read() <func-read>` call.
+
+
+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.