Merge tag 'media/v4.8-4' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media

Pull media documentation updates from Mauro Carvalho Chehab:
 "This patch series does the conversion of all media documentation stuff
  to Restrutured Text markup format and add them to the
  Documentation/index.rst file.

  The media documentation was grouped into 4 books:

    - media uAPI
    - media kAPI
    - V4L driver-specific documentation
    - DVB driver-specific documentation

  It also contains several documentation improvements and one fixup
  patch for a core issue with cropcap.

  PS.  After this patch series, the media DocBook is deprecated and
  should be removed.  I'll add such patch on a future pull request"

* tag 'media/v4.8-4' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (322 commits)
  [media] cx23885-cardlist.rst: add a new card
  [media] doc-rst: add some needed escape codes
  [media] doc-rst: kapi: use :c:func: instead of :cpp:func
  doc-rst: kernel-doc: fix a change introduced by mistake
  [media] v4l2-ioctl.h add debug info for struct v4l2_ioctl_ops
  [media] dvb_ringbuffer.h: some documentation improvements
  [media] v4l2-ctrls.h: fully document the header file
  [media] doc-rst: Fix some typedef ugly warnings
  [media] doc-rst: reorganize the kAPI v4l2 chapters
  [media] rename v4l2-framework.rst to v4l2-intro.rst
  [media] move V4L2 clocks to a separate .rst file
  [media] v4l2-fh.rst: add cross references and markups
  [media] v4l2-fh.rst: add fh contents from v4l2-framework.rst
  [media] v4l2-fh.h: add documentation for it
  [media] v4l2-event.rst: add cross-references and markups
  [media] v4l2-event.h: document all functions
  [media] v4l2-event.rst: add text from v4l2-framework.rst
  [media] v4l2-framework.rst: remove videobuf quick chapter
  [media] v4l2-dev: add cross-references and improve markup
  [media] doc-rst: move v4l2-dev doc to a separate file
  ...

1 files changed, 196 insertions, 0 deletions

diff --git a/Documentation/media/uapi/v4l/pixfmt-002.rst b/Documentation/media/uapi/v4l/pixfmt-002.rst
new file mode 100644
index 0000000..fae9b2d
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-002.rst
@@ -0,0 +1,196 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+******************************
+Single-planar format structure
+******************************
+
+
+.. _v4l2-pix-format:
+
+.. flat-table:: struct v4l2_pix_format
+    :header-rows:  0
+    :stub-columns: 0
+    :widths:       1 1 2
+
+
+    -  .. row 1
+
+       -  __u32
+
+       -  ``width``
+
+       -  Image width in pixels.
+
+    -  .. row 2
+
+       -  __u32
+
+       -  ``height``
+
+       -  Image height in pixels. If ``field`` is one of ``V4L2_FIELD_TOP``,
+	  ``V4L2_FIELD_BOTTOM`` or ``V4L2_FIELD_ALTERNATE`` then height
+	  refers to the number of lines in the field, otherwise it refers to
+	  the number of lines in the frame (which is twice the field height
+	  for interlaced formats).
+
+    -  .. row 3
+
+       -  :cspan:`2` Applications set these fields to request an image
+	  size, drivers return the closest possible values. In case of
+	  planar formats the ``width`` and ``height`` applies to the largest
+	  plane. To avoid ambiguities drivers must return values rounded up
+	  to a multiple of the scale factor of any smaller planes. For
+	  example when the image format is YUV 4:2:0, ``width`` and
+	  ``height`` must be multiples of two.
+
+    -  .. row 4
+
+       -  __u32
+
+       -  ``pixelformat``
+
+       -  The pixel format or type of compression, set by the application.
+	  This is a little endian
+	  :ref:`four character code <v4l2-fourcc>`. V4L2 defines standard
+	  RGB formats in :ref:`rgb-formats`, YUV formats in
+	  :ref:`yuv-formats`, and reserved codes in
+	  :ref:`reserved-formats`
+
+    -  .. row 5
+
+       -  enum :ref:`v4l2_field <v4l2-field>`
+
+       -  ``field``
+
+       -  Video images are typically interlaced. Applications can request to
+	  capture or output only the top or bottom field, or both fields
+	  interlaced or sequentially stored in one buffer or alternating in
+	  separate buffers. Drivers return the actual field order selected.
+	  For more details on fields see :ref:`field-order`.
+
+    -  .. row 6
+
+       -  __u32
+
+       -  ``bytesperline``
+
+       -  Distance in bytes between the leftmost pixels in two adjacent
+	  lines.
+
+    -  .. row 7
+
+       -  :cspan:`2`
+
+	  Both applications and drivers can set this field to request
+	  padding bytes at the end of each line. Drivers however may ignore
+	  the value requested by the application, returning ``width`` times
+	  bytes per pixel or a larger value required by the hardware. That
+	  implies applications can just set this field to zero to get a
+	  reasonable default.
+
+	  Video hardware may access padding bytes, therefore they must
+	  reside in accessible memory. Consider cases where padding bytes
+	  after the last line of an image cross a system page boundary.
+	  Input devices may write padding bytes, the value is undefined.
+	  Output devices ignore the contents of padding bytes.
+
+	  When the image format is planar the ``bytesperline`` value applies
+	  to the first plane and is divided by the same factor as the
+	  ``width`` field for the other planes. For example the Cb and Cr
+	  planes of a YUV 4:2:0 image have half as many padding bytes
+	  following each line as the Y plane. To avoid ambiguities drivers
+	  must return a ``bytesperline`` value rounded up to a multiple of
+	  the scale factor.
+
+	  For compressed formats the ``bytesperline`` value makes no sense.
+	  Applications and drivers must set this to 0 in that case.
+
+    -  .. row 8
+
+       -  __u32
+
+       -  ``sizeimage``
+
+       -  Size in bytes of the buffer to hold a complete image, set by the
+	  driver. Usually this is ``bytesperline`` times ``height``. When
+	  the image consists of variable length compressed data this is the
+	  maximum number of bytes required to hold an image.
+
+    -  .. row 9
+
+       -  enum :ref:`v4l2_colorspace <v4l2-colorspace>`
+
+       -  ``colorspace``
+
+       -  This information supplements the ``pixelformat`` and must be set
+	  by the driver for capture streams and by the application for
+	  output streams, see :ref:`colorspaces`.
+
+    -  .. row 10
+
+       -  __u32
+
+       -  ``priv``
+
+       -  This field indicates whether the remaining fields of the
+	  :ref:`struct v4l2_pix_format <v4l2-pix-format>` structure, also called the
+	  extended fields, are valid. When set to
+	  ``V4L2_PIX_FMT_PRIV_MAGIC``, it indicates that the extended fields
+	  have been correctly initialized. When set to any other value it
+	  indicates that the extended fields contain undefined values.
+
+	  Applications that wish to use the pixel format extended fields
+	  must first ensure that the feature is supported by querying the
+	  device for the :ref:`V4L2_CAP_EXT_PIX_FORMAT <querycap>`
+	  capability. If the capability isn't set the pixel format extended
+	  fields are not supported and using the extended fields will lead
+	  to undefined results.
+
+	  To use the extended fields, applications must set the ``priv``
+	  field to ``V4L2_PIX_FMT_PRIV_MAGIC``, initialize all the extended
+	  fields and zero the unused bytes of the
+	  :ref:`struct v4l2_format <v4l2-format>` ``raw_data`` field.
+
+	  When the ``priv`` field isn't set to ``V4L2_PIX_FMT_PRIV_MAGIC``
+	  drivers must act as if all the extended fields were set to zero.
+	  On return drivers must set the ``priv`` field to
+	  ``V4L2_PIX_FMT_PRIV_MAGIC`` and all the extended fields to
+	  applicable values.
+
+    -  .. row 11
+
+       -  __u32
+
+       -  ``flags``
+
+       -  Flags set by the application or driver, see :ref:`format-flags`.
+
+    -  .. row 12
+
+       -  enum :ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>`
+
+       -  ``ycbcr_enc``
+
+       -  This information supplements the ``colorspace`` and must be set by
+	  the driver for capture streams and by the application for output
+	  streams, see :ref:`colorspaces`.
+
+    -  .. row 13
+
+       -  enum :ref:`v4l2_quantization <v4l2-quantization>`
+
+       -  ``quantization``
+
+       -  This information supplements the ``colorspace`` and must be set by
+	  the driver for capture streams and by the application for output
+	  streams, see :ref:`colorspaces`.
+
+    -  .. row 14
+
+       -  enum :ref:`v4l2_xfer_func <v4l2-xfer-func>`
+
+       -  ``xfer_func``
+
+       -  This information supplements the ``colorspace`` and must be set by
+	  the driver for capture streams and by the application for output
+	  streams, see :ref:`colorspaces`.