1 files changed, 142 insertions, 9 deletions

diff --git a/Documentation/DocBook/v4l/pixfmt.xml b/Documentation/DocBook/v4l/pixfmt.xml
index c4ad0a8e42dc..deb660207f94 100644
--- a/Documentation/DocBook/v4l/pixfmt.xml
+++ b/Documentation/DocBook/v4l/pixfmt.xml
@@ -2,12 +2,16 @@
 
   <para>The V4L2 API was primarily designed for devices exchanging
 image data with applications. The
-<structname>v4l2_pix_format</structname> structure defines the format
-and layout of an image in memory. Image formats are negotiated with
-the &VIDIOC-S-FMT; ioctl. (The explanations here focus on video
+<structname>v4l2_pix_format</structname> and <structname>v4l2_pix_format_mplane
+</structname> structures define the format and layout of an image in memory.
+The former is used with the single-planar API, while the latter is used with the
+multi-planar version (see <xref linkend="planar-apis"/>). Image formats are
+negotiated with the &VIDIOC-S-FMT; ioctl. (The explanations here focus on video
 capturing and output, for overlay frame buffer formats see also
 &VIDIOC-G-FBUF;.)</para>
 
+<section>
+  <title>Single-planar format structure</title>
   <table pgwide="1" frame="none" id="v4l2-pix-format">
     <title>struct <structname>v4l2_pix_format</structname></title>
     <tgroup cols="3">
@@ -106,6 +110,98 @@ set this field to zero.</entry>
       </tbody>
     </tgroup>
   </table>
+</section>
+
+<section>
+  <title>Multi-planar format structures</title>
+  <para>The <structname>v4l2_plane_pix_format</structname> structures define
+    size and layout for each of the planes in a multi-planar format.
+    The <structname>v4l2_pix_format_mplane</structname> structure contains
+    information common to all planes (such as image width and height) and
+    an array of <structname>v4l2_plane_pix_format</structname> structures,
+    describing all planes of that format.</para>
+  <table pgwide="1" frame="none" id="v4l2-plane-pix-format">
+    <title>struct <structname>vl42_plane_pix_format</structname></title>
+    <tgroup cols="3">
+      &cs-str;
+      <tbody valign="top">
+        <row>
+          <entry>__u32</entry>
+          <entry><structfield>sizeimage</structfield></entry>
+          <entry>Maximum size in bytes required for image data in this plane.
+          </entry>
+        </row>
+        <row>
+          <entry>__u16</entry>
+          <entry><structfield>bytesperline</structfield></entry>
+          <entry>Distance in bytes between the leftmost pixels in two adjacent
+            lines.</entry>
+        </row>
+        <row>
+          <entry>__u16</entry>
+          <entry><structfield>reserved[7]</structfield></entry>
+          <entry>Reserved for future extensions. Should be zeroed by the
+           application.</entry>
+        </row>
+      </tbody>
+    </tgroup>
+  </table>
+  <table pgwide="1" frame="none" id="v4l2-pix-format-mplane">
+    <title>struct <structname>v4l2_pix_format_mplane</structname></title>
+    <tgroup cols="3">
+      &cs-str;
+      <tbody valign="top">
+        <row>
+          <entry>__u32</entry>
+          <entry><structfield>width</structfield></entry>
+          <entry>Image width in pixels.</entry>
+        </row>
+        <row>
+          <entry>__u32</entry>
+          <entry><structfield>height</structfield></entry>
+          <entry>Image height in pixels.</entry>
+        </row>
+        <row>
+          <entry>__u32</entry>
+          <entry><structfield>pixelformat</structfield></entry>
+          <entry>The pixel format. Both single- and multi-planar four character
+codes can be used.</entry>
+        </row>
+        <row>
+          <entry>&v4l2-field;</entry>
+          <entry><structfield>field</structfield></entry>
+          <entry>See &v4l2-pix-format;.</entry>
+        </row>
+        <row>
+          <entry>&v4l2-colorspace;</entry>
+          <entry><structfield>colorspace</structfield></entry>
+          <entry>See &v4l2-pix-format;.</entry>
+        </row>
+        <row>
+          <entry>&v4l2-plane-pix-format;</entry>
+          <entry><structfield>plane_fmt[VIDEO_MAX_PLANES]</structfield></entry>
+          <entry>An array of structures describing format of each plane this
+          pixel format consists of. The number of valid entries in this array
+          has to be put in the <structfield>num_planes</structfield>
+          field.</entry>
+        </row>
+        <row>
+          <entry>__u8</entry>
+          <entry><structfield>num_planes</structfield></entry>
+          <entry>Number of planes (i.e. separate memory buffers) for this format
+          and the number of valid entries in the
+          <structfield>plane_fmt</structfield> array.</entry>
+        </row>
+        <row>
+          <entry>__u8</entry>
+          <entry><structfield>reserved[11]</structfield></entry>
+          <entry>Reserved for future extensions. Should be zeroed by the
+           application.</entry>
+        </row>
+      </tbody>
+    </tgroup>
+  </table>
+</section>
 
   <section>
     <title>Standard Image Formats</title>
@@ -144,9 +240,17 @@ has just as many pad bytes after it as the other rows.</para>
     <para>In V4L2 each format has an identifier which looks like
 <constant>PIX_FMT_XXX</constant>, defined in the <link
 linkend="videodev">videodev.h</link> header file. These identifiers
-represent <link linkend="v4l2-fourcc">four character codes</link>
+represent <link linkend="v4l2-fourcc">four character (FourCC) codes</link>
 which are also listed below, however they are not the same as those
 used in the Windows world.</para>
+
+    <para>For some formats, data is stored in separate, discontiguous
+memory buffers. Those formats are identified by a separate set of FourCC codes
+and are referred to as "multi-planar formats". For example, a YUV422 frame is
+normally stored in one memory buffer, but it can also be placed in two or three
+separate buffers, with Y component in one buffer and CbCr components in another
+in the 2-planar version or with each component in its own buffer in the
+3-planar case. Those sub-buffers are referred to as "planes".</para>
   </section>
 
   <section id="colorspaces">
@@ -566,7 +670,10 @@ access the palette, this must be done with ioctls of the Linux framebuffer API.<
     &sub-sbggr8;
     &sub-sgbrg8;
     &sub-sgrbg8;
+    &sub-srggb8;
     &sub-sbggr16;
+    &sub-srggb10;
+    &sub-srggb12;
   </section>
 
   <section id="yuv-formats">
@@ -589,6 +696,9 @@ information.</para>
 
     &sub-packed-yuv;
     &sub-grey;
+    &sub-y10;
+    &sub-y12;
+    &sub-y10b;
     &sub-y16;
     &sub-yuyv;
     &sub-uyvy;
@@ -596,11 +706,15 @@ information.</para>
     &sub-vyuy;
     &sub-y41p;
     &sub-yuv420;
+    &sub-yuv420m;
     &sub-yuv410;
     &sub-yuv422p;
     &sub-yuv411p;
     &sub-nv12;
+    &sub-nv12m;
+    &sub-nv12mt;
     &sub-nv16;
+    &sub-m420;
   </section>
 
   <section>
@@ -685,6 +799,11 @@ http://www.ivtvdriver.org/</ulink></para><para>The format is documented in the
 kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.hm12</filename>
 </para></entry>
           </row>
+          <row id="V4L2-PIX-FMT-CPIA1">
+            <entry><constant>V4L2_PIX_FMT_CPIA1</constant></entry>
+            <entry>'CPIA'</entry>
+            <entry>YUV format used by the gspca cpia1 driver.</entry>
+          </row>
           <row id="V4L2-PIX-FMT-SPCA501">
             <entry><constant>V4L2_PIX_FMT_SPCA501</constant></entry>
             <entry>'S501'</entry>
@@ -705,11 +824,6 @@ kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.hm
             <entry>'S561'</entry>
             <entry>Compressed GBRG Bayer format used by the gspca driver.</entry>
           </row>
-          <row id="V4L2-PIX-FMT-SGRBG10">
-            <entry><constant>V4L2_PIX_FMT_SGRBG10</constant></entry>
-            <entry>'DA10'</entry>
-            <entry>10 bit raw Bayer, expanded to 16 bits.</entry>
-          </row>
           <row id="V4L2-PIX-FMT-SGRBG10DPCM8">
             <entry><constant>V4L2_PIX_FMT_SGRBG10DPCM8</constant></entry>
             <entry>'DB10'</entry>
@@ -770,6 +884,11 @@ kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.hm
             <entry>'S920'</entry>
             <entry>YUV 4:2:0 format of the gspca sn9c20x driver.</entry>
           </row>
+          <row id="V4L2-PIX-FMT-SN9C2028">
+            <entry><constant>V4L2_PIX_FMT_SN9C2028</constant></entry>
+            <entry>'SONX'</entry>
+            <entry>Compressed GBRG bayer format of the gspca sn9c2028 driver.</entry>
+          </row>
           <row id="V4L2-PIX-FMT-STV0680">
             <entry><constant>V4L2_PIX_FMT_STV0680</constant></entry>
             <entry>'S680'</entry>
@@ -787,6 +906,20 @@ http://www.thedirks.org/winnov/</ulink></para></entry>
             <entry>'TM60'</entry>
             <entry><para>Used by Trident tm6000</para></entry>
           </row>
+          <row id="V4L2-PIX-FMT-CIT-YYVYUY">
+            <entry><constant>V4L2_PIX_FMT_CIT_YYVYUY</constant></entry>
+            <entry>'CITV'</entry>
+            <entry><para>Used by xirlink CIT, found at IBM webcams.</para>
+                   <para>Uses one line of Y then 1 line of VYUY</para>
+            </entry>
+          </row>
+          <row id="V4L2-PIX-FMT-KONICA420">
+            <entry><constant>V4L2_PIX_FMT_KONICA420</constant></entry>
+            <entry>'KONI'</entry>
+            <entry><para>Used by Konica webcams.</para>
+                   <para>YUV420 planar in blocks of 256 pixels.</para>
+            </entry>
+          </row>
           <row id="V4L2-PIX-FMT-YYUV">
             <entry><constant>V4L2_PIX_FMT_YYUV</constant></entry>
             <entry>'YYUV'</entry>