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, 417 insertions, 0 deletions

diff --git a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
new file mode 100644
index 000000000000..e19d64e0116a
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
@@ -0,0 +1,417 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_DV_TIMINGS:
+
+**********************************************
+ioctl VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS
+**********************************************
+
+Name
+====
+
+VIDIOC_G_DV_TIMINGS - VIDIOC_S_DV_TIMINGS - VIDIOC_SUBDEV_G_DV_TIMINGS - VIDIOC_SUBDEV_S_DV_TIMINGS - Get or set DV timings for input or output
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_dv_timings *argp )
+
+
+Arguments
+=========
+
+``fd``
+    File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+    VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS,
+    VIDIOC_SUBDEV_G_DV_TIMINGS, VIDIOC_SUBDEV_S_DV_TIMINGS
+
+``argp``
+
+
+Description
+===========
+
+To set DV timings for the input or output, applications use the
+:ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl and to get the current timings,
+applications use the :ref:`VIDIOC_G_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl. The detailed timing
+information is filled in using the structure struct
+:ref:`v4l2_dv_timings <v4l2-dv-timings>`. These ioctls take a
+pointer to the struct :ref:`v4l2_dv_timings <v4l2-dv-timings>`
+structure as argument. If the ioctl is not supported or the timing
+values are not correct, the driver returns ``EINVAL`` error code.
+
+The ``linux/v4l2-dv-timings.h`` header can be used to get the timings of
+the formats in the :ref:`cea861` and :ref:`vesadmt` standards. If
+the current input or output does not support DV timings (e.g. if
+:ref:`VIDIOC_ENUMINPUT` does not set the
+``V4L2_IN_CAP_DV_TIMINGS`` flag), then ``ENODATA`` error code is returned.
+
+
+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
+    This ioctl is not supported, or the :ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>`
+    parameter was unsuitable.
+
+ENODATA
+    Digital video timings are not supported for this input or output.
+
+EBUSY
+    The device is busy and therefore can not change the timings.
+
+
+.. _v4l2-bt-timings:
+
+.. flat-table:: struct v4l2_bt_timings
+    :header-rows:  0
+    :stub-columns: 0
+    :widths:       1 1 2
+
+
+    -  .. row 1
+
+       -  __u32
+
+       -  ``width``
+
+       -  Width of the active video in pixels.
+
+    -  .. row 2
+
+       -  __u32
+
+       -  ``height``
+
+       -  Height of the active video frame in lines. So for interlaced
+	  formats the height of the active video in each field is
+	  ``height``/2.
+
+    -  .. row 3
+
+       -  __u32
+
+       -  ``interlaced``
+
+       -  Progressive (0) or interlaced (1)
+
+    -  .. row 4
+
+       -  __u32
+
+       -  ``polarities``
+
+       -  This is a bit mask that defines polarities of sync signals. bit 0
+	  (``V4L2_DV_VSYNC_POS_POL``) is for vertical sync polarity and bit
+	  1 (``V4L2_DV_HSYNC_POS_POL``) is for horizontal sync polarity. If
+	  the bit is set (1) it is positive polarity and if is cleared (0),
+	  it is negative polarity.
+
+    -  .. row 5
+
+       -  __u64
+
+       -  ``pixelclock``
+
+       -  Pixel clock in Hz. Ex. 74.25MHz->74250000
+
+    -  .. row 6
+
+       -  __u32
+
+       -  ``hfrontporch``
+
+       -  Horizontal front porch in pixels
+
+    -  .. row 7
+
+       -  __u32
+
+       -  ``hsync``
+
+       -  Horizontal sync length in pixels
+
+    -  .. row 8
+
+       -  __u32
+
+       -  ``hbackporch``
+
+       -  Horizontal back porch in pixels
+
+    -  .. row 9
+
+       -  __u32
+
+       -  ``vfrontporch``
+
+       -  Vertical front porch in lines. For interlaced formats this refers
+	  to the odd field (aka field 1).
+
+    -  .. row 10
+
+       -  __u32
+
+       -  ``vsync``
+
+       -  Vertical sync length in lines. For interlaced formats this refers
+	  to the odd field (aka field 1).
+
+    -  .. row 11
+
+       -  __u32
+
+       -  ``vbackporch``
+
+       -  Vertical back porch in lines. For interlaced formats this refers
+	  to the odd field (aka field 1).
+
+    -  .. row 12
+
+       -  __u32
+
+       -  ``il_vfrontporch``
+
+       -  Vertical front porch in lines for the even field (aka field 2) of
+	  interlaced field formats. Must be 0 for progressive formats.
+
+    -  .. row 13
+
+       -  __u32
+
+       -  ``il_vsync``
+
+       -  Vertical sync length in lines for the even field (aka field 2) of
+	  interlaced field formats. Must be 0 for progressive formats.
+
+    -  .. row 14
+
+       -  __u32
+
+       -  ``il_vbackporch``
+
+       -  Vertical back porch in lines for the even field (aka field 2) of
+	  interlaced field formats. Must be 0 for progressive formats.
+
+    -  .. row 15
+
+       -  __u32
+
+       -  ``standards``
+
+       -  The video standard(s) this format belongs to. This will be filled
+	  in by the driver. Applications must set this to 0. See
+	  :ref:`dv-bt-standards` for a list of standards.
+
+    -  .. row 16
+
+       -  __u32
+
+       -  ``flags``
+
+       -  Several flags giving more information about the format. See
+	  :ref:`dv-bt-flags` for a description of the flags.
+
+
+
+.. _v4l2-dv-timings:
+
+.. flat-table:: struct v4l2_dv_timings
+    :header-rows:  0
+    :stub-columns: 0
+    :widths:       1 1 2 1
+
+
+    -  .. row 1
+
+       -  __u32
+
+       -  ``type``
+
+       -
+       -  Type of DV timings as listed in :ref:`dv-timing-types`.
+
+    -  .. row 2
+
+       -  union
+
+       -
+       -
+
+    -  .. row 3
+
+       -
+       -  struct :ref:`v4l2_bt_timings <v4l2-bt-timings>`
+
+       -  ``bt``
+
+       -  Timings defined by BT.656/1120 specifications
+
+    -  .. row 4
+
+       -
+       -  __u32
+
+       -  ``reserved``\ [32]
+
+       -
+
+
+
+.. _dv-timing-types:
+
+.. flat-table:: DV Timing types
+    :header-rows:  0
+    :stub-columns: 0
+    :widths:       1 1 2
+
+
+    -  .. row 1
+
+       -  Timing type
+
+       -  value
+
+       -  Description
+
+    -  .. row 2
+
+       -
+       -
+       -
+
+    -  .. row 3
+
+       -  ``V4L2_DV_BT_656_1120``
+
+       -  0
+
+       -  BT.656/1120 timings
+
+
+
+.. _dv-bt-standards:
+
+.. flat-table:: DV BT Timing standards
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  Timing standard
+
+       -  Description
+
+    -  .. row 2
+
+       -
+       -
+
+    -  .. row 3
+
+       -  ``V4L2_DV_BT_STD_CEA861``
+
+       -  The timings follow the CEA-861 Digital TV Profile standard
+
+    -  .. row 4
+
+       -  ``V4L2_DV_BT_STD_DMT``
+
+       -  The timings follow the VESA Discrete Monitor Timings standard
+
+    -  .. row 5
+
+       -  ``V4L2_DV_BT_STD_CVT``
+
+       -  The timings follow the VESA Coordinated Video Timings standard
+
+    -  .. row 6
+
+       -  ``V4L2_DV_BT_STD_GTF``
+
+       -  The timings follow the VESA Generalized Timings Formula standard
+
+
+
+.. _dv-bt-flags:
+
+.. flat-table:: DV BT Timing flags
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  Flag
+
+       -  Description
+
+    -  .. row 2
+
+       -
+       -
+
+    -  .. row 3
+
+       -  ``V4L2_DV_FL_REDUCED_BLANKING``
+
+       -  CVT/GTF specific: the timings use reduced blanking (CVT) or the
+	  'Secondary GTF' curve (GTF). In both cases the horizontal and/or
+	  vertical blanking intervals are reduced, allowing a higher
+	  resolution over the same bandwidth. This is a read-only flag,
+	  applications must not set this.
+
+    -  .. row 4
+
+       -  ``V4L2_DV_FL_CAN_REDUCE_FPS``
+
+       -  CEA-861 specific: set for CEA-861 formats with a framerate that is
+	  a multiple of six. These formats can be optionally played at 1 /
+	  1.001 speed to be compatible with 60 Hz based standards such as
+	  NTSC and PAL-M that use a framerate of 29.97 frames per second. If
+	  the transmitter can't generate such frequencies, then the flag
+	  will also be cleared. This is a read-only flag, applications must
+	  not set this.
+
+    -  .. row 5
+
+       -  ``V4L2_DV_FL_REDUCED_FPS``
+
+       -  CEA-861 specific: only valid for video transmitters, the flag is
+	  cleared by receivers. It is also only valid for formats with the
+	  ``V4L2_DV_FL_CAN_REDUCE_FPS`` flag set, for other formats the
+	  flag will be cleared by the driver. If the application sets this
+	  flag, then the pixelclock used to set up the transmitter is
+	  divided by 1.001 to make it compatible with NTSC framerates. If
+	  the transmitter can't generate such frequencies, then the flag
+	  will also be cleared.
+
+    -  .. row 6
+
+       -  ``V4L2_DV_FL_HALF_LINE``
+
+       -  Specific to interlaced formats: if set, then the vertical
+	  frontporch of field 1 (aka the odd field) is really one half-line
+	  longer and the vertical backporch of field 2 (aka the even field)
+	  is really one half-line shorter, so each field has exactly the
+	  same number of half-lines. Whether half-lines can be detected or
+	  used depends on the hardware.
+
+    -  .. row 7
+
+       -  ``V4L2_DV_FL_IS_CE_VIDEO``
+
+       -  If set, then this is a Consumer Electronics (CE) video format.
+	  Such formats differ from other formats (commonly called IT
+	  formats) in that if R'G'B' encoding is used then by default the
+	  R'G'B' values use limited range (i.e. 16-235) as opposed to full
+	  range (i.e. 0-255). All formats defined in CEA-861 except for the
+	  640x480p59.94 format are CE formats.