[PATCH 1/3] v4l: Move event documentation from SUBSCRIBE_EVENT to DQEVENT

[PATCH 1/3] v4l: Move event documentation from SUBSCRIBE_EVENT to DQEVENT

[Sakari Ailus]

Move documentation of structures used in DQEVENT from SUBSCRIBE_EVENT to
DQEVENT.

Signed-off-by: Sakari Ailus <sakari.ailus@iki.fi>
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
---
 Documentation/DocBook/media/v4l/vidioc-dqevent.xml |  107 ++++++++++++++++++++
 .../DocBook/media/v4l/vidioc-subscribe-event.xml   |  107 --------------------
 2 files changed, 107 insertions(+), 107 deletions(-)

diff --git a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
index 7769642..5200b68 100644
--- a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
@@ -135,6 +135,113 @@
       </tgroup>
     </table>
 
+    <table frame="none" pgwide="1" id="v4l2-event-vsync">
+      <title>struct <structname>v4l2_event_vsync</structname></title>
+      <tgroup cols="3">
+	&cs-str;
+	<tbody valign="top">
+	  <row>
+	    <entry>__u8</entry>
+	    <entry><structfield>field</structfield></entry>
+	    <entry>The upcoming field. See &v4l2-field;.</entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </table>
+
+    <table frame="none" pgwide="1" id="v4l2-event-ctrl">
+      <title>struct <structname>v4l2_event_ctrl</structname></title>
+      <tgroup cols="4">
+	&cs-str;
+	<tbody valign="top">
+	  <row>
+	    <entry>__u32</entry>
+	    <entry><structfield>changes</structfield></entry>
+	    <entry></entry>
+	    <entry>A bitmask that tells what has changed. See <xref linkend="changes-flags" />.</entry>
+	  </row>
+	  <row>
+	    <entry>__u32</entry>
+	    <entry><structfield>type</structfield></entry>
+	    <entry></entry>
+	    <entry>The type of the control. See &v4l2-ctrl-type;.</entry>
+	  </row>
+	  <row>
+	    <entry>union (anonymous)</entry>
+	    <entry></entry>
+	    <entry></entry>
+	    <entry></entry>
+	  </row>
+	  <row>
+	    <entry></entry>
+	    <entry>__s32</entry>
+	    <entry><structfield>value</structfield></entry>
+	    <entry>The 32-bit value of the control for 32-bit control types.
+		This is 0 for string controls since the value of a string
+		cannot be passed using &VIDIOC-DQEVENT;.</entry>
+	  </row>
+	  <row>
+	    <entry></entry>
+	    <entry>__s64</entry>
+	    <entry><structfield>value64</structfield></entry>
+	    <entry>The 64-bit value of the control for 64-bit control types.</entry>
+	  </row>
+	  <row>
+	    <entry>__u32</entry>
+	    <entry><structfield>flags</structfield></entry>
+	    <entry></entry>
+	    <entry>The control flags. See <xref linkend="control-flags" />.</entry>
+	  </row>
+	  <row>
+	    <entry>__s32</entry>
+	    <entry><structfield>minimum</structfield></entry>
+	    <entry></entry>
+	    <entry>The minimum value of the control. See &v4l2-queryctrl;.</entry>
+	  </row>
+	  <row>
+	    <entry>__s32</entry>
+	    <entry><structfield>maximum</structfield></entry>
+	    <entry></entry>
+	    <entry>The maximum value of the control. See &v4l2-queryctrl;.</entry>
+	  </row>
+	  <row>
+	    <entry>__s32</entry>
+	    <entry><structfield>step</structfield></entry>
+	    <entry></entry>
+	    <entry>The step value of the control. See &v4l2-queryctrl;.</entry>
+	  </row>
+	  <row>
+	    <entry>__s32</entry>
+	    <entry><structfield>default_value</structfield></entry>
+	    <entry></entry>
+	    <entry>The default value value of the control. See &v4l2-queryctrl;.</entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </table>
+
+    <table pgwide="1" frame="none" id="changes-flags">
+      <title>Changes</title>
+      <tgroup cols="3">
+	&cs-def;
+	<tbody valign="top">
+	  <row>
+	    <entry><constant>V4L2_EVENT_CTRL_CH_VALUE</constant></entry>
+	    <entry>0x0001</entry>
+	    <entry>This control event was triggered because the value of the control
+		changed. Special case: if a button control is pressed, then this
+		event is sent as well, even though there is not explicit value
+		associated with a button control.</entry>
+	  </row>
+	  <row>
+	    <entry><constant>V4L2_EVENT_CTRL_CH_FLAGS</constant></entry>
+	    <entry>0x0002</entry>
+	    <entry>This control event was triggered because the control flags
+		changed.</entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </table>
   </refsect1>
   <refsect1>
     &return-value;
diff --git a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
index 69c0d8a..275be96 100644
--- a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
@@ -183,113 +183,6 @@
       </tgroup>
     </table>
 
