Commit 872484ce authored by Sakari Ailus's avatar Sakari Ailus Committed by Mauro Carvalho Chehab
Browse files

[media] v4l: Add timestamp source flags, mask and document them 



Some devices do not produce timestamps that correspond to the end of the
frame. The user space should be informed on the matter. This patch achieves
that by adding buffer flags (and a mask) for timestamp sources since more
possible timestamping points are expected than just two.

A three-bit mask is defined (V4L2_BUF_FLAG_TSTAMP_SRC_MASK) and two of the
eight possible values is are defined V4L2_BUF_FLAG_TSTAMP_SRC_EOF for end of
frame (value zero) V4L2_BUF_FLAG_TSTAMP_SRC_SOE for start of exposure (next
value).

Signed-off-by: default avatarSakari Ailus <sakari.ailus@iki.fi>
Acked-by: default avatarKamil Debski <k.debski@samsung.com>
Acked-by: default avatarHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: default avatarMauro Carvalho Chehab <m.chehab@samsung.com>
parent c57ff792

Documentation/DocBook/media/v4l/io.xml

+30 −6
Original line number Diff line number Diff line
@@ -653,12 +653,6 @@ plane, are stored in struct <structname>v4l2_plane</structname> instead. 
In that case, struct <structname>v4l2_buffer</structname> contains an array of

plane structures.</para>



      <para>For timestamp types that are sampled from the system clock

(V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC) it is guaranteed that the timestamp is

taken after the complete frame has been received (or transmitted in

case of video output devices). For other kinds of

timestamps this may vary depending on the driver.</para>



    <table frame="none" pgwide="1" id="v4l2-buffer">

      <title>struct <structname>v4l2_buffer</structname></title>

      <tgroup cols="4">
@@ -1125,6 +1119,36 @@ in which case caches have not been used.</entry> 
	    <entry>The CAPTURE buffer timestamp has been taken from the

	    corresponding OUTPUT buffer. This flag applies only to mem2mem devices.</entry>

	  </row>

	  <row>

	    <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant></entry>

	    <entry>0x00070000</entry>

	    <entry>Mask for timestamp sources below. The timestamp source

	    defines the point of time the timestamp is taken in relation to

	    the frame. Logical 'and' operation between the

	    <structfield>flags</structfield> field and

	    <constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant> produces the

	    value of the timestamp source.</entry>

	  </row>

	  <row>

	    <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_EOF</constant></entry>

	    <entry>0x00000000</entry>

	    <entry>End Of Frame. The buffer timestamp has been taken

	    when the last pixel of the frame has been received or the

	    last pixel of the frame has been transmitted. In practice,

	    software generated timestamps will typically be read from

	    the clock a small amount of time after the last pixel has

	    been received or transmitten, depending on the system and

	    other activity in it.</entry>

	  </row>

	  <row>

	    <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_SOE</constant></entry>

	    <entry>0x00010000</entry>

	    <entry>Start Of Exposure. The buffer timestamp has been

	    taken when the exposure of the frame has begun. This is

	    only valid for the

	    <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> buffer

	    type.</entry>

	  </row>

	</tbody>

      </tgroup>

    </table>

drivers/media/v4l2-core/videobuf2-core.c

+3 −1
Original line number Diff line number Diff line
@@ -2227,7 +2227,9 @@ int vb2_queue_init(struct vb2_queue *q) 
	    WARN_ON(!q->io_modes)	  ||

	    WARN_ON(!q->ops->queue_setup) ||

	    WARN_ON(!q->ops->buf_queue)   ||

	    WARN_ON(q->timestamp_flags & ~V4L2_BUF_FLAG_TIMESTAMP_MASK))

	    WARN_ON(q->timestamp_flags &

		    ~(V4L2_BUF_FLAG_TIMESTAMP_MASK |

		      V4L2_BUF_FLAG_TSTAMP_SRC_MASK)))

		return -EINVAL;



	/* Warn that the driver should choose an appropriate timestamp type */

include/media/videobuf2-core.h

+2 −0
Original line number Diff line number Diff line
@@ -312,6 +312,8 @@ struct v4l2_fh; 
 * @buf_struct_size: size of the driver-specific buffer structure;

 *		"0" indicates the driver doesn't want to use a custom buffer

 *		structure type, so sizeof(struct vb2_buffer) will is used

 * @timestamp_flags: Timestamp flags; V4L2_BUF_FLAGS_TIMESTAMP_* and

 *		V4L2_BUF_FLAGS_TSTAMP_SRC_*

 * @gfp_flags:	additional gfp flags used when allocating the buffers.

 *		Typically this is 0, but it may be e.g. GFP_DMA or __GFP_DMA32

 *		to force the buffer allocation to a specific memory zone.

include/uapi/linux/videodev2.h

+4 −0
Original line number Diff line number Diff line
@@ -700,6 +700,10 @@ struct v4l2_buffer { 
#define V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN		0x00000000

#define V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC	0x00002000

#define V4L2_BUF_FLAG_TIMESTAMP_COPY		0x00004000

/* Timestamp sources. */

#define V4L2_BUF_FLAG_TSTAMP_SRC_MASK		0x00070000

#define V4L2_BUF_FLAG_TSTAMP_SRC_EOF		0x00000000

#define V4L2_BUF_FLAG_TSTAMP_SRC_SOE		0x00010000



/**

 * struct v4l2_exportbuffer - export of video buffer as DMABUF file descriptor

CRA Git | Maintained and supported by SUSTech CRA and CCSE