From f1fd1cb70a9d070fe3330a1b8583683139ac0d41 Mon Sep 17 00:00:00 2001
From: Hans Verkuil <hverkuil@xs4all.nl>
Date: Tue, 7 May 2013 08:06:11 -0300
Subject: [PATCH] --- yaml --- r: 377172 b: refs/heads/master c:
 6e7df1cd373d688486b0b0b6626cb32f59ebdcfa h: refs/heads/master v: v3

---
 [refs]                                        |  2 +-
 .../DocBook/media/v4l/dev-codec.xml           | 35 ++++++++++++-------
 2 files changed, 23 insertions(+), 14 deletions(-)

diff --git a/[refs] b/[refs]
index 44221d439620..d79d39e4220d 100644
--- a/[refs]
+++ b/[refs]
@@ -1,2 +1,2 @@
 ---
-refs/heads/master: ea457ad9dbf32c8d22cc1cc39b4c1a2e06bf9b89
+refs/heads/master: 6e7df1cd373d688486b0b0b6626cb32f59ebdcfa
diff --git a/trunk/Documentation/DocBook/media/v4l/dev-codec.xml b/trunk/Documentation/DocBook/media/v4l/dev-codec.xml
index dca0ecd54dc6..ff44c16fc080 100644
--- a/trunk/Documentation/DocBook/media/v4l/dev-codec.xml
+++ b/trunk/Documentation/DocBook/media/v4l/dev-codec.xml
@@ -1,18 +1,27 @@
   <title>Codec Interface</title>
 
-  <note>
-    <title>Suspended</title>
+  <para>A V4L2 codec can compress, decompress, transform, or otherwise
+convert video data from one format into another format, in memory. Typically
+such devices are memory-to-memory devices (i.e. devices with the
+<constant>V4L2_CAP_VIDEO_M2M</constant> or <constant>V4L2_CAP_VIDEO_M2M_MPLANE</constant>
+capability set).
+</para>
 
-    <para>This interface has been be suspended from the V4L2 API
-implemented in Linux 2.6 until we have more experience with codec
-device interfaces.</para>
-  </note>
+  <para>A memory-to-memory video node acts just like a normal video node, but it
+supports both output (sending frames from memory to the codec hardware) and
+capture (receiving the processed frames from the codec hardware into memory)
+stream I/O. An application will have to setup the stream
+I/O for both sides and finally call &VIDIOC-STREAMON; for both capture and output
+to start the codec.</para>
 
-  <para>A V4L2 codec can compress, decompress, transform, or otherwise
-convert video data from one format into another format, in memory.
-Applications send data to be converted to the driver through a
-&func-write; call, and receive the converted data through a
-&func-read; call. For efficiency a driver may also support streaming
-I/O.</para>
+  <para>Video compression codecs use the MPEG controls to setup their codec parameters
+(note that the MPEG controls actually support many more codecs than just MPEG).
+See <xref linkend="mpeg-controls"></xref>.</para>
 
-  <para>[to do]</para>
+  <para>Memory-to-memory devices can often be used as a shared resource: you can
+open the video node multiple times, each application setting up their own codec properties
+that are local to the file handle, and each can use it independently from the others.
+The driver will arbitrate access to the codec and reprogram it whenever another file
+handler gets access. This is different from the usual video node behavior where the video properties
+are global to the device (i.e. changing something through one file handle is visible
+through another file handle).</para>