Commit 1202ecdc authored by Sakari Ailus's avatar Sakari Ailus Committed by Mauro Carvalho Chehab

[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: default avatarSakari Ailus <sakari.ailus@iki.fi>
Acked-by: default avatarLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Acked-by: default avatarHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@redhat.com>
parent 1b590133
...@@ -2477,6 +2477,18 @@ that used it. It was originally scheduled for removal in 2.6.35. ...@@ -2477,6 +2477,18 @@ that used it. It was originally scheduled for removal in 2.6.35.
</orderedlist> </orderedlist>
</section> </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"> <section id="other">
<title>Relation of V4L2 to other Linux multimedia APIs</title> <title>Relation of V4L2 to other Linux multimedia APIs</title>
......
...@@ -741,17 +741,19 @@ applications when an output stream.</entry> ...@@ -741,17 +741,19 @@ applications when an output stream.</entry>
<entry>struct timeval</entry> <entry>struct timeval</entry>
<entry><structfield>timestamp</structfield></entry> <entry><structfield>timestamp</structfield></entry>
<entry></entry> <entry></entry>
<entry><para>For input streams this is the <entry><para>For input streams this is time when the first data
system time (as returned by the <function>gettimeofday()</function> byte was captured, as returned by the
function) when the first data byte was captured. For output streams <function>clock_gettime()</function> function for the relevant
the data will not be displayed before this time, secondary to the clock id; see <constant>V4L2_BUF_FLAG_TIMESTAMP_*</constant> in
nominal frame rate determined by the current video standard in <xref linkend="buffer-flags" />. For output streams the data
enqueued order. Applications can for example zero this field to will not be displayed before this time, secondary to the nominal
display frames as soon as possible. The driver stores the time at frame rate determined by the current video standard in enqueued
which the first data byte was actually sent out in the order. Applications can for example zero this field to display
<structfield>timestamp</structfield> field. This permits frames as soon as possible. The driver stores the time at which
applications to monitor the drift between the video and system the first data byte was actually sent out in the
clock.</para></entry> <structfield>timestamp</structfield> field. This permits
applications to monitor the drift between the video and system
clock.</para></entry>
</row> </row>
<row> <row>
<entry>&v4l2-timecode;</entry> <entry>&v4l2-timecode;</entry>
...@@ -1114,6 +1116,35 @@ Typically applications shall use this flag for output buffers if the data ...@@ -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 this buffer has not been created by the CPU but by some DMA-capable unit,
in which case caches have not been used.</entry> in which case caches have not been used.</entry>
</row> </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> </tbody>
</tgroup> </tgroup>
</table> </table>
......
...@@ -139,6 +139,16 @@ structs, ioctls) must be noted in more detail in the history chapter ...@@ -139,6 +139,16 @@ structs, ioctls) must be noted in more detail in the history chapter
(compat.xml), along with the possible impact on existing drivers and (compat.xml), along with the possible impact on existing drivers and
applications. --> 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> <revision>
<revnumber>3.6</revnumber> <revnumber>3.6</revnumber>
<date>2012-07-02</date> <date>2012-07-02</date>
...@@ -472,7 +482,7 @@ and discussions on the V4L mailing list.</revremark> ...@@ -472,7 +482,7 @@ and discussions on the V4L mailing list.</revremark>
</partinfo> </partinfo>
<title>Video for Linux Two API Specification</title> <title>Video for Linux Two API Specification</title>
<subtitle>Revision 3.6</subtitle> <subtitle>Revision 3.9</subtitle>
<chapter id="common"> <chapter id="common">
&sub-common; &sub-common;
......
...@@ -701,6 +701,10 @@ struct v4l2_buffer { ...@@ -701,6 +701,10 @@ struct v4l2_buffer {
/* Cache handling flags */ /* Cache handling flags */
#define V4L2_BUF_FLAG_NO_CACHE_INVALIDATE 0x0800 #define V4L2_BUF_FLAG_NO_CACHE_INVALIDATE 0x0800
#define V4L2_BUF_FLAG_NO_CACHE_CLEAN 0x1000 #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 * struct v4l2_exportbuffer - export of video buffer as DMABUF file descriptor
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment