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>

122 files changed, 36715 insertions, 1 deletions

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 9632444f6c62..ad07875febca 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -14,7 +14,7 @@ DOCBOOKS := z8530book.xml mcabook.xml device-drivers.xml \
 	    genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
 	    mac80211.xml debugobjects.xml sh.xml regulator.xml \
 	    alsa-driver-api.xml writing-an-alsa-driver.xml \
-	    tracepoint.xml
+	    tracepoint.xml media.xml
 
 ###
 # The build process is as follows (targets):
diff --git a/Documentation/DocBook/dvb/audio.xml b/Documentation/DocBook/dvb/audio.xml
new file mode 100644
index 000000000000..eeb96b8a0864
--- /dev/null
+++ b/Documentation/DocBook/dvb/audio.xml
@@ -0,0 +1,1473 @@
+<title>DVB Audio Device</title>
+<para>The DVB audio device controls the MPEG2 audio decoder of the DVB hardware. It
+can be accessed through <emphasis role="tt">/dev/dvb/adapter0/audio0</emphasis>. Data types and and
+ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/video.h</emphasis> in your
+application.
+</para>
+<para>Please note that some DVB cards don&#8217;t have their own MPEG decoder, which results in
+the omission of the audio and video device.
+</para>
+
+<section id="audio_data_types">
+<title>Audio Data Types</title>
+<para>This section describes the structures, data types and defines used when talking to the
+audio device.
+</para>
+
+<section id="audio_stream_source_t">
+<title>audio_stream_source_t</title>
+<para>The audio stream source is set through the AUDIO_SELECT_SOURCE call and can take
+the following values, depending on whether we are replaying from an internal (demux) or
+external (user write) source.
+</para>
+<programlisting>
+ typedef enum {
+	 AUDIO_SOURCE_DEMUX,
+	 AUDIO_SOURCE_MEMORY
+ } audio_stream_source_t;
+</programlisting>
+<para>AUDIO_SOURCE_DEMUX selects the demultiplexer (fed either by the frontend or the
+DVR device) as the source of the video stream. If AUDIO_SOURCE_MEMORY
+is selected the stream comes from the application through the <emphasis role="tt">write()</emphasis> system
+call.
+</para>
+
+</section>
+<section id="audio_play_state_t">
+<title>audio_play_state_t</title>
+<para>The following values can be returned by the AUDIO_GET_STATUS call representing the
+state of audio playback.
+</para>
+<programlisting>
+ typedef enum {
+	 AUDIO_STOPPED,
+	 AUDIO_PLAYING,
+	 AUDIO_PAUSED
+ } audio_play_state_t;
+</programlisting>
+
+</section>
+<section id="audio_channel_select_t">
+<title>audio_channel_select_t</title>
+<para>The audio channel selected via AUDIO_CHANNEL_SELECT is determined by the
+following values.
+</para>
+<programlisting>
+ typedef enum {
+	 AUDIO_STEREO,
+	 AUDIO_MONO_LEFT,
+	 AUDIO_MONO_RIGHT,
+ } audio_channel_select_t;
+</programlisting>
+
+</section>
+<section id="struct_audio_status">
+<title>struct audio_status</title>
+<para>The AUDIO_GET_STATUS call returns the following structure informing about various
+states of the playback operation.
+</para>
+<programlisting>
+ typedef struct audio_status {
+	 boolean AV_sync_state;
+	 boolean mute_state;
+	 audio_play_state_t play_state;
+	 audio_stream_source_t stream_source;
+	 audio_channel_select_t channel_select;
+	 boolean bypass_mode;
+ } audio_status_t;
+</programlisting>
+
+</section>
+<section id="struct_audio_mixer">
+<title>struct audio_mixer</title>
+<para>The following structure is used by the AUDIO_SET_MIXER call to set the audio
+volume.
+</para>
+<programlisting>
+ typedef struct audio_mixer {
+	 unsigned int volume_left;
+	 unsigned int volume_right;
+ } audio_mixer_t;
+</programlisting>
+
+</section>
+<section id="audio_encodings">
+<title>audio encodings</title>
+<para>A call to AUDIO_GET_CAPABILITIES returns an unsigned integer with the following
+bits set according to the hardwares capabilities.
+</para>
+<programlisting>
+ #define AUDIO_CAP_DTS    1
+ #define AUDIO_CAP_LPCM   2
+ #define AUDIO_CAP_MP1    4
+ #define AUDIO_CAP_MP2    8
+ #define AUDIO_CAP_MP3   16
+ #define AUDIO_CAP_AAC   32
+ #define AUDIO_CAP_OGG   64
+ #define AUDIO_CAP_SDDS 128
+ #define AUDIO_CAP_AC3  256
+</programlisting>
+
+</section>
+<section id="struct_audio_karaoke">
+<title>struct audio_karaoke</title>
+&l