[media] v4l: Define video buffer flags for timestamp types

Define video buffer flags for different timestamp types. Everything up to
now have used either realtime clock or monotonic clock, without a way to
tell which clock the timestamp was taken from.
Also document that the clock source of the timestamp in the timestamp field
depends on buffer flags.

[mchehab@redhat.com: fix a few wrong references to Kernel 3.8 - as this patch
 is meant for 3.9]
Signed-off-by: Sakari Ailus <sakari.ailus@iki.fi>
Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml
index 3dd9e78..ebd2bfd 100644 (file)
--- a/Documentation/DocBook/media/v4l/compat.xml
+++ b/Documentation/DocBook/media/v4l/compat.xml
@@ -2477,6 +2477,18 @@ that used it. It was originally scheduled for removal in 2.6.35.
       </orderedlist>
     </section>
 
+    <section>
+      <title>V4L2 in Linux 3.9</title>
+      <orderedlist>
+        <listitem>
+         <para>Added timestamp types to
+         <structfield>flags</structfield> field in
+         <structname>v4l2_buffer</structname>. See <xref
+         linkend="buffer-flags" />.</para>
+        </listitem>
+      </orderedlist>
+    </section>
+
     <section id="other">
       <title>Relation of V4L2 to other Linux multimedia APIs</title>
 

diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml
index 388a340..09e8dcf 100644 (file)
--- a/Documentation/DocBook/media/v4l/io.xml
+++ b/Documentation/DocBook/media/v4l/io.xml
@@ -741,17 +741,19 @@ applications when an output stream.</entry>
            <entry>struct timeval</entry>
            <entry><structfield>timestamp</structfield></entry>
            <entry></entry>
-           <entry><para>For input streams this is the
-system time (as returned by the <function>gettimeofday()</function>
-function) when the first data byte was captured. For output streams
-the data will not be displayed before this time, secondary to the
-nominal frame rate determined by the current video standard in
-enqueued order. Applications can for example zero this field to
-display frames as soon as possible. The driver stores the time at
-which the first data byte was actually sent out in the
-<structfield>timestamp</structfield> field. This permits
-applications to monitor the drift between the video and system
-clock.</para></entry>
+           <entry><para>For input streams this is time when the first data
+           byte was captured, as returned by the
+           <function>clock_gettime()</function> function for the relevant
+           clock id; see <constant>V4L2_BUF_FLAG_TIMESTAMP_*</constant> in
+           <xref linkend="buffer-flags" />. For output streams the data
+           will not be displayed before this time, secondary to the nominal
+           frame rate determined by the current video standard in enqueued
+           order. Applications can for example zero this field to display
+           frames as soon as possible. The driver stores the time at which
+           the first data byte was actually sent out in the
+           <structfield>timestamp</structfield> field. This permits
+           applications to monitor the drift between the video and system
+           clock.</para></entry>
          </row>
          <row>
            <entry>&v4l2-timecode;</entry>
@@ -1114,6 +1116,35 @@ Typically applications shall use this flag for output buffers if the data
 in this buffer has not been created by the CPU but by some DMA-capable unit,
 in which case caches have not been used.</entry>
          </row>
+         <row>
+           <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MASK</constant></entry>
+           <entry>0xe000</entry>
+           <entry>Mask for timestamp types below. To test the
+           timestamp type, mask out bits not belonging to timestamp
+           type by performing a logical and operation with buffer
+           flags and timestamp mask.</entry>
+         </row>
+         <row>
+           <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN</constant></entry>
+           <entry>0x0000</entry>
+           <entry>Unknown timestamp type. This type is used by
+           drivers before Linux 3.9 and may be either monotonic (see
+           below) or realtime (wall clock). Monotonic clock has been
+           favoured in embedded systems whereas most of the drivers
+           use the realtime clock. Either kinds of timestamps are
+           available in user space via
+           <function>clock_gettime(2)</function> using clock IDs
+           <constant>CLOCK_MONOTONIC</constant> and
+           <constant>CLOCK_REALTIME</constant>, respectively.</entry>
+         </row>
+         <row>
+           <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC</constant></entry>
+           <entry>0x2000</entry>
+           <entry>The buffer timestamp has been taken from the
+           <constant>CLOCK_MONOTONIC</constant> clock. To access the
+           same clock outside V4L2, use
+           <function>clock_gettime(2)</function> .</entry>
+         </row>
        </tbody>
       </tgroup>
     </table>

diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml
index 4d110b1..8fe2942 100644 (file)
--- a/Documentation/DocBook/media/v4l/v4l2.xml
+++ b/Documentation/DocBook/media/v4l/v4l2.xml
@@ -140,6 +140,16 @@ structs, ioctls) must be noted in more detail in the history chapter
 applications. -->
 
       <revision>
+       <revnumber>3.9</revnumber>
+       <date>2012-12-03</date>
+       <authorinitials>sa</authorinitials>
+       <revremark>Added timestamp types to
+       <structname>v4l2_buffer</structname>, see <xref
+       linkend="buffer-flags" />.
+       </revremark>
+      </revision>
+
+      <revision>
        <revnumber>3.6</revnumber>
        <date>2012-07-02</date>
        <authorinitials>hv</authorinitials>
@@ -472,7 +482,7 @@ and discussions on the V4L mailing list.</revremark>
 </partinfo>
 
 <title>Video for Linux Two API Specification</title>
- <subtitle>Revision 3.6</subtitle>
+ <subtitle>Revision 3.9</subtitle>
 
   <chapter id="common">
     &sub-common;

diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
index 39d2cec..94cbe26 100644 (file)
--- a/include/uapi/linux/videodev2.h
+++ b/include/uapi/linux/videodev2.h
@@ -701,6 +701,10 @@ struct v4l2_buffer {
 /* Cache handling flags */
 #define V4L2_BUF_FLAG_NO_CACHE_INVALIDATE      0x0800
 #define V4L2_BUF_FLAG_NO_CACHE_CLEAN           0x1000
+/* Timestamp type */
+#define V4L2_BUF_FLAG_TIMESTAMP_MASK           0xe000
+#define V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN                0x0000
+#define V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC      0x2000
 
 /**
  * struct v4l2_exportbuffer - export of video buffer as DMABUF file descriptor