Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

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

[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

Documentation/DocBook/media/v4l/compat.xml

+12 −0
Original line number Diff line number Diff line
@@ -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>

Documentation/DocBook/media/v4l/io.xml

+42 −11
Original line number Diff line number Diff line
@@ -741,14 +741,16 @@ 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

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

Documentation/DocBook/media/v4l/v4l2.xml

+11 −1
Original line number Diff line number Diff line
@@ -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;

include/uapi/linux/videodev2.h

+4 −0
Original line number Diff line number Diff line
@@ -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