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>
diff --git a/Documentation/DocBook/v4l/v4l2.xml b/Documentation/DocBook/v4l/v4l2.xml
new file mode 100644
index 0000000..9780172
--- /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;
+