Skip to contentSkip to conversation

media: events: add new flags

RFC PATCH In review Hans Verkuil 1 participant 7 messages Oct 10, 2025 Media (V4L/DVB)

lore
Share & tools
lore
#0 lore raw

cover media: events: add new flags

Note: this patch series sits on top of this patch:

https://patchwork.linuxtv.org/project/linux-media/patch/[email protected]/

However, it can be rebased if needed without that patch.

This series adds a flags field for v4l2_event and adds two flags:
one to indicate that the event is the initial event as requested by V4L2_EVENT_SUB_FL_SEND_INITIAL, and one flag to indicate that the event is a merger multiple events, meaning that some history is lost.

This information is particularly useful when debugging event issues.

Regards,

Hans

Hans Verkuil (5):
media: videodev2.h: add flags field to v4l2_event
media: videodev2.h: add new v4l2_event flags
media: v4l2-event: add support for V4L2_EVENT_FL_MULTIPLE
media: v4l2-ctrls: set the new V4L2_EVENT_FL_INITIAL flag
Documentation: media: document new event flags

 .../media/v4l/vidioc-dqevent.rst              | 29 +++++++++++++++++--
 .../media/v4l/vidioc-subscribe-event.rst      |  6 ++--
 .../media/videodev2.h.rst.exceptions          |  7 +++--
 drivers/media/v4l2-core/v4l2-compat-ioctl32.c |  8 +++--
 drivers/media/v4l2-core/v4l2-ctrls-core.c     |  1 +
 drivers/media/v4l2-core/v4l2-event.c          |  3 ++
 drivers/media/v4l2-core/v4l2-ioctl.c          |  4 +--
 include/uapi/linux/videodev2.h                |  6 +++-
 8 files changed, 52 insertions(+), 12 deletions(-)
Signature · 1 line
2.51.0
#1 lore raw

RFC PATCH 1/5 media: videodev2.h: add flags field to v4l2_event

Add a new flags field to struct v4l2_event.

---
 drivers/media/v4l2-core/v4l2-compat-ioctl32.c | 8 ++++++--
 drivers/media/v4l2-core/v4l2-ioctl.c          | 4 ++--
 include/uapi/linux/videodev2.h                | 3 ++-
 3 files changed, 10 insertions(+), 5 deletions(-)
drivers/media/v4l2-core/v4l2-compat-ioctl32.c +6 -2
index 2c88e1175a10..160ce928bc91 100644
@@ -754,7 +754,8 @@ struct v4l2_event32 {
 		compat_s64		tv_nsec;
 	} timestamp;
 	__u32				id;
