iv/linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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>
This commit is contained in:
Sakari Ailus 2012-10-21 16:02:47 -03:00 committed by Mauro Carvalho Chehab
parent 1b5901331f
commit 1202ecdc24
4 changed files with 69 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
Documentation/DocBook/media/v4l/compat.xml
View File

@ -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>

53
Documentation/DocBook/media/v4l/io.xml
View File

@ -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>

12
Documentation/DocBook/media/v4l/v4l2.xml
View File

@ -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
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>
@ -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;

4
include/uapi/linux/videodev2.h
View File

@ -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