V4L/DVB (12761): DocBook: add media API specs

The V4L and DVB API's are there for a long time. however, up to now,
no efforts were done to merge them to kernel DocBook.

This patch adds the current versions of the specs as an unique compendium.

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

1 files changed, 481 insertions, 0 deletions

diff --git a/Documentation/DocBook/v4l/v4l2.xml b/Documentation/DocBook/v4l/v4l2.xml
new file mode 100644
index 00000000000..97801725b97
--- /dev/null
+++ b/Documentation/DocBook/v4l/v4l2.xml
@@ -0,0 +1,481 @@
+ <partinfo>
+    <authorgroup>
+      <author>
+	<firstname>Michael</firstname>
+	<surname>Schimek</surname>
+	<othername role="mi">H</othername>
+	<affiliation>
+	  <address>
+	    <email>mschimek@gmx.at</email>
+	  </address>
+	</affiliation>
+      </author>
+
+      <author>
+	<firstname>Bill</firstname>
+	<surname>Dirks</surname>
+	<!-- Commented until Bill opts in to be spammed.
+	<affiliation>
+	  <address>
+	    <email>bill@thedirks.org</email>
+	  </address>
+	</affiliation> -->
+	<contrib>Original author of the V4L2 API and
+documentation.</contrib>
+      </author>
+
+      <author>
+	<firstname>Hans</firstname>
+	<surname>Verkuil</surname>
+	<contrib>Designed and documented the VIDIOC_LOG_STATUS ioctl,
+the extended control ioctls and major parts of the sliced VBI
+API.</contrib>
+	<affiliation>
+	  <address>
+	    <email>hverkuil@xs4all.nl</email>
+	  </address>
+	</affiliation>
+      </author>
+
+      <author>
+	<firstname>Martin</firstname>
+	<surname>Rubli</surname>
+	<!--
+	<affiliation>
+	  <address>
+	    <email>martin_rubli@logitech.com</email>
+	  </address>
+	</affiliation> -->
+	<contrib>Designed and documented the VIDIOC_ENUM_FRAMESIZES
+and VIDIOC_ENUM_FRAMEINTERVALS ioctls.</contrib>
+      </author>
+
+      <author>
+	<firstname>Andy</firstname>
+	<surname>Walls</surname>
+	<contrib>Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV
+MPEG stream embedded, sliced VBI data format in this specification.
+</contrib>
+	<affiliation>
+	  <address>
+	    <email>awalls@radix.net</email>
+	  </address>
+	</affiliation>
+      </author>
+
+      <author>
+	<firstname>Mauro</firstname>
+	<surname>Carvalho Chehab</surname>
+	<contrib>Documented libv4l, designed and added v4l2grab example,
+Remote Controller chapter.</contrib>
+	<affiliation>
+	  <address>
+	    <email>mchehab@redhat.com</email>
+	  </address>
+	</affiliation>
+      </author>
+    </authorgroup>
+
+    <copyright>
+      <year>1999</year>
+      <year>2000</year>
+      <year>2001</year>
+      <year>2002</year>
+      <year>2003</year>
+      <year>2004</year>
+      <year>2005</year>
+      <year>2006</year>
+      <year>2007</year>
+      <year>2008</year>
+      <year>2009</year>
+      <holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin
+Rubli, Andy Walls, Mauro Carvalho Chehab</holder>
+    </copyright>
+    <legalnotice>
+    <para>Except when explicitly stated as GPL, programming examples within
+	    this part can be used and distributed without restrictions.</para>
+    </legalnotice>
+    <revhistory>
+      <!-- Put document revisions here, newest first. -->
+      <!-- API revisions (changes and additions of defines, enums,
+structs, ioctls) must be noted in more detail in the history chapter
+(compat.sgml), along with the possible impact on existing drivers and
+applications. -->
+
+      <revision>
+	<revnumber>2.6.32</revnumber>
+	<date>2009-08-31</date>
+	<authorinitials>mcc</authorinitials>
+	<revremark>Now, revisions will match the kernel version where
+the V4L2 API changes will be used by the Linux Kernel.
+Also added Remote Controller chapter.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.29</revnumber>
+	<date>2009-08-26</date>
+	<authorinitials>ev</authorinitials>
+	<revremark>Added documentation for string controls and for FM Transmitter controls.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.28</revnumber>
+	<date>2009-08-26</date>
+	<authorinitials>gl</authorinitials>
+	<revremark>Added V4L2_CID_BAND_STOP_FILTER documentation.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.27</revnumber>
+	<date>2009-08-15</date>
+	<authorinitials>mcc</authorinitials>
+	<revremark>Added libv4l and Remote Controller documentation;
+added v4l2grab and keytable application examples.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.26</revnumber>
+	<date>2009-07-23</date>
+	<authorinitials>hv</authorinitials>
+	<revremark>Finalized the RDS capture API. Added modulator and RDS encoder
+capabilities. Added support for string controls.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.25</revnumber>
+	<date>2009-01-18</date>
+	<authorinitials>hv</authorinitials>
+	<revremark>Added pixel formats VYUY, NV16 and NV61, and changed
+the debug ioctls VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT.
+Added camera controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE,
+V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.24</revnumber>
+	<date>2008-03-04</date>
+	<authorinitials>mhs</authorinitials>
+	<revremark>Added pixel formats Y16 and SBGGR16, new controls
+and a camera controls class. Removed VIDIOC_G/S_MPEGCOMP.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.23</revnumber>
+	<date>2007-08-30</date>
+	<authorinitials>mhs</authorinitials>
+	<revremark>Fixed a typo in VIDIOC_DBG_G/S_REGISTER.
+Clarified the byte order of packed pixel formats.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.22</revnumber>
+	<date>2007-08-29</date>
+	<authorinitials>mhs</authorinitials>
+	<revremark>Added the Video Output Overlay interface, new MPEG
+controls, V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT,
+VIDIOC_DBG_G/S_REGISTER, VIDIOC_(TRY_)ENCODER_CMD,
+VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats.
+Clarifications in the cropping chapter, about RGB pixel formats, the
+mmap(), poll(), select(), read() and write() functions. Typographical
+fixes.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.21</revnumber>
+	<date>2006-12-19</date>
+	<authorinitials>mhs</authorinitials>
+	<revremark>Fixed a link in the VIDIOC_G_EXT_CTRLS section.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.20</revnumber>
+	<date>2006-11-24</date>
+	<authorinitials>mhs</authorinitials>
+	<revremark>Clarified the purpose of the audioset field in
+struct v4l2_input and v4l2_output.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.19</revnumber>
+	<date>2006-10-19</date>
+	<authorinitials>mhs</authorinitials>
+	<revremark>Documented V4L2_PIX_FMT_RGB444.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.18</revnumber>
+	<date>2006-10-18</date>
+	<authorinitials>mhs</authorinitials>
+	<revremark>Added the description of extended controls by Hans
+Verkuil. Linked V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.17</revnumber>
+	<date>2006-10-12</date>
+	<authorinitials>mhs</authorinitials>
+	<revremark>Corrected V4L2_PIX_FMT_HM12 description.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.16</revnumber>
+	<date>2006-10-08</date>
+	<authorinitials>mhs</authorinitials>
+	<revremark>VIDIOC_ENUM_FRAMESIZES and
+VIDIOC_ENUM_FRAMEINTERVALS are now part of the API.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.15</revnumber>
+	<date>2006-09-23</date>
+	<authorinitials>mhs</authorinitials>
+	<revremark>Cleaned up the bibliography, added BT.653 and
+BT.1119. capture.c/start_capturing() for user pointer I/O did not
+initialize the buffer index. Documented the V4L MPEG and MJPEG
+VID_TYPEs and V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel
+formats. See the history chapter for API changes.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.14</revnumber>
+	<date>2006-09-14</date>
+	<authorinitials>mr</authorinitials>
+	<revremark>Added VIDIOC_ENUM_FRAMESIZES and
+VIDIOC_ENUM_FRAMEINTERVALS proposal for frame format enumeration of
+digital devices.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.13</revnumber>
+	<date>2006-04-07</date>
+	<authorinitials>mhs</authorinitials>
+	<revremark>Corrected the description of struct v4l2_window
+clips. New V4L2_STD_ and V4L2_TUNER_MODE_LANG1_LANG2
+defines.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.12</revnumber>
+	<date>2006-02-03</date>
+	<authorinitials>mhs</authorinitials>
+	<revremark>Corrected the description of struct
+v4l2_captureparm and v4l2_outputparm.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.11</revnumber>
+	<date>2006-01-27</date>
+	<authorinitials>mhs</authorinitials>
+	<revremark>Improved the description of struct
+v4l2_tuner.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.10</revnumber>
+	<date>2006-01-10</date>
+	<authorinitials>mhs</authorinitials>
+	<revremark>VIDIOC_G_INPUT and VIDIOC_S_PARM
+clarifications.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.9</revnumber>
+	<date>2005-11-27</date>
+	<authorinitials>mhs</authorinitials>
+	<revremark>Improved the 525 line numbering diagram. Hans
+Verkuil and I rewrote the sliced VBI section. He also contributed a
+VIDIOC_LOG_STATUS page. Fixed VIDIOC_S_STD call in the video standard
+selection example. Various updates.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.8</revnumber>
+	<date>2004-10-04</date>
+	<authorinitials>mhs</authorinitials>
+	<revremark>Somehow a piece of junk slipped into the capture
+example, removed.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.7</revnumber>
+	<date>2004-09-19</date>
+	<authorinitials>mhs</authorinitials>
+	<revremark>Fixed video standard selection, control
+enumeration, downscaling and aspect example. Added read and user
+pointer i/o to video capture example.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.6</revnumber>
+	<date>2004-08-01</date>
+	<authorinitials>mhs</authorinitials>
+	<revremark>v4l2_buffer changes, added video capture example,
+various corrections.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.5</revnumber>
+	<date>2003-11-05</date>
+	<authorinitials>mhs</authorinitials>
+	<revremark>Pixel format erratum.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.4</revnumber>
+	<date>2003-09-17</date>
+	<authorinitials>mhs</authorinitials>
+	<revremark>Corrected source and Makefile to generate a PDF.
+SGML fixes. Added latest API changes. Closed gaps in the history
+chapter.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.3</revnumber>
+	<date>2003-02-05</date>
+	<authorinitials>mhs</authorinitials>
+	<revremark>Another draft, more corrections.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.2</revnumber>
+	<date>2003-01-15</date>
+	<authorinitials>mhs</authorinitials>
+	<revremark>Second draft, with corrections pointed out by Gerd
+Knorr.</revremark>
+      </revision>
+
+      <revision>
+	<revnumber>0.1</revnumber>
+	<date>2002-12-01</date>
+	<authorinitials>mhs</authorinitials>
+	<revremark>First draft, based on documentation by Bill Dirks
+and discussions on the V4L mailing list.</revremark>
+      </revision>
+    </revhistory>
+</partinfo>
+
+<title>Video for Linux Two API Specification</title>
+ <subtitle>Revision 2.6.32</subtitle>
+
+  <chapter id="common">
+    &sub-common;
+  </chapter>
+
+  <chapter id="pixfmt">
+    &sub-pixfmt;
+  </chapter>
+
+  <chapter id="io">
+    &sub-io;
+  </chapter>
+
+  <chapter id="devices">
+    <title>Interfaces</title>
+
+    <section id="capture"> &sub-dev-capture; </section>
+    <section id="overlay"> &sub-dev-overlay; </section>
+    <section id="output"> &sub-dev-output; </section>
+    <section id="osd"> &sub-dev-osd; </section>
+    <section id="codec"> &sub-dev-codec; </section>
+    <section id="effect"> &sub-dev-effect; </section>
+    <section id="raw-vbi"> &sub-dev-raw-vbi; </section>
+    <section id="sliced"> &sub-dev-sliced-vbi; </section>
+    <section id="ttx"> &sub-dev-teletext; </section>
+    <section id="radio"> &sub-dev-radio; </section>
+    <section id="rds"> &sub-dev-rds; </section>
+  </chapter>
+
+  <chapter id="driver">
+	  &sub-driver;
+  </chapter>
+
+  <chapter id="libv4l">
+	  &sub-libv4l;
+  </chapter>
+
+  <chapter id="compat">
+	  &sub-compat;
+  </chapter>
+
+  <appendix id="function_ref">
+  <title>Function Reference</title>
+  <reference id="user-func">
+
+    <!-- Keep this alphabetically sorted. -->
+
+    &sub-close;
+    &sub-ioctl;
+    <!-- All ioctls go here. -->
+    &sub-cropcap;
+    &sub-dbg-g-chip-ident;
+    &sub-dbg-g-register;
+    &sub-encoder-cmd;
+    &sub-enumaudio;
+    &sub-enumaudioout;
+    &sub-enum-fmt;
+    &sub-enum-framesizes;
+    &sub-enum-frameintervals;
+    &sub-enuminput;
+    &sub-enumoutput;
+    &sub-enumstd;
+    &sub-g-audio;
+    &sub-g-audioout;
+    &sub-g-crop;
+    &sub-g-ctrl;
+    &sub-g-enc-index;
+    &sub-g-ext-ctrls;
+    &sub-g-fbuf;
+    &sub-g-fmt;
+    &sub-g-frequency;
+    &sub-g-input;
+    &sub-g-jpegcomp;
+    &sub-g-modulator;
+    &sub-g-output;
+    &sub-g-parm;
+    &sub-g-priority;
+    &sub-g-sliced-vbi-cap;
+    &sub-g-std;
+    &sub-g-tuner;
+    &sub-log-status;
+    &sub-overlay;
+    &sub-qbuf;
+    &sub-querybuf;
+    &sub-querycap;
+    &sub-queryctrl;
+    &sub-querystd;
+    &sub-reqbufs;
+    &sub-s-hw-freq-seek;
+    &sub-streamon;
+    <!-- End of ioctls. -->
+    &sub-mmap;
+    &sub-munmap;
+    &sub-open;
+    &sub-poll;
+    &sub-read;
+    &sub-select;
+    &sub-write;
+  </reference>
+  </appendix>
+
+  <appendix id="videodev">
+    <title>Video For Linux Two Header File</title>
+    &sub-videodev2-h;
+  </appendix>
+
+  <appendix id="capture-example">
+    <title>Video Capture Example</title>
+    &sub-capture-c;
+  </appendix>
+
+  <appendix id="v4l2grab-example">
+    <title>Video Grabber example using libv4l</title>
+    <para>This program demonstrates how to grab V4L2 images in ppm format by
+using libv4l handlers. The advantage is that this grabber can potentially work
+with any V4L2 driver.</para>
+    &sub-v4l2grab-c;
+  </appendix>
+
+  &sub-media-indices;
+
+  &sub-biblio;
+