-	__u32				reserved[8];
+	__u32				flags;
+	__u32				reserved[7];
 };
 
 static int put_v4l2_event32(struct v4l2_event *p64,
@@ -767,6 +768,7 @@ static int put_v4l2_event32(struct v4l2_event *p64,
 	    put_user(p64->timestamp.tv_sec, &p32->timestamp.tv_sec) ||
 	    put_user(p64->timestamp.tv_nsec, &p32->timestamp.tv_nsec) ||
 	    put_user(p64->id, &p32->id) ||
+	    put_user(p64->flags, &p32->flags) ||
 	    copy_to_user(p32->reserved, p64->reserved, sizeof(p32->reserved)))
 		return -EFAULT;
 	return 0;
@@ -785,7 +787,8 @@ struct v4l2_event32_time32 {
 	__u32				sequence;
 	struct old_timespec32		timestamp;
 	__u32				id;
-	__u32				reserved[8];
+	__u32				flags;
+	__u32				reserved[7];
 };
 
 static int put_v4l2_event32_time32(struct v4l2_event *p64,
@@ -798,6 +801,7 @@ static int put_v4l2_event32_time32(struct v4l2_event *p64,
 	    put_user(p64->timestamp.tv_sec, &p32->timestamp.tv_sec) ||
 	    put_user(p64->timestamp.tv_nsec, &p32->timestamp.tv_nsec) ||
 	    put_user(p64->id, &p32->id) ||
+	    put_user(p64->flags, &p32->flags) ||
 	    copy_to_user(p32->reserved, p64->reserved, sizeof(p32->reserved)))
 		return -EFAULT;
 	return 0;
drivers/media/v4l2-core/v4l2-ioctl.c +2 -2
index 01cf52c3ea33..b421336605a3 100644
@@ -791,8 +791,8 @@ static void v4l_print_event(const void *arg, bool write_only)
 	const struct v4l2_event *p = arg;
 	const struct v4l2_event_ctrl *c;
 
-	pr_cont("type=0x%x, pending=%u, sequence=%u, id=%u, timestamp=%llu.%9.9llu\n",
-			p->type, p->pending, p->sequence, p->id,
+	pr_cont("type=0x%x, pending=%u, sequence=%u, id=%u, flags=%08x, timestamp=%llu.%9.9llu\n",
+			p->type, p->pending, p->sequence, p->id, p->flags,
 			p->timestamp.tv_sec, p->timestamp.tv_nsec);
 	switch (p->type) {
 	case V4L2_EVENT_VSYNC:
include/uapi/linux/videodev2.h +2 -1
index becd08fdbddb..83ee088df24a 100644
@@ -2618,7 +2618,8 @@ struct v4l2_event {
 	struct timespec			timestamp;
 #endif
 	__u32				id;
-	__u32				reserved[8];
+	__u32				flags;
+	__u32				reserved[7];
 };
 
 #define V4L2_EVENT_SUB_FL_SEND_INITIAL		(1 << 0)
Signature · 1 line
2.51.0
#2 lore raw

RFC PATCH 2/5 media: videodev2.h: add new v4l2_event flags

In reply to Hans Verkuil

Add two new flags:

- V4L2_EVENT_FL_INITIAL: set for the initial control events if V4L2_EVENT_SUB_FL_SEND_INITIAL was set when subscribing.
- V4L2_EVENT_FL_MULTIPLE: set if the event actually is a merger of multiple events due to space constraints in the event queue.

---
 include/uapi/linux/videodev2.h | 3 +++
 1 file changed, 3 insertions(+)
include/uapi/linux/videodev2.h +3 -0
index 83ee088df24a..2d7f1ab7ca33 100644
@@ -2600,6 +2600,9 @@ struct v4l2_event_motion_det {
 	__u32 region_mask;
 };
 
+#define V4L2_EVENT_FL_INITIAL			(1 << 0)
+#define V4L2_EVENT_FL_MULTIPLE			(1 << 1)
+
 struct v4l2_event {
 	__u32				type;
 	union {
Signature · 1 line
2.51.0
#3 lore raw

RFC PATCH 3/5 media: v4l2-event: add support for V4L2_EVENT_FL_MULTIPLE

In reply to Hans Verkuil

Set the V4L2_EVENT_FL_MULTIPLE flag if two events are squashed together.

Also use the new flags field of struct v4l2_event so it is copied to the events in the event list.

---
 drivers/media/v4l2-core/v4l2-event.c | 3 +++
 1 file changed, 3 insertions(+)
drivers/media/v4l2-core/v4l2-event.c +3 -0
index 1bc1e2f8c3d7..2c0d1e66584c 100644
@@ -139,6 +139,7 @@ static void __v4l2_event_queue_fh(struct v4l2_fh *fh,
 			} else {
 				oldest->event.u = ev->u;
 			}
+			oldest->event.flags |= ev->flags | V4L2_EVENT_FL_MULTIPLE;
 			wake_up_all(&fh->wait);
 			return;
 		}
@@ -154,6 +155,7 @@ static void __v4l2_event_queue_fh(struct v4l2_fh *fh,
 		 */
 		second_oldest->event.sequence = oldest->event.sequence;
 		second_oldest->ts = oldest->ts;
+		second_oldest->flags |= oldest->flags | V4L2_EVENT_FL_MULTIPLE;
 		list_del(&second_oldest->list);
 		list_replace_init(&oldest->list, &second_oldest->list);
 		sev->first = sev_pos(sev, 1);
@@ -171,6 +173,7 @@ static void __v4l2_event_queue_fh(struct v4l2_fh *fh,
 	kev->event.id = ev->id;
 	kev->ts = ts;
 	kev->event.sequence = fh->sequence;
+	kev->event.flags = ev->flags;
 	sev->in_use++;
 	list_add_tail(&kev->list, &fh->available);
 
Signature · 1 line
2.51.0
#5 lore raw

RFC PATCH 4/5 media: v4l2-ctrls: set the new V4L2_EVENT_FL_INITIAL flag

In reply to Hans Verkuil

If V4L2_EVENT_SUB_FL_SEND_INITIAL was set when subscribing to the control event, set V4L2_EVENT_FL_INITIAL in the flags field of the initial event that is sent out.

---
 drivers/media/v4l2-core/v4l2-ctrls-core.c | 1 +
 1 file changed, 1 insertion(+)
drivers/media/v4l2-core/v4l2-ctrls-core.c +1 -0
index 85d07ef44f62..6ff9b2f7e668 100644
@@ -47,6 +47,7 @@ void send_initial_event(struct v4l2_fh *fh, struct v4l2_ctrl *ctrl)
 	if (!(ctrl->flags & V4L2_CTRL_FLAG_WRITE_ONLY))
 		changes |= V4L2_EVENT_CTRL_CH_VALUE;
 	fill_event(&ev, ctrl, changes);
+	ev.flags |= V4L2_EVENT_FL_INITIAL;
 	v4l2_event_queue_fh(fh, &ev);
 }
 
Signature · 1 line
2.51.0
#6 lore raw

RFC PATCH 5/5 Documentation: media: document new event flags

In reply to Hans Verkuil

Document the new V4L2_EVENT_FL_INITIAL/MULTIPLE flags.

Also fix a small mistake for the type of the 'id' field: it's __u32, not u32.

---
 .../media/v4l/vidioc-dqevent.rst              | 29 +++++++++++++++++--
 .../media/v4l/vidioc-subscribe-event.rst      |  6 ++--
 .../media/videodev2.h.rst.exceptions          |  7 +++--
 3 files changed, 35 insertions(+), 7 deletions(-)
Documentation/userspace-api/media/v4l/vidioc-dqevent.rst +27 -2
index 8db103760930..e66c9fe1f84f 100644
@@ -86,13 +86,16 @@ call.
       - Event timestamp. The timestamp has been taken from the
 	``CLOCK_MONOTONIC`` clock. To access the same clock outside V4L2,
 	use :c:func:`clock_gettime`.
-    * - u32
+    * - __u32
       - ``id``
       - The ID associated with the event source. If the event does not
 	have an associated ID (this depends on the event type), then this
 	is 0.
     * - __u32
-      - ``reserved``\ [8]
+      - ``flags``
+      - Event flags, see :ref:`event-flags`.
+    * - __u32
+      - ``reserved``\ [7]
       - Reserved for future extensions. Drivers must set the array to
 	zero.
 
@@ -369,6 +372,28 @@ call.
 	loss of signal and so restarting streaming I/O is required in order for
 	the hardware to synchronize to the video signal.
 
+.. tabularcolumns:: |p{7.5cm}|p{2.0cm}|p{7.8cm}|
+
+.. _event-flags:
+
+.. flat-table:: Event Flags
+    :header-rows:  0
+    :stub-columns: 0
+    :widths:       3 1 4
+
+    * - ``V4L2_EVENT_FL_INITIAL``
+      - 0x0001
+      - When this event is subscribed and the ``V4L2_EVENT_SUB_FL_SEND_INITIAL``
+        flag is set, then an initial event will be sent with the current status
+	(if applicable to the event type), and that initial event will have
+	this flag set.
+    * - ``V4L2_EVENT_FL_MULTIPLE``
+      - 0x0002
+      - When more events of the same type arrive then the internal queue can store,
+        then the oldest two events will be merged. In that case this flag is set
+	to indicate that some history is lost. The ``sequence`` and ``timestamp``
+	fields are those of the oldest event.
+
 Return Value
 ============
 
Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst +3 -3
index a6fc3c5fe99d..952e28729eee 100644
@@ -64,7 +64,7 @@ using the :ref:`VIDIOC_DQEVENT` ioctl.
 	ID depends on the event type.
     * - __u32
       - ``flags``
-      - Event flags, see :ref:`event-flags`.
+      - Event subscription flags, see :ref:`event-sub-flags`.
     * - __u32
       - ``reserved``\ [5]
       - Reserved for future extensions. Drivers and applications must set
@@ -73,9 +73,9 @@ using the :ref:`VIDIOC_DQEVENT` ioctl.
 
 .. tabularcolumns:: |p{7.5cm}|p{2.0cm}|p{7.8cm}|
 
-.. _event-flags:
+.. _event-sub-flags:
 
-.. flat-table:: Event Flags
+.. flat-table:: Event Subscription Flags
     :header-rows:  0
     :stub-columns: 0
     :widths:       3 1 4
Documentation/userspace-api/media/videodev2.h.rst.exceptions +5 -2
index 35d3456cc812..f876ee083337 100644
@@ -529,8 +529,11 @@ replace define V4L2_EVENT_SRC_CH_RESOLUTION src-changes-flags
 
 replace define V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ :c:type:`v4l2_event_motion_det`
 
-replace define V4L2_EVENT_SUB_FL_SEND_INITIAL event-flags
-replace define V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK event-flags
+replace define V4L2_EVENT_SUB_FL_SEND_INITIAL event-sub-flags
+replace define V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK event-sub-flags
+
+replace define V4L2_EVENT_FL_INITIAL event-flags
+replace define V4L2_EVENT_FL_MULTIPLE event-flags
 
 # V4L2 debugging
 replace define V4L2_CHIP_MATCH_BRIDGE vidioc_dbg_g_register
Signature · 1 line
2.51.0
#4 lore raw

Re: [RFC PATCH 3/5] media: v4l2-event: add support for V4L2_EVENT_FL_MULTIPLE

In reply to Hans Verkuil
Quoted 24 lines · Hans Verkuil

Set the V4L2_EVENT_FL_MULTIPLE flag if two events are squashed together.

Also use the new flags field of struct v4l2_event so it is copied to the events in the event list.

---
 drivers/media/v4l2-core/v4l2-event.c | 3 +++
 1 file changed, 3 insertions(+)
drivers/media/v4l2-core/v4l2-event.c +1 -0
index 1bc1e2f8c3d7..2c0d1e66584c 100644
@@ -139,6 +139,7 @@ static void __v4l2_event_queue_fh(struct v4l2_fh *fh,
 			} else {
 				oldest->event.u = ev->u;
 			}
+			oldest->event.flags |= ev->flags | V4L2_EVENT_FL_MULTIPLE;
 			wake_up_all(&fh->wait);
 			return;
 		}

drivers/media/v4l2-core/v4l2-event.c static void __v4l2_event_queue_fh(struct v4l2_fh *fh, · line 158

Quoted 4 lines
drivers/media/v4l2-core/v4l2-event.c +1 -0
@@ -154,6 +155,7 @@ static void __v4l2_event_queue_fh(struct v4l2_fh *fh,
 		 */
 		second_oldest->event.sequence = oldest->event.sequence;
 		second_oldest->ts = oldest->ts;
+		second_oldest->flags |= oldest->flags | V4L2_EVENT_FL_MULTIPLE;

Oops, that should be:

second_oldest->event.flags |= oldest->event.flags | V4L2_EVENT_FL_MULTIPLE;

Regards,

Hans

Quoted 11 lines
drivers/media/v4l2-core/v4l2-event.c +1 -0
 		list_del(&second_oldest->list);
 		list_replace_init(&oldest->list, &second_oldest->list);
 		sev->first = sev_pos(sev, 1);
@@ -171,6 +173,7 @@ static void __v4l2_event_queue_fh(struct v4l2_fh *fh,
 	kev->event.id = ev->id;
 	kev->ts = ts;
 	kev->event.sequence = fh->sequence;
+	kev->event.flags = ev->flags;
 	sev->in_use++;
 	list_add_tail(&kev->list, &fh->available);