-    <table frame="none" pgwide="1" id="v4l2-event-vsync">
-      <title>struct <structname>v4l2_event_vsync</structname></title>
-      <tgroup cols="3">
-	&cs-str;
-	<tbody valign="top">
-	  <row>
-	    <entry>__u8</entry>
-	    <entry><structfield>field</structfield></entry>
-	    <entry>The upcoming field. See &v4l2-field;.</entry>
-	  </row>
-	</tbody>
-      </tgroup>
-    </table>
-
-    <table frame="none" pgwide="1" id="v4l2-event-ctrl">
-      <title>struct <structname>v4l2_event_ctrl</structname></title>
-      <tgroup cols="4">
-	&cs-str;
-	<tbody valign="top">
-	  <row>
-	    <entry>__u32</entry>
-	    <entry><structfield>changes</structfield></entry>
-	    <entry></entry>
-	    <entry>A bitmask that tells what has changed. See <xref linkend="changes-flags" />.</entry>
-	  </row>
-	  <row>
-	    <entry>__u32</entry>
-	    <entry><structfield>type</structfield></entry>
-	    <entry></entry>
-	    <entry>The type of the control. See &v4l2-ctrl-type;.</entry>
-	  </row>
-	  <row>
-	    <entry>union (anonymous)</entry>
-	    <entry></entry>
-	    <entry></entry>
-	    <entry></entry>
-	  </row>
-	  <row>
-	    <entry></entry>
-	    <entry>__s32</entry>
-	    <entry><structfield>value</structfield></entry>
-	    <entry>The 32-bit value of the control for 32-bit control types.
-		This is 0 for string controls since the value of a string
-		cannot be passed using &VIDIOC-DQEVENT;.</entry>
-	  </row>
-	  <row>
-	    <entry></entry>
-	    <entry>__s64</entry>
-	    <entry><structfield>value64</structfield></entry>
-	    <entry>The 64-bit value of the control for 64-bit control types.</entry>
-	  </row>
-	  <row>
-	    <entry>__u32</entry>
-	    <entry><structfield>flags</structfield></entry>
-	    <entry></entry>
-	    <entry>The control flags. See <xref linkend="control-flags" />.</entry>
-	  </row>
-	  <row>
-	    <entry>__s32</entry>
-	    <entry><structfield>minimum</structfield></entry>
-	    <entry></entry>
-	    <entry>The minimum value of the control. See &v4l2-queryctrl;.</entry>
-	  </row>
-	  <row>
-	    <entry>__s32</entry>
-	    <entry><structfield>maximum</structfield></entry>
-	    <entry></entry>
-	    <entry>The maximum value of the control. See &v4l2-queryctrl;.</entry>
-	  </row>
-	  <row>
-	    <entry>__s32</entry>
-	    <entry><structfield>step</structfield></entry>
-	    <entry></entry>
-	    <entry>The step value of the control. See &v4l2-queryctrl;.</entry>
-	  </row>
-	  <row>
-	    <entry>__s32</entry>
-	    <entry><structfield>default_value</structfield></entry>
-	    <entry></entry>
-	    <entry>The default value value of the control. See &v4l2-queryctrl;.</entry>
-	  </row>
-	</tbody>
-      </tgroup>
-    </table>
-
-    <table pgwide="1" frame="none" id="changes-flags">
-      <title>Changes</title>
-      <tgroup cols="3">
-	&cs-def;
-	<tbody valign="top">
-	  <row>
-	    <entry><constant>V4L2_EVENT_CTRL_CH_VALUE</constant></entry>
-	    <entry>0x0001</entry>
-	    <entry>This control event was triggered because the value of the control
-		changed. Special case: if a button control is pressed, then this
-		event is sent as well, even though there is not explicit value
-		associated with a button control.</entry>
-	  </row>
-	  <row>
-	    <entry><constant>V4L2_EVENT_CTRL_CH_FLAGS</constant></entry>
-	    <entry>0x0002</entry>
-	    <entry>This control event was triggered because the control flags
-		changed.</entry>
-	  </row>
-	</tbody>
-      </tgroup>
-    </table>
   </refsect1>
   <refsect1>
     &return-value;
-- 
1.7.2.5

[PATCH 2/3] v4l: events: Define frame start event

[Sakari Ailus]

Define a frame start event to tell user space when the reception of a frame
starts.

Signed-off-by: Sakari Ailus <sakari.ailus@iki.fi>
---
 Documentation/DocBook/media/v4l/vidioc-dqevent.xml |   23 ++++++++++++++++++++
 .../DocBook/media/v4l/vidioc-subscribe-event.xml   |   18 +++++++++++++++
 include/linux/videodev2.h                          |   12 +++++++--
 3 files changed, 50 insertions(+), 3 deletions(-)

diff --git a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
index 5200b68..1d03313 100644
--- a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
@@ -88,6 +88,12 @@
 	  </row>
 	  <row>
 	    <entry></entry>
+	    <entry>&v4l2-event-frame-sync;</entry>
+            <entry><structfield>frame</structfield></entry>
+	    <entry>Event data for event V4L2_EVENT_FRAME_SYNC.</entry>
+	  </row>
+	  <row>
+	    <entry></entry>
 	    <entry>__u8</entry>
             <entry><structfield>data</structfield>[64]</entry>
 	    <entry>Event data. Defined by the event type. The union
@@ -220,6 +226,23 @@
       </tgroup>
     </table>
 
+    <table frame="none" pgwide="1" id="v4l2-event-frame-sync">
+      <title>struct <structname>v4l2_event_frame_sync</structname></title>
+      <tgroup cols="3">
+	&cs-str;
+	<tbody valign="top">
+	  <row>
+	    <entry>__u32</entry>
+	    <entry><structfield>buffer_sequence</structfield></entry>
+	    <entry>
+	      The sequence number of the buffer to be handled next or
+	      currently handled by the driver.
+	    </entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </table>
+
     <table pgwide="1" frame="none" id="changes-flags">
       <title>Changes</title>
       <tgroup cols="3">
diff --git a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
index 275be96..812b63c 100644
--- a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
@@ -139,6 +139,24 @@
 	    </entry>
 	  </row>
 	  <row>
+	    <entry><constant>V4L2_EVENT_FRAME_SYNC</constant></entry>
+	    <entry>4</entry>
+	    <entry>
+	      <para>Triggered immediately when the reception of a
+	      frame has begun. This event has a
+	      &v4l2-event-frame-sync; associated with it.</para>
+
+	      <para>A driver will only generate this event when the
+	      hardware can generate it. This might not be the case
+	      e.g. when the hardware has no DMA buffer to write the
+	      image data to. In such cases the
+	      <structfield>buffer_sequence</structfield> field in
+	      &v4l2-event-frame-sync; will not be incremented either.
+	      This causes two consecutive buffer sequence numbers to
+	      have n times frame interval in between them.</para>
+	    </entry>
+	  </row>
+	  <row>
 	    <entry><constant>V4L2_EVENT_PRIVATE_START</constant></entry>
 	    <entry>0x08000000</entry>
 	    <entry>Base event number for driver-private events.</entry>
diff --git a/include/linux/videodev2.h b/include/linux/videodev2.h
index fca24cc..056a49e 100644
--- a/include/linux/videodev2.h
+++ b/include/linux/videodev2.h
@@ -2006,6 +2006,7 @@ struct v4l2_streamparm {
 #define V4L2_EVENT_VSYNC			1
 #define V4L2_EVENT_EOS				2
 #define V4L2_EVENT_CTRL				3
+#define V4L2_EVENT_FRAME_SYNC			4
 #define V4L2_EVENT_PRIVATE_START		0x08000000
 
 /* Payload for V4L2_EVENT_VSYNC */
@@ -2032,12 +2033,17 @@ struct v4l2_event_ctrl {
 	__s32 default_value;
 };
 
+struct v4l2_event_frame_sync {
+	__u32 buffer_sequence;
+};
+
 struct v4l2_event {
 	__u32				type;
 	union {
-		struct v4l2_event_vsync vsync;
-		struct v4l2_event_ctrl	ctrl;
-		__u8			data[64];
+		struct v4l2_event_vsync		vsync;
+		struct v4l2_event_ctrl		ctrl;
+		struct v4l2_event_frame_sync	frame_sync;
+		__u8				data[64];
 	} u;
 	__u32				pending;
 	__u32				sequence;
-- 
1.7.2.5

[PATCH 3/3] omap3isp: ccdc: Make frame start event generic

[Sakari Ailus]

The ccdc block in the omap3isp produces frame start events. These events
were previously specific to the omap3isp. Make them generic.

Also add sequence number to the frame. This is stored to the id field.

Signed-off-by: Sakari Ailus <sakari.ailus@iki.fi>
---
 Documentation/video4linux/omap3isp.txt |    9 +++++----
 drivers/media/video/omap3isp/ispccdc.c |   11 +++++++++--
 include/linux/omap3isp.h               |    2 --
 3 files changed, 14 insertions(+), 8 deletions(-)

diff --git a/Documentation/video4linux/omap3isp.txt b/Documentation/video4linux/omap3isp.txt
index 69be2c7..5dd1439 100644
--- a/Documentation/video4linux/omap3isp.txt
+++ b/Documentation/video4linux/omap3isp.txt
@@ -70,10 +70,11 @@ Events
 The OMAP 3 ISP driver does support the V4L2 event interface on CCDC and
 statistics (AEWB, AF and histogram) subdevs.
 
-The CCDC subdev produces V4L2_EVENT_OMAP3ISP_HS_VS type event on HS_VS
-interrupt which is used to signal frame start. The event is triggered exactly
-when the reception of the first line of the frame starts in the CCDC module.
-The event can be subscribed on the CCDC subdev.
+The CCDC subdev produces V4L2_EVENT_FRAME_SYNC type event on HS_VS
+interrupt which is used to signal frame start. Earlier version of this
+driver used V4L2_EVENT_OMAP3ISP_HS_VS for this purpose. The event is
+triggered exactly when the reception of the first line of the frame starts
+in the CCDC module. The event can be subscribed on the CCDC subdev.
 
 (When using parallel interface one must pay account to correct configuration
 of the VS signal polarity. This is automatically correct when using the serial
diff --git a/drivers/media/video/omap3isp/ispccdc.c b/drivers/media/video/omap3isp/ispccdc.c
index 6766247..842a930 100644
--- a/drivers/media/video/omap3isp/ispccdc.c
+++ b/drivers/media/video/omap3isp/ispccdc.c
@@ -1402,11 +1402,14 @@ static int __ccdc_handle_stopping(struct isp_ccdc_device *ccdc, u32 event)
 
 static void ccdc_hs_vs_isr(struct isp_ccdc_device *ccdc)
 {
+	struct isp_pipeline *pipe =
+		to_isp_pipeline(&ccdc->video_out.video.entity);
 	struct video_device *vdev = &ccdc->subdev.devnode;
 	struct v4l2_event event;
 
 	memset(&event, 0, sizeof(event));
-	event.type = V4L2_EVENT_OMAP3ISP_HS_VS;
+	event.type = V4L2_EVENT_FRAME_SYNC;
+	event.u.frame_sync.buffer_sequence = atomic_read(&pipe->frame_number);
 
 	v4l2_event_queue(vdev, &event);
 }
@@ -1688,7 +1691,11 @@ static long ccdc_ioctl(struct v4l2_subdev *sd, unsigned int cmd, void *arg)
 static int ccdc_subscribe_event(struct v4l2_subdev *sd, struct v4l2_fh *fh,
 				struct v4l2_event_subscription *sub)
 {
-	if (sub->type != V4L2_EVENT_OMAP3ISP_HS_VS)
+	if (sub->type != V4L2_EVENT_FRAME_SYNC)
+		return -EINVAL;
+
+	/* line number is zero at frame start */
+	if (sub->id != 0)
 		return -EINVAL;
 
 	return v4l2_event_subscribe(fh, sub, OMAP3ISP_CCDC_NEVENTS);
diff --git a/include/linux/omap3isp.h b/include/linux/omap3isp.h
index b6111f8..c73a34c 100644
--- a/include/linux/omap3isp.h
+++ b/include/linux/omap3isp.h
@@ -62,14 +62,12 @@
  * V4L2_EVENT_OMAP3ISP_AEWB: AEWB statistics data ready
  * V4L2_EVENT_OMAP3ISP_AF: AF statistics data ready
  * V4L2_EVENT_OMAP3ISP_HIST: Histogram statistics data ready
- * V4L2_EVENT_OMAP3ISP_HS_VS: Horizontal/vertical synchronization detected
  */
 
 #define V4L2_EVENT_OMAP3ISP_CLASS	(V4L2_EVENT_PRIVATE_START | 0x100)
 #define V4L2_EVENT_OMAP3ISP_AEWB	(V4L2_EVENT_OMAP3ISP_CLASS | 0x1)
 #define V4L2_EVENT_OMAP3ISP_AF		(V4L2_EVENT_OMAP3ISP_CLASS | 0x2)
 #define V4L2_EVENT_OMAP3ISP_HIST	(V4L2_EVENT_OMAP3ISP_CLASS | 0x3)
-#define V4L2_EVENT_OMAP3ISP_HS_VS	(V4L2_EVENT_OMAP3ISP_CLASS | 0x4)
 
 struct omap3isp_stat_event_status {
 	__u32 frame_number;
-- 
1.7.2.5

[PATCH 0/3] Frame synchronisation events and support for them in the OMAP 3 ISP driver

[Sakari Ailus]

Hi all,

The OMAP 3 ISP driver implements an HS_VS event which is triggered when
the reception of a frame begins. This functionality is very, very likely
not specific to OMAP 3 ISP so it should be standardised.

I have a few patches to do that. Additionally the next expected buffer
sequence number is provided with the event, unlike earlier.

The questions I had over the RFC (under otherwise same subject field on
this list) have been resolved:

1) Other frame synchronisation events, if they ever are needed, can be
implemented by using the id field as the line number the event should be
triggered on, as proposed by Sylwester and Hans. Currently, the id field
is not separately mentioned in the documentation, meaning that
FRAME_SYNC events have id field set to 0 meaning frame start.

2) It was also concluded that the buffer sequence number is specific to
FRAME_SYNC event and deserves its own struct: struct v4l2_event_frame_sync.

Changes to the RFC:

- Renamed V4L2_EVENT_FRAME_START to V4L2_EVENT_FRAME_SYNC.
- Removed extra reference to V4L2_EVENT_FRAME_START in documentation; it
is mentioned in the same page struct v4l2_event_frame_sync is related to it.
- The OMAP 3 ISP driver check that the id field is zero in anticipation
of such events.

-- 
Sakari Ailus
sakari.ailus@iki.fi

Re: [PATCH 2/3] v4l: events: Define frame start event

[Laurent Pinchart]

Hi Sakari,

On Tuesday 26 July 2011 20:49:43 Sakari Ailus wrote:
> Define a frame start event to tell user space when the reception of a frame
> starts.

You might want to rename 'frame start' to 'frame sync' in the subject and 
commit message as well.

> Signed-off-by: Sakari Ailus <sakari.ailus@iki.fi>
> ---
>  Documentation/DocBook/media/v4l/vidioc-dqevent.xml |   23
> ++++++++++++++++++++ .../DocBook/media/v4l/vidioc-subscribe-event.xml   | 
>  18 +++++++++++++++ include/linux/videodev2.h                          |  
> 12 +++++++-- 3 files changed, 50 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
> b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml index
> 5200b68..1d03313 100644
> --- a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
> +++ b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
> @@ -88,6 +88,12 @@
>  	  </row>
>  	  <row>
>  	    <entry></entry>
> +	    <entry>&v4l2-event-frame-sync;</entry>
> +            <entry><structfield>frame</structfield></entry>
> +	    <entry>Event data for event V4L2_EVENT_FRAME_SYNC.</entry>
> +	  </row>
> +	  <row>
> +	    <entry></entry>
>  	    <entry>__u8</entry>
>              <entry><structfield>data</structfield>[64]</entry>
>  	    <entry>Event data. Defined by the event type. The union
> @@ -220,6 +226,23 @@
>        </tgroup>
>      </table>
> 
> +    <table frame="none" pgwide="1" id="v4l2-event-frame-sync">
> +      <title>struct <structname>v4l2_event_frame_sync</structname></title>
> +      <tgroup cols="3">
> +	&cs-str;
> +	<tbody valign="top">
> +	  <row>
> +	    <entry>__u32</entry>
> +	    <entry><structfield>buffer_sequence</structfield></entry>
> +	    <entry>
> +	      The sequence number of the buffer to be handled next or
> +	      currently handled by the driver.

What happens if a particular piece of hardware can capture two (or more) 
simultaneous streams from the same video source (an unscaled compressed stream 
and a scaled down uncompressed stream for instance) ? Applications don't need 
to start both streams at the same time, what buffer sequence number should be 
reported in that case ?

> +	    </entry>
> +	  </row>
> +	</tbody>
> +      </tgroup>
> +    </table>
> +
>      <table pgwide="1" frame="none" id="changes-flags">
>        <title>Changes</title>
>        <tgroup cols="3">
> diff --git a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
> b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml index
> 275be96..812b63c 100644
> --- a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
> +++ b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
> @@ -139,6 +139,24 @@
>  	    </entry>
>  	  </row>
>  	  <row>
> +	    <entry><constant>V4L2_EVENT_FRAME_SYNC</constant></entry>
> +	    <entry>4</entry>
> +	    <entry>
> +	      <para>Triggered immediately when the reception of a
> +	      frame has begun. This event has a
> +	      &v4l2-event-frame-sync; associated with it.</para>
> +
> +	      <para>A driver will only generate this event when the
> +	      hardware can generate it. This might not be the case
> +	      e.g. when the hardware has no DMA buffer to write the
> +	      image data to. In such cases the
> +	      <structfield>buffer_sequence</structfield> field in
> +	      &v4l2-event-frame-sync; will not be incremented either.
> +	      This causes two consecutive buffer sequence numbers to
> +	      have n times frame interval in between them.</para>

I don't think that's correct. Don't many drivers still increment the sequence 
number in that case, to make it possible for applications to detect frame loss 
?

> +	    </entry>
> +	  </row>
> +	  <row>
>  	    <entry><constant>V4L2_EVENT_PRIVATE_START</constant></entry>
>  	    <entry>0x08000000</entry>
>  	    <entry>Base event number for driver-private events.</entry>
> diff --git a/include/linux/videodev2.h b/include/linux/videodev2.h
> index fca24cc..056a49e 100644
> --- a/include/linux/videodev2.h
> +++ b/include/linux/videodev2.h
> @@ -2006,6 +2006,7 @@ struct v4l2_streamparm {
>  #define V4L2_EVENT_VSYNC			1
>  #define V4L2_EVENT_EOS				2
>  #define V4L2_EVENT_CTRL				3
> +#define V4L2_EVENT_FRAME_SYNC			4
>  #define V4L2_EVENT_PRIVATE_START		0x08000000
> 
>  /* Payload for V4L2_EVENT_VSYNC */
> @@ -2032,12 +2033,17 @@ struct v4l2_event_ctrl {
>  	__s32 default_value;
>  };
> 
> +struct v4l2_event_frame_sync {
> +	__u32 buffer_sequence;
> +};
> +
>  struct v4l2_event {
>  	__u32				type;
>  	union {
> -		struct v4l2_event_vsync vsync;
> -		struct v4l2_event_ctrl	ctrl;
> -		__u8			data[64];
> +		struct v4l2_event_vsync		vsync;
> +		struct v4l2_event_ctrl		ctrl;
> +		struct v4l2_event_frame_sync	frame_sync;
> +		__u8				data[64];
>  	} u;
>  	__u32				pending;
>  	__u32				sequence;

-- 
Regards,

Laurent Pinchart

Re: [PATCH 2/3] v4l: events: Define frame start event

[Sakari Ailus]

On Thu, Jul 28, 2011 at 01:52:21PM +0200, Laurent Pinchart wrote:
> Hi Sakari,

Hi Laurent,

Thanks for the comments!

> On Tuesday 26 July 2011 20:49:43 Sakari Ailus wrote:
> > Define a frame start event to tell user space when the reception of a frame
> > starts.
> 
> You might want to rename 'frame start' to 'frame sync' in the subject and 
> commit message as well.

Good point. I forgot to change those. Thanks.

> > Signed-off-by: Sakari Ailus <sakari.ailus@iki.fi>
> > ---
> >  Documentation/DocBook/media/v4l/vidioc-dqevent.xml |   23
> > ++++++++++++++++++++ .../DocBook/media/v4l/vidioc-subscribe-event.xml   | 
> >  18 +++++++++++++++ include/linux/videodev2.h                          |  
> > 12 +++++++-- 3 files changed, 50 insertions(+), 3 deletions(-)
> > 
> > diff --git a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
> > b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml index
> > 5200b68..1d03313 100644
> > --- a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
> > +++ b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
> > @@ -88,6 +88,12 @@
> >  	  </row>
> >  	  <row>
> >  	    <entry></entry>
> > +	    <entry>&v4l2-event-frame-sync;</entry>
> > +            <entry><structfield>frame</structfield></entry>
> > +	    <entry>Event data for event V4L2_EVENT_FRAME_SYNC.</entry>
> > +	  </row>
> > +	  <row>
> > +	    <entry></entry>
> >  	    <entry>__u8</entry>
> >              <entry><structfield>data</structfield>[64]</entry>
> >  	    <entry>Event data. Defined by the event type. The union
> > @@ -220,6 +226,23 @@
> >        </tgroup>
> >      </table>
> > 
> > +    <table frame="none" pgwide="1" id="v4l2-event-frame-sync">
> > +      <title>struct <structname>v4l2_event_frame_sync</structname></title>
> > +      <tgroup cols="3">
> > +	&cs-str;
> > +	<tbody valign="top">
> > +	  <row>
> > +	    <entry>__u32</entry>
> > +	    <entry><structfield>buffer_sequence</structfield></entry>
> > +	    <entry>
> > +	      The sequence number of the buffer to be handled next or
> > +	      currently handled by the driver.
> 
> What happens if a particular piece of hardware can capture two (or more) 
> simultaneous streams from the same video source (an unscaled compressed stream 
> and a scaled down uncompressed stream for instance) ? Applications don't need 
> to start both streams at the same time, what buffer sequence number should be 
> reported in that case ?

I think that if the video data comes from the same source, the sequence
numbers should definitely be in sync. This would mean that for the second
stream the first sequence number wouldn't be zero.

> > +	    </entry>
> > +	  </row>
> > +	</tbody>
> > +      </tgroup>
> > +    </table>
> > +
> >      <table pgwide="1" frame="none" id="changes-flags">
> >        <title>Changes</title>
> >        <tgroup cols="3">
> > diff --git a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
> > b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml index
> > 275be96..812b63c 100644
> > --- a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
> > +++ b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
> > @@ -139,6 +139,24 @@
> >  	    </entry>
> >  	  </row>
> >  	  <row>
> > +	    <entry><constant>V4L2_EVENT_FRAME_SYNC</constant></entry>
> > +	    <entry>4</entry>
> > +	    <entry>
> > +	      <para>Triggered immediately when the reception of a
> > +	      frame has begun. This event has a
> > +	      &v4l2-event-frame-sync; associated with it.</para>
> > +
> > +	      <para>A driver will only generate this event when the
> > +	      hardware can generate it. This might not be the case
> > +	      e.g. when the hardware has no DMA buffer to write the
> > +	      image data to. In such cases the
> > +	      <structfield>buffer_sequence</structfield> field in
> > +	      &v4l2-event-frame-sync; will not be incremented either.
> > +	      This causes two consecutive buffer sequence numbers to
> > +	      have n times frame interval in between them.</para>
> 
> I don't think that's correct. Don't many drivers still increment the sequence 
> number in that case, to make it possible for applications to detect frame loss 
> ?

I think I understood once that the OMAP 3 ISP driver didn't do this in all
cases but I later learned that this isn't the case. I still would be
actually a bit surprised if there was not hardware that could not do this.

Do you think the text is relevant in this context, or should it be removed?

> > +	    </entry>
> > +	  </row>
> > +	  <row>
> >  	    <entry><constant>V4L2_EVENT_PRIVATE_START</constant></entry>
> >  	    <entry>0x08000000</entry>
> >  	    <entry>Base event number for driver-private events.</entry>
> > diff --git a/include/linux/videodev2.h b/include/linux/videodev2.h
> > index fca24cc..056a49e 100644
> > --- a/include/linux/videodev2.h
> > +++ b/include/linux/videodev2.h
> > @@ -2006,6 +2006,7 @@ struct v4l2_streamparm {
> >  #define V4L2_EVENT_VSYNC			1
> >  #define V4L2_EVENT_EOS				2
> >  #define V4L2_EVENT_CTRL				3
> > +#define V4L2_EVENT_FRAME_SYNC			4
> >  #define V4L2_EVENT_PRIVATE_START		0x08000000
> > 
> >  /* Payload for V4L2_EVENT_VSYNC */
> > @@ -2032,12 +2033,17 @@ struct v4l2_event_ctrl {
> >  	__s32 default_value;
> >  };
> > 
> > +struct v4l2_event_frame_sync {
> > +	__u32 buffer_sequence;
> > +};
> > +
> >  struct v4l2_event {
> >  	__u32				type;
> >  	union {
> > -		struct v4l2_event_vsync vsync;
> > -		struct v4l2_event_ctrl	ctrl;
> > -		__u8			data[64];
> > +		struct v4l2_event_vsync		vsync;
> > +		struct v4l2_event_ctrl		ctrl;
> > +		struct v4l2_event_frame_sync	frame_sync;
> > +		__u8				data[64];
> >  	} u;
> >  	__u32				pending;
> >  	__u32				sequence;
> 
> -- 
> Regards,
> 
> Laurent Pinchart

-- 
Sakari Ailus
sakari.ailus@iki.fi

Re: [PATCH 2/3] v4l: events: Define frame start event

[Laurent Pinchart]

Hi Sakari,

On Thursday 28 July 2011 22:28:57 Sakari Ailus wrote:
> On Thu, Jul 28, 2011 at 01:52:21PM +0200, Laurent Pinchart wrote:
> > On Tuesday 26 July 2011 20:49:43 Sakari Ailus wrote:

[snip]

> > > +    <table frame="none" pgwide="1" id="v4l2-event-frame-sync">
> > > +      <title>struct
> > > <structname>v4l2_event_frame_sync</structname></title> +      <tgroup
> > > cols="3">
> > > +	&cs-str;
> > > +	<tbody valign="top">
> > > +	  <row>
> > > +	    <entry>__u32</entry>
> > > +	    <entry><structfield>buffer_sequence</structfield></entry>
> > > +	    <entry>
> > > +	      The sequence number of the buffer to be handled next or
> > > +	      currently handled by the driver.
> > 
> > What happens if a particular piece of hardware can capture two (or more)
> > simultaneous streams from the same video source (an unscaled compressed
> > stream and a scaled down uncompressed stream for instance) ?
> > Applications don't need to start both streams at the same time, what
> > buffer sequence number should be reported in that case ?
> 
> I think that if the video data comes from the same source, the sequence
> numbers should definitely be in sync. This would mean that for the second
> stream the first sequence number wouldn't be zero.

Then we should document this somewhere. Here is probably not the best place to 
document that, but the buffer_sequence documentation should still refer to the 
explanation.

I also find the wording a bit unclear. The "buffer to be handled next" could 
mean the buffer that will be given to an application at the next DQBUF call. 
Maybe we should refer to frame sequence numbers instead of buffer sequence 
numbers.

> > > +	    </entry>
> > > +	  </row>
> > > +	</tbody>
> > > +      </tgroup>
> > > +    </table>
> > > +
> > > 
> > >      <table pgwide="1" frame="none" id="changes-flags">
> > >      
> > >        <title>Changes</title>
> > >        <tgroup cols="3">
> > > 
> > > diff --git a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
> > > b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml index
> > > 275be96..812b63c 100644
> > > --- a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
> > > +++ b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
> > > @@ -139,6 +139,24 @@
> > > 
> > >  	    </entry>
> > >  	  
> > >  	  </row>
> > >  	  <row>
> > > 
> > > +	    <entry><constant>V4L2_EVENT_FRAME_SYNC</constant></entry>
> > > +	    <entry>4</entry>
> > > +	    <entry>
> > > +	      <para>Triggered immediately when the reception of a
> > > +	      frame has begun. This event has a
> > > +	      &v4l2-event-frame-sync; associated with it.</para>
> > > +
> > > +	      <para>A driver will only generate this event when the
> > > +	      hardware can generate it. This might not be the case
> > > +	      e.g. when the hardware has no DMA buffer to write the
> > > +	      image data to. In such cases the
> > > +	      <structfield>buffer_sequence</structfield> field in
> > > +	      &v4l2-event-frame-sync; will not be incremented either.
> > > +	      This causes two consecutive buffer sequence numbers to
> > > +	      have n times frame interval in between them.</para>
> > 
> > I don't think that's correct. Don't many drivers still increment the
> > sequence number in that case, to make it possible for applications to
> > detect frame loss ?
> 
> I think I understood once that the OMAP 3 ISP driver didn't do this in all
> cases but I later learned that this isn't the case. I still would be
> actually a bit surprised if there was not hardware that could not do this.
> 
> Do you think the text is relevant in this context, or should it be removed?

I think you should just mention that the event *might* not be generated if the 
hardware needs to be stopped in case of buffer underrun for instance.

-- 
Regards,

Laurent Pinchart

Re: [PATCH 2/3] v4l: events: Define frame start event

[Sakari Ailus]

On Thu, Jul 28, 2011 at 10:36:57PM +0200, Laurent Pinchart wrote:
> Hi Sakari,

Hi, Laurent!

> On Thursday 28 July 2011 22:28:57 Sakari Ailus wrote:
> > On Thu, Jul 28, 2011 at 01:52:21PM +0200, Laurent Pinchart wrote:
> > > On Tuesday 26 July 2011 20:49:43 Sakari Ailus wrote:
> 
> [snip]
> 
> > > > +    <table frame="none" pgwide="1" id="v4l2-event-frame-sync">
> > > > +      <title>struct
> > > > <structname>v4l2_event_frame_sync</structname></title> +      <tgroup
> > > > cols="3">
> > > > +	&cs-str;
> > > > +	<tbody valign="top">
> > > > +	  <row>
> > > > +	    <entry>__u32</entry>
> > > > +	    <entry><structfield>buffer_sequence</structfield></entry>
> > > > +	    <entry>
> > > > +	      The sequence number of the buffer to be handled next or
> > > > +	      currently handled by the driver.
> > > 
> > > What happens if a particular piece of hardware can capture two (or more)
> > > simultaneous streams from the same video source (an unscaled compressed
> > > stream and a scaled down uncompressed stream for instance) ?
> > > Applications don't need to start both streams at the same time, what
> > > buffer sequence number should be reported in that case ?
> > 
> > I think that if the video data comes from the same source, the sequence
> > numbers should definitely be in sync. This would mean that for the second
> > stream the first sequence number wouldn't be zero.
> 
> Then we should document this somewhere. Here is probably not the best place to 
> document that, but the buffer_sequence documentation should still refer to the 
> explanation.
> 
> I also find the wording a bit unclear. The "buffer to be handled next" could 
> mean the buffer that will be given to an application at the next DQBUF call. 
> Maybe we should refer to frame sequence numbers instead of buffer sequence 
> numbers.

What's the difference? I would consider the two the same.

..."buffer to be written next to by the hardware"?

> > > > +	    </entry>
> > > > +	  </row>
> > > > +	</tbody>
> > > > +      </tgroup>
> > > > +    </table>
> > > > +
> > > > 
> > > >      <table pgwide="1" frame="none" id="changes-flags">
> > > >      
> > > >        <title>Changes</title>
> > > >        <tgroup cols="3">
> > > > 
> > > > diff --git a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
> > > > b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml index
> > > > 275be96..812b63c 100644
> > > > --- a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
> > > > +++ b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
> > > > @@ -139,6 +139,24 @@
> > > > 
> > > >  	    </entry>
> > > >  	  
> > > >  	  </row>
> > > >  	  <row>
> > > > 
> > > > +	    <entry><constant>V4L2_EVENT_FRAME_SYNC</constant></entry>
> > > > +	    <entry>4</entry>
> > > > +	    <entry>
> > > > +	      <para>Triggered immediately when the reception of a
> > > > +	      frame has begun. This event has a
> > > > +	      &v4l2-event-frame-sync; associated with it.</para>
> > > > +
> > > > +	      <para>A driver will only generate this event when the
> > > > +	      hardware can generate it. This might not be the case
> > > > +	      e.g. when the hardware has no DMA buffer to write the
> > > > +	      image data to. In such cases the
> > > > +	      <structfield>buffer_sequence</structfield> field in
> > > > +	      &v4l2-event-frame-sync; will not be incremented either.
> > > > +	      This causes two consecutive buffer sequence numbers to
> > > > +	      have n times frame interval in between them.</para>
> > > 
> > > I don't think that's correct. Don't many drivers still increment the
> > > sequence number in that case, to make it possible for applications to
> > > detect frame loss ?
> > 
> > I think I understood once that the OMAP 3 ISP driver didn't do this in all
> > cases but I later learned that this isn't the case. I still would be
> > actually a bit surprised if there was not hardware that could not do this.
> > 
> > Do you think the text is relevant in this context, or should it be removed?
> 
> I think you should just mention that the event *might* not be generated if the 
> hardware needs to be stopped in case of buffer underrun for instance.

Ack.

-- 
Sakari Ailus
sakari.ailus@iki.fi

Re: [PATCH 2/3] v4l: events: Define frame start event

[Laurent Pinchart]

Hi Sakari,

On Friday 29 July 2011 09:44:46 Sakari Ailus wrote:
> On Thu, Jul 28, 2011 at 10:36:57PM +0200, Laurent Pinchart wrote:
> > On Thursday 28 July 2011 22:28:57 Sakari Ailus wrote:
> > > On Thu, Jul 28, 2011 at 01:52:21PM +0200, Laurent Pinchart wrote:
> > > > On Tuesday 26 July 2011 20:49:43 Sakari Ailus wrote:
> > [snip]
> > 
> > > > > +    <table frame="none" pgwide="1" id="v4l2-event-frame-sync">
> > > > > +      <title>struct
> > > > > <structname>v4l2_event_frame_sync</structname></title> +     
> > > > > <tgroup cols="3">
> > > > > +	&cs-str;
> > > > > +	<tbody valign="top">
> > > > > +	  <row>
> > > > > +	    <entry>__u32</entry>
> > > > > +	    <entry><structfield>buffer_sequence</structfield></entry>
> > > > > +	    <entry>
> > > > > +	      The sequence number of the buffer to be handled next or
> > > > > +	      currently handled by the driver.
> > > > 
> > > > What happens if a particular piece of hardware can capture two (or
> > > > more) simultaneous streams from the same video source (an unscaled
> > > > compressed stream and a scaled down uncompressed stream for
> > > > instance) ? Applications don't need to start both streams at the
> > > > same time, what buffer sequence number should be reported in that
> > > > case ?
> > > 
> > > I think that if the video data comes from the same source, the sequence
> > > numbers should definitely be in sync. This would mean that for the
> > > second stream the first sequence number wouldn't be zero.
> > 
> > Then we should document this somewhere. Here is probably not the best
> > place to document that, but the buffer_sequence documentation should
> > still refer to the explanation.
> > 
> > I also find the wording a bit unclear. The "buffer to be handled next"
> > could mean the buffer that will be given to an application at the next
> > DQBUF call. Maybe we should refer to frame sequence numbers instead of
> > buffer sequence numbers.
> 
> What's the difference? I would consider the two the same.

If we have multiple simultaneous streams from the same source, I think it 
would make sense to start thinking about frame sequence numbers instead of 
buffer sequence numbers. The buffer sequence number would then just store the 
frame sequence number of the frame stored in the buffer. This would (in my 
opinion) simplify the spec's understanding.

> ..."buffer to be written next to by the hardware"?

What about ..."buffer that will store the image" ?

-- 
Regards,

Laurent Pinchart

Re: [PATCH 2/3] v4l: events: Define frame start event

[Sakari Ailus]

On Fri, Jul 29, 2011 at 11:38:16AM +0200, Laurent Pinchart wrote:
> Hi Sakari,
> 
> On Friday 29 July 2011 09:44:46 Sakari Ailus wrote:
> > On Thu, Jul 28, 2011 at 10:36:57PM +0200, Laurent Pinchart wrote:
> > > On Thursday 28 July 2011 22:28:57 Sakari Ailus wrote:
> > > > On Thu, Jul 28, 2011 at 01:52:21PM +0200, Laurent Pinchart wrote:
> > > > > On Tuesday 26 July 2011 20:49:43 Sakari Ailus wrote:
> > > [snip]
> > > 
> > > > > > +    <table frame="none" pgwide="1" id="v4l2-event-frame-sync">
> > > > > > +      <title>struct
> > > > > > <structname>v4l2_event_frame_sync</structname></title> +     
> > > > > > <tgroup cols="3">
> > > > > > +	&cs-str;
> > > > > > +	<tbody valign="top">
> > > > > > +	  <row>
> > > > > > +	    <entry>__u32</entry>
> > > > > > +	    <entry><structfield>buffer_sequence</structfield></entry>
> > > > > > +	    <entry>
> > > > > > +	      The sequence number of the buffer to be handled next or
> > > > > > +	      currently handled by the driver.
> > > > > 
> > > > > What happens if a particular piece of hardware can capture two (or
> > > > > more) simultaneous streams from the same video source (an unscaled
> > > > > compressed stream and a scaled down uncompressed stream for
> > > > > instance) ? Applications don't need to start both streams at the
> > > > > same time, what buffer sequence number should be reported in that
> > > > > case ?
> > > > 
> > > > I think that if the video data comes from the same source, the sequence
> > > > numbers should definitely be in sync. This would mean that for the
> > > > second stream the first sequence number wouldn't be zero.
> > > 
> > > Then we should document this somewhere. Here is probably not the best
> > > place to document that, but the buffer_sequence documentation should
> > > still refer to the explanation.
> > > 
> > > I also find the wording a bit unclear. The "buffer to be handled next"
> > > could mean the buffer that will be given to an application at the next
> > > DQBUF call. Maybe we should refer to frame sequence numbers instead of
> > > buffer sequence numbers.
> > 
> > What's the difference? I would consider the two the same.
> 
> If we have multiple simultaneous streams from the same source, I think it 
> would make sense to start thinking about frame sequence numbers instead of 
> buffer sequence numbers. The buffer sequence number would then just store the 
> frame sequence number of the frame stored in the buffer. This would (in my 
> opinion) simplify the spec's understanding.

Another good point from you, I agree with this.

> > ..."buffer to be written next to by the hardware"?
> 
> What about ..."buffer that will store the image" ?

But which image? And if there is no buffer, no image is written to it
either.

"frame to be processed or being processed by the hardware"?

-- 
Sakari Ailus
sakari.ailus@iki.fi

Re: [PATCH 2/3] v4l: events: Define frame start event

[Laurent Pinchart]

On Friday 29 July 2011 11:54:03 Sakari Ailus wrote:
> On Fri, Jul 29, 2011 at 11:38:16AM +0200, Laurent Pinchart wrote:
> > On Friday 29 July 2011 09:44:46 Sakari Ailus wrote:
> > > On Thu, Jul 28, 2011 at 10:36:57PM +0200, Laurent Pinchart wrote:
> > > > On Thursday 28 July 2011 22:28:57 Sakari Ailus wrote:
> > > > > On Thu, Jul 28, 2011 at 01:52:21PM +0200, Laurent Pinchart wrote:
> > > > > > On Tuesday 26 July 2011 20:49:43 Sakari Ailus wrote:
> > > > [snip]
> > > > 
> > > > > > > +    <table frame="none" pgwide="1" id="v4l2-event-frame-sync">
> > > > > > > +      <title>struct
> > > > > > > <structname>v4l2_event_frame_sync</structname></title> +
> > > > > > > <tgroup cols="3">
> > > > > > > +	&cs-str;
> > > > > > > +	<tbody valign="top">
> > > > > > > +	  <row>
> > > > > > > +	    <entry>__u32</entry>
> > > > > > > +	    <entry><structfield>buffer_sequence</structfield></entry>
> > > > > > > +	    <entry>
> > > > > > > +	      The sequence number of the buffer to be handled next or
> > > > > > > +	      currently handled by the driver.
> > > > > > 
> > > > > > What happens if a particular piece of hardware can capture two
> > > > > > (or more) simultaneous streams from the same video source (an
> > > > > > unscaled compressed stream and a scaled down uncompressed stream
> > > > > > for instance) ? Applications don't need to start both streams at
> > > > > > the same time, what buffer sequence number should be reported in
> > > > > > that case ?
> > > > > 
> > > > > I think that if the video data comes from the same source, the
> > > > > sequence numbers should definitely be in sync. This would mean
> > > > > that for the second stream the first sequence number wouldn't be
> > > > > zero.
> > > > 
> > > > Then we should document this somewhere. Here is probably not the best
> > > > place to document that, but the buffer_sequence documentation should
> > > > still refer to the explanation.
> > > > 
> > > > I also find the wording a bit unclear. The "buffer to be handled
> > > > next" could mean the buffer that will be given to an application at
> > > > the next DQBUF call. Maybe we should refer to frame sequence numbers
> > > > instead of buffer sequence numbers.
> > > 
> > > What's the difference? I would consider the two the same.
> > 
> > If we have multiple simultaneous streams from the same source, I think it
> > would make sense to start thinking about frame sequence numbers instead
> > of buffer sequence numbers. The buffer sequence number would then just
> > store the frame sequence number of the frame stored in the buffer. This
> > would (in my opinion) simplify the spec's understanding.
> 
> Another good point from you, I agree with this.
> 
> > > ..."buffer to be written next to by the hardware"?
> > 
> > What about ..."buffer that will store the image" ?
> 
> But which image? And if there is no buffer, no image is written to it
> either.
> 
> "frame to be processed or being processed by the hardware"?

"frame being received" ? This is a *frame* sync event, it should contain the 
sequence number of the frame that triggered it.

-- 
Regards,

Laurent Pinchart

Re: [PATCH 2/3] v4l: events: Define frame start event

[Sakari Ailus]

On Fri, Jul 29, 2011 at 11:57:17AM +0200, Laurent Pinchart wrote:
> On Friday 29 July 2011 11:54:03 Sakari Ailus wrote:
> > On Fri, Jul 29, 2011 at 11:38:16AM +0200, Laurent Pinchart wrote:
> > > On Friday 29 July 2011 09:44:46 Sakari Ailus wrote:
> > > > On Thu, Jul 28, 2011 at 10:36:57PM +0200, Laurent Pinchart wrote:
> > > > > On Thursday 28 July 2011 22:28:57 Sakari Ailus wrote:
> > > > > > On Thu, Jul 28, 2011 at 01:52:21PM +0200, Laurent Pinchart wrote:
> > > > > > > On Tuesday 26 July 2011 20:49:43 Sakari Ailus wrote:
> > > > > [snip]
> > > > > 
> > > > > > > > +    <table frame="none" pgwide="1" id="v4l2-event-frame-sync">
> > > > > > > > +      <title>struct
> > > > > > > > <structname>v4l2_event_frame_sync</structname></title> +
> > > > > > > > <tgroup cols="3">
> > > > > > > > +	&cs-str;
> > > > > > > > +	<tbody valign="top">
> > > > > > > > +	  <row>
> > > > > > > > +	    <entry>__u32</entry>
> > > > > > > > +	    <entry><structfield>buffer_sequence</structfield></entry>
> > > > > > > > +	    <entry>
> > > > > > > > +	      The sequence number of the buffer to be handled next or
> > > > > > > > +	      currently handled by the driver.
> > > > > > > 
> > > > > > > What happens if a particular piece of hardware can capture two
> > > > > > > (or more) simultaneous streams from the same video source (an
> > > > > > > unscaled compressed stream and a scaled down uncompressed stream
> > > > > > > for instance) ? Applications don't need to start both streams at
> > > > > > > the same time, what buffer sequence number should be reported in
> > > > > > > that case ?
> > > > > > 
> > > > > > I think that if the video data comes from the same source, the
> > > > > > sequence numbers should definitely be in sync. This would mean
> > > > > > that for the second stream the first sequence number wouldn't be
> > > > > > zero.
> > > > > 
> > > > > Then we should document this somewhere. Here is probably not the best
> > > > > place to document that, but the buffer_sequence documentation should
> > > > > still refer to the explanation.
> > > > > 
> > > > > I also find the wording a bit unclear. The "buffer to be handled
> > > > > next" could mean the buffer that will be given to an application at
> > > > > the next DQBUF call. Maybe we should refer to frame sequence numbers
> > > > > instead of buffer sequence numbers.
> > > > 
> > > > What's the difference? I would consider the two the same.
> > > 
> > > If we have multiple simultaneous streams from the same source, I think it
> > > would make sense to start thinking about frame sequence numbers instead
> > > of buffer sequence numbers. The buffer sequence number would then just
> > > store the frame sequence number of the frame stored in the buffer. This
> > > would (in my opinion) simplify the spec's understanding.
> > 
> > Another good point from you, I agree with this.
> > 
> > > > ..."buffer to be written next to by the hardware"?
> > > 
> > > What about ..."buffer that will store the image" ?
> > 
> > But which image? And if there is no buffer, no image is written to it
> > either.
> > 
> > "frame to be processed or being processed by the hardware"?
> 
> "frame being received" ? This is a *frame* sync event, it should contain the 
> sequence number of the frame that triggered it.

I'm fine with "frame being received".

-- 
Sakari Ailus
sakari.ailus@iki.fi