From 1202ecdc24fc88d5b144824f55ec9c8899591caf Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Sun, 21 Oct 2012 16:02:47 -0300 Subject: [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 Acked-by: Laurent Pinchart Acked-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/compat.xml | 12 +++++++ Documentation/DocBook/media/v4l/io.xml | 53 +++++++++++++++++++++++------- Documentation/DocBook/media/v4l/v4l2.xml | 12 ++++++- include/uapi/linux/videodev2.h | 4 +++ 4 files changed, 69 insertions(+), 12 deletions(-) diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index 3dd9e78815d1..ebd2bfd1ee8e 100644 --- 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. +
+ V4L2 in Linux 3.9 + + + Added timestamp types to + flags field in + v4l2_buffer. See . + + +
+
Relation of V4L2 to other Linux multimedia APIs diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index 388a34032653..09e8dcf5e9c4 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -741,17 +741,19 @@ applications when an output stream. struct timeval timestamp - For input streams this is the -system time (as returned by the gettimeofday() -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 -timestamp field. This permits -applications to monitor the drift between the video and system -clock. + For input streams this is time when the first data + byte was captured, as returned by the + clock_gettime() function for the relevant + clock id; see V4L2_BUF_FLAG_TIMESTAMP_* in + . 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 + timestamp field. This permits + applications to monitor the drift between the video and system + clock. &v4l2-timecode; @@ -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. + + V4L2_BUF_FLAG_TIMESTAMP_MASK + 0xe000 + 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. + + + V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN + 0x0000 + 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 + clock_gettime(2) using clock IDs + CLOCK_MONOTONIC and + CLOCK_REALTIME, respectively. + + + V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC + 0x2000 + The buffer timestamp has been taken from the + CLOCK_MONOTONIC clock. To access the + same clock outside V4L2, use + clock_gettime(2) . + diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 4d110b1ad3e9..8fe29427c8e4 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -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. --> + + 3.9 + 2012-12-03 + sa + Added timestamp types to + v4l2_buffer, see . + + + 3.6 2012-07-02 @@ -472,7 +482,7 @@ and discussions on the V4L mailing list. Video for Linux Two API Specification - Revision 3.6 + Revision 3.9 &sub-common; diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h index 39d2cecdf38c..94cbe26e9f00 100644 --- 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 -- cgit v1.2.3