[media] DocBook: update V4L Event Interface section

Starting with v3.1 the V4L2 API provides certain guarantees with respect to
events. Document these.

Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

1 files changed, 25 insertions, 5 deletions

diff --git a/Documentation/DocBook/media/v4l/dev-event.xml b/Documentation/DocBook/media/v4l/dev-event.xml
index be5a98f..f14ae3f 100644
--- a/Documentation/DocBook/media/v4l/dev-event.xml
+++ b/Documentation/DocBook/media/v4l/dev-event.xml
@@ -1,9 +1,10 @@
   <title>Event Interface</title>
 
-  <para>The V4L2 event interface provides means for user to get
+  <para>The V4L2 event interface provides a means for a user to get
   immediately notified on certain conditions taking place on a device.
   This might include start of frame or loss of signal events, for
-  example.
+  example. Changes in the value or state of a V4L2 control can also be
+  reported through events.
   </para>
 
   <para>To receive events, the events the user is interested in first must
@@ -15,12 +16,31 @@
 
   <para>The event subscriptions and event queues are specific to file
   handles. Subscribing an event on one file handle does not affect
-  other file handles.
-  </para>
+  other file handles.</para>
 
   <para>The information on dequeueable events is obtained by using select or
   poll system calls on video devices. The V4L2 events use POLLPRI events on
-  poll system call and exceptions on select system call.  </para>
+  poll system call and exceptions on select system call.</para>
+
+  <para>Starting with kernel 3.1 certain guarantees can be given with
+  regards to events:<orderedlist>
+	<listitem>
+	  <para>Each subscribed event has its own internal dedicated event queue.
+This means that flooding of one event type will not interfere with other
+event types.</para>
+	</listitem>
+	<listitem>
+	  <para>If the internal event queue for a particular subscribed event
+becomes full, then the oldest event in that queue will be dropped.</para>
+	</listitem>
+	<listitem>
+	  <para>Where applicable, certain event types can ensure that the payload
+of the oldest event that is about to be dropped will be merged with the payload
+of the next oldest event. Thus ensuring that no information is lost, but only an
+intermediate step leading up to that information. See the documentation for the
+event you want to subscribe to whether this is applicable for that event or not.</para>
+	</listitem>
+      </orderedlist></para>
 
   <!--
 Local Variables: