Video events, version 2.1

RFC Sakari Ailus 4 participants 7 messages Oct 16, 2009 – Oct 20, 2009 Media (V4L/DVB)

Share & tools

Sakari Ailus

author

2009-10-16 13:41 UTC #0 lore raw

Hi,

Here's the version 2.1 of the video events RFC. It's based on Laurent
Pinchart's original RFC and version 2 which I wrote some time ago. This time the changes are done based on discussion on the list. The old RFC is available here:

<URL:http://www.spinics.net/lists/linux-media/msg10971.html>

(Cc:d to Mike Krufky and Devin Heitmueller, too.)

Changes to version 2
--------------------

#define V4L2_EVENT_ALL

VIDIOC_G_EVENT -> VIDIOC_DQEVENT

Event enumeration is gone.

Reserved fields moved before data in v4l2_event and now there are 8 of them instead of 4.

Event (un)subscription argument is now v4l2_event_subscription.

Interface description
---------------------

Event type is either a standard event or private event. Standard events will be defined in videodev2.h. Private event types begin from V4L2_EVENT_PRIVATE. Some high order bits will be reserved for future use.

#define V4L2_EVENT_ALL 0x07ffffff
#define V4L2_EVENT_PRIVATE_START 0x08000000
#define V4L2_EVENT_RESERVED 0x10000000

VIDIOC_DQEVENT is used to get events. count is number of pending events after the current one. sequence is the event type sequence number and the data is specific to event type.

The user will get the information that there's an event through exception file descriptors by using select(2). When an event is available the poll handler sets POLLPRI which wakes up select. -EINVAL will be returned if there are no pending events.

VIDIOC_SUBSCRIBE_EVENT and VIDIOC_UNSUBSCRIBE_EVENT are used to
subscribe and unsubscribe from events. The argument is struct v4l2_event_subscription which now only contains the type field for the event type. Every event can be subscribed or unsubscribed by one ioctl by using special type V4L2_EVENT_ALL.

struct v4l2_event {
	__u32		count;
	__u32		type;
	__u32		sequence;
	struct timeval	timestamp;
	__u32		reserved[8];
	__u8		data[64];
};

struct v4l2_event_subscription {
	__u32		type;
	__u32		reserved[8];
};

#define VIDIOC_DQEVENT _IOR('V', 84, struct v4l2_event)
#define VIDIOC_SUBSCRIBE_EVENT _IOW('V', 85, struct
v4l2_event_subscription)
#define VIDIOC_UNSUBSCRIBE_EVENT _IOW('V', 86, struct
v4l2_event_subscription)

The size of the event queue is decided by the driver. Which events will be discarded on queue overflow depends on the implementation.

Questions
---------

One more question I have is that there can be situations that the application wants to know something has happened but does not want an explicit notification from that. So it gets an event from VIDIOC_DQEVENT but does not want to get woken up for that reason. I guess one flag in event subscription should do that. Perhaps that is something that should be implemented when needed, though.

Are there enough reserved fields now? How about the event type high order bits split?

What should we really call v4l2_event_subscription? A better name for the structure would be perhaps favourable.

Comments and questions are still very very welcome.

Signature · 2 lines

Sakari Ailus
[email protected]

Michael Krufky

2009-10-16 14:32 UTC #1 lore raw

Let's please just use either my @linuxtv.org or @kernellabs.com email account for this...

Thanks,

Mike

Quoted 102 lines · Sakari Ailus

Hi,
Here's the version 2.1 of the video events RFC. It's based on Laurent Pinchart's original RFC and version 2 which I wrote some time ago. This time the changes are done based on discussion on the list. The old RFC is available here:
<URL:http://www.spinics.net/lists/linux-media/msg10971.html>
(Cc:d to Mike Krufky and Devin Heitmueller, too.)
Changes to version 2
--------------------
#define V4L2_EVENT_ALL
VIDIOC_G_EVENT -> VIDIOC_DQEVENT
Event enumeration is gone.
Reserved fields moved before data in v4l2_event and now there are 8 of them instead of 4.
Event (un)subscription argument is now v4l2_event_subscription.
Interface description
---------------------
Event type is either a standard event or private event. Standard events will be defined in videodev2.h. Private event types begin from V4L2_EVENT_PRIVATE. Some high order bits will be reserved for future use.
#define V4L2_EVENT_ALL                  0x07ffffff
#define V4L2_EVENT_PRIVATE_START        0x08000000
#define V4L2_EVENT_RESERVED             0x10000000
VIDIOC_DQEVENT is used to get events. count is number of pending events after the current one. sequence is the event type sequence number and the data is specific to event type.
The user will get the information that there's an event through exception file descriptors by using select(2). When an event is available the poll handler sets POLLPRI which wakes up select. -EINVAL will be returned if there are no pending events.
VIDIOC_SUBSCRIBE_EVENT and VIDIOC_UNSUBSCRIBE_EVENT are used to subscribe and unsubscribe from events. The argument is struct v4l2_event_subscription which now only contains the type field for the event type. Every event can be subscribed or unsubscribed by one ioctl by using special type V4L2_EVENT_ALL.
struct v4l2_event {
        __u32           count;
        __u32           type;
        __u32           sequence;
        struct timeval  timestamp;
        __u32           reserved[8];
        __u8            data[64];
};
struct v4l2_event_subscription {
        __u32           type;
        __u32           reserved[8];
};
#define VIDIOC_DQEVENT _IOR('V', 84, struct v4l2_event)
#define VIDIOC_SUBSCRIBE_EVENT _IOW('V', 85, struct
v4l2_event_subscription)
#define VIDIOC_UNSUBSCRIBE_EVENT _IOW('V', 86, struct
v4l2_event_subscription)
The size of the event queue is decided by the driver. Which events will be discarded on queue overflow depends on the implementation.
Questions
---------
One more question I have is that there can be situations that the application wants to know something has happened but does not want an explicit notification from that. So it gets an event from VIDIOC_DQEVENT but does not want to get woken up for that reason. I guess one flag in event subscription should do that. Perhaps that is something that should be implemented when needed, though.
Are there enough reserved fields now? How about the event type high order bits split?
What should we really call v4l2_event_subscription? A better name for the structure would be perhaps favourable.
Comments and questions are still very very welcome.
Signature · 2 lines
Sakari Ailus
[email protected]

Hans Verkuil

2009-10-16 20:43 UTC #2 lore raw

In reply to Sakari Ailus

Quoted 26 lines · On Friday 16 October 2009 15:39:44 Sakari Ailus wrote:

Hi,
Here's the version 2.1 of the video events RFC. It's based on Laurent Pinchart's original RFC and version 2 which I wrote some time ago. This time the changes are done based on discussion on the list. The old RFC is available here:
<URL:http://www.spinics.net/lists/linux-media/msg10971.html>
(Cc:d to Mike Krufky and Devin Heitmueller, too.)
Changes to version 2
--------------------
#define V4L2_EVENT_ALL
VIDIOC_G_EVENT -> VIDIOC_DQEVENT
Event enumeration is gone.
Reserved fields moved before data in v4l2_event and now there are 8 of them instead of 4.
Event (un)subscription argument is now v4l2_event_subscription.

Quoted 8 lines

Interface description
---------------------
Event type is either a standard event or private event. Standard events will be defined in videodev2.h. Private event types begin from V4L2_EVENT_PRIVATE. Some high order bits will be reserved for future use.
#define V4L2_EVENT_ALL 0x07ffffff

I suggest using 0 instead of 0x07ffffff. Yes, 0 is still a magic number, but somehow it feels a lot less magic :-)

Quoted 2 lines

#define V4L2_EVENT_PRIVATE_START 0x08000000
#define V4L2_EVENT_RESERVED 0x10000000

Rather than calling this RESERVED turn this into a mask:

#define V4L2_EVENT_MASK 0x0fffffff

Quoted 31 lines

VIDIOC_DQEVENT is used to get events. count is number of pending events after the current one. sequence is the event type sequence number and the data is specific to event type.
The user will get the information that there's an event through exception file descriptors by using select(2). When an event is available the poll handler sets POLLPRI which wakes up select. -EINVAL will be returned if there are no pending events.
VIDIOC_SUBSCRIBE_EVENT and VIDIOC_UNSUBSCRIBE_EVENT are used to subscribe and unsubscribe from events. The argument is struct v4l2_event_subscription which now only contains the type field for the event type. Every event can be subscribed or unsubscribed by one ioctl by using special type V4L2_EVENT_ALL.
struct v4l2_event {
	__u32		count;
	__u32		type;
	__u32		sequence;
	struct timeval	timestamp;
	__u32		reserved[8];
	__u8		data[64];
};
struct v4l2_event_subscription {
	__u32		type;
	__u32		reserved[8];
};

Quoted 5 lines

#define VIDIOC_DQEVENT _IOR('V', 84, struct v4l2_event)
#define VIDIOC_SUBSCRIBE_EVENT _IOW('V', 85, struct
v4l2_event_subscription)
#define VIDIOC_UNSUBSCRIBE_EVENT _IOW('V', 86, struct
v4l2_event_subscription)

Perhaps we should use just one ioctl and use a flag in the event_subscription struct to tell whether to subscribe or unsubscribe? Just brainstorming here.

Quoted 8 lines

The size of the event queue is decided by the driver. Which events will be discarded on queue overflow depends on the implementation.
Questions
---------

Quoted 6 lines

One more question I have is that there can be situations that the application wants to know something has happened but does not want an explicit notification from that. So it gets an event from VIDIOC_DQEVENT but does not want to get woken up for that reason. I guess one flag in event subscription should do that. Perhaps that is something that should be implemented when needed, though.

Yeah, lets implement this only when needed.

Quoted 1 line

Are there enough reserved fields now?

Personally I think 4 reserved fields for the event_subscription is enough. 8 reserved fields for that seems overkill to me.

Quoted 2 lines

How about the event type high
order bits split?

Yes, what's the purpose of that? I don't see a good reason for that.

Quoted 5 lines

What should we really call v4l2_event_subscription? A better name for the structure would be perhaps favourable.
Comments and questions are still very very welcome.

Regards,

Hans

Signature · 1 line

Hans Verkuil - video4linux developer - sponsored by TANDBERG

Sakari Ailus

author

2009-10-19 21:47 UTC #3 lore raw

Hans Verkuil wrote:
[clip]

Quoted 3 lines

Quoted 1 line
#define V4L2_EVENT_ALL 0x07ffffff
I suggest using 0 instead of 0x07ffffff. Yes, 0 is still a magic number, but somehow it feels a lot less magic :-)

Okay.

Quoted 6 lines

Quoted 2 lines
#define V4L2_EVENT_PRIVATE_START 0x08000000
#define V4L2_EVENT_RESERVED 0x10000000
Rather than calling this RESERVED turn this into a mask:
#define V4L2_EVENT_MASK 0x0fffffff

Ok.

Quoted 30 lines

Quoted 30 lines
VIDIOC_DQEVENT is used to get events. count is number of pending events after the current one. sequence is the event type sequence number and the data is specific to event type.
The user will get the information that there's an event through exception file descriptors by using select(2). When an event is available the poll handler sets POLLPRI which wakes up select. -EINVAL will be returned if there are no pending events.
VIDIOC_SUBSCRIBE_EVENT and VIDIOC_UNSUBSCRIBE_EVENT are used to subscribe and unsubscribe from events. The argument is struct v4l2_event_subscription which now only contains the type field for the event type. Every event can be subscribed or unsubscribed by one ioctl by using special type V4L2_EVENT_ALL.
struct v4l2_event {
	__u32		count;
	__u32		type;
	__u32		sequence;
	struct timeval	timestamp;
	__u32		reserved[8];
	__u8		data[64];
};
struct v4l2_event_subscription {
	__u32		type;
	__u32		reserved[8];
};

Quoted 7 lines

Quoted 5 lines
#define VIDIOC_DQEVENT _IOR('V', 84, struct v4l2_event)
#define VIDIOC_SUBSCRIBE_EVENT _IOW('V', 85, struct
v4l2_event_subscription)
#define VIDIOC_UNSUBSCRIBE_EVENT _IOW('V', 86, struct
v4l2_event_subscription)
Perhaps we should use just one ioctl and use a flag in the event_subscription struct to tell whether to subscribe or unsubscribe? Just brainstorming here.

Having two ioctls would be equivalent to STREAMON and STREAMOFF, that's why I originally picked that. I can't immediately figure a way it could be done nicely by using a flag.

Quoted 14 lines

Quoted 7 lines
The size of the event queue is decided by the driver. Which events will be discarded on queue overflow depends on the implementation.
Questions
---------
Quoted 6 lines
One more question I have is that there can be situations that the application wants to know something has happened but does not want an explicit notification from that. So it gets an event from VIDIOC_DQEVENT but does not want to get woken up for that reason. I guess one flag in event subscription should do that. Perhaps that is something that should be implemented when needed, though.

Quoted 5 lines

Yeah, lets implement this only when needed.
Quoted 1 line
Are there enough reserved fields now?
Personally I think 4 reserved fields for the event_subscription is enough. 8 reserved fields for that seems overkill to me.

struct v4l2_format is IMO a good example of having enough unused fields. ;)

I see that 8 reserved fields might make sense at least for v4l2_event. I wouldn't mind if we had that many in v4l2_event_subscription as well. There is already proposed use for three of them:

- flags (e.g. notification / no notification)
- entity

- number of pending events

The two first ones might make sense in v4l2_event_subscription as well. That would leave just two reserved fields afterwards.

The entity field would fit to v4l2_event_subscription for the same reasons than to v4l2_event; if there are several entities the event could be coming from we could limit it to just some. Perhaps a bit far-fetched but still...

And I wouldn't be surprised if a need appeared to something like priority as Tomasz suggested. After all that we'd be left with just one reserved field if we decided to use all 32 bits for priority.

The basic event delivery problem is IMO very well understood but there are just so many ideas on extensions (many of which sound quite reasonable) already at this point that I'm slightly worried about the future if we just have a few reserved fields. Unnecessary bloat still must be kept away, of course.

Quoted 3 lines

Quoted 1 line
How about the event type high order bits split?
Yes, what's the purpose of that? I don't see a good reason for that.

Me neither. Although even if we don't see use for them now it doesn't mean there couldn't be any in future. We can always say that the reserved bits are no more reserved but not the other way around.

I originally though those few bits could be used for flags that now are part of the structure.

Or we could just drop the reserved bits, I'm not against that.

Signature · 2 lines

Sakari Ailus
[email protected]

Hans Verkuil

2009-10-20 21:48 UTC #4 lore raw

Quoted 56 lines

Hans Verkuil wrote:
[clip]
Quoted 5 lines
Quoted 1 line
#define V4L2_EVENT_ALL 0x07ffffff
I suggest using 0 instead of 0x07ffffff. Yes, 0 is still a magic number, but
somehow it feels a lot less magic :-)
Okay.
Quoted 6 lines
Quoted 2 lines
#define V4L2_EVENT_PRIVATE_START 0x08000000
#define V4L2_EVENT_RESERVED 0x10000000
Rather than calling this RESERVED turn this into a mask:
#define V4L2_EVENT_MASK 0x0fffffff
Ok.
Quoted 36 lines
Quoted 35 lines
VIDIOC_DQEVENT is used to get events. count is number of pending events after the current one. sequence is the event type sequence number and the data is specific to event type.
The user will get the information that there's an event through exception file descriptors by using select(2). When an event is available the poll handler sets POLLPRI which wakes up select. -EINVAL will be returned if there are no pending events.
VIDIOC_SUBSCRIBE_EVENT and VIDIOC_UNSUBSCRIBE_EVENT are used to subscribe and unsubscribe from events. The argument is struct v4l2_event_subscription which now only contains the type field for the event type. Every event can be subscribed or unsubscribed by one ioctl by using special type V4L2_EVENT_ALL.
struct v4l2_event {
	__u32		count;
	__u32		type;
	__u32		sequence;
	struct timeval	timestamp;
	__u32		reserved[8];
	__u8		data[64];
};
struct v4l2_event_subscription {
	__u32		type;
	__u32		reserved[8];
};
#define VIDIOC_DQEVENT _IOR('V', 84, struct v4l2_event)
#define VIDIOC_SUBSCRIBE_EVENT _IOW('V', 85, struct
v4l2_event_subscription)
#define VIDIOC_UNSUBSCRIBE_EVENT _IOW('V', 86, struct
v4l2_event_subscription)

Quoted 8 lines

Quoted 4 lines
Perhaps we should use just one ioctl and use a flag in the event_subscription struct to tell whether to subscribe or unsubscribe? Just
brainstorming here.
Having two ioctls would be equivalent to STREAMON and STREAMOFF, that's why I originally picked that. I can't immediately figure a way it could be done nicely by using a flag.

OK.

Quoted 48 lines

Quoted 16 lines
Quoted 7 lines
The size of the event queue is decided by the driver. Which events will be discarded on queue overflow depends on the implementation.
Questions
---------
Quoted 8 lines
One more question I have is that there can be situations that the application wants to know something has happened but does not want an explicit notification from that. So it gets an event from VIDIOC_DQEVENT
but does not want to get woken up for that reason. I guess one flag in event subscription should do that. Perhaps that is something that should
be implemented when needed, though.
Quoted 7 lines
Yeah, lets implement this only when needed.
Quoted 1 line
Are there enough reserved fields now?
Personally I think 4 reserved fields for the event_subscription is enough. 8
reserved fields for that seems overkill to me.
struct v4l2_format is IMO a good example of having enough unused fields. ;)
I see that 8 reserved fields might make sense at least for v4l2_event. I wouldn't mind if we had that many in v4l2_event_subscription as well. There is already proposed use for three of them:
- flags (e.g. notification / no notification)
- entity
- number of pending events
The two first ones might make sense in v4l2_event_subscription as well. That would leave just two reserved fields afterwards.
The entity field would fit to v4l2_event_subscription for the same reasons than to v4l2_event; if there are several entities the event could be coming from we could limit it to just some. Perhaps a bit far-fetched but still...
And I wouldn't be surprised if a need appeared to something like priority as Tomasz suggested. After all that we'd be left with just one reserved field if we decided to use all 32 bits for priority.

Quoted 5 lines

The basic event delivery problem is IMO very well understood but there are just so many ideas on extensions (many of which sound quite reasonable) already at this point that I'm slightly worried about the future if we just have a few reserved fields. Unnecessary bloat still must be kept away, of course.

Good points. I agree with you.

Quoted 5 lines

Quoted 4 lines
Quoted 2 lines
How about the event type high
order bits split?
Yes, what's the purpose of that? I don't see a good reason for that.

Quoted 8 lines

Me neither. Although even if we don't see use for them now it doesn't mean there couldn't be any in future. We can always say that the reserved bits are no more reserved but not the other way around.
I originally though those few bits could be used for flags that now are part of the structure.
Or we could just drop the reserved bits, I'm not against that.

I propose to just drop it, but document that we shouldn't use the top 4-bits for now. We might use it in the future if we ever need an event enum and want to do something like the NEXT_CTRL flag that QUERYCTRL supports.

Regards,

Hans

Quoted 5 lines

--
Sakari Ailus
[email protected]

Signature · 1 line

Hans Verkuil - video4linux developer - sponsored by TANDBERG Telecom

Tomasz Fujak

2009-10-19 12:35 UTC #5 lore raw

In reply to Sakari Ailus

Hi,

The event count may be useful for the reason Laurent mentioned. In case we don't have dequeue multiple (DQEVENT_MULTIPLE?) a flag should be enough, saying if there are any events immediately available. That'd be just one bit we could mash into the 'type' field.

On the other hand I can imagine an event type that come swarming once a client registers to them (i.e.: VSYNC). In such a case they may overflow a queue and discard potentially useful events (i.e.: a cable detached from the output). We could do one of the following:
- nothing (let the above happen if the application is not fast enough to
retrieve events),
- suggest using separate event feed for periodic events,
- compress periodic events (provide 'compressed' flag, and stamp the event
with the timestamp of the last of the kind) - thus at most one of a periodic event type would reside in the queue,
- let the client define the window size,
- define event priorities (low, normal, high) and discard overflowing
events starting with the lowest priorities. I.e.: low for VSYNC, normal for picture decoding error and high for cable attach

Third, the event subscription scheme. What does a subscription call mean:
"Add these new events to what I already collect" or "Discard whatever I have subscribed for and now give me this"?
In the latter use, there are just 27 event types available; can't tell if that's enough till we try to enumerate the event types we currently have. I've just seen a few of them (DVB, UVC, ACPI), but I think the list would grow once people start using the v4l2 events. How big is it going to be?

Best regards

Signature · 1 line

Tomasz Fujak

Sakari Ailus

author

2009-10-19 21:08 UTC #6 lore raw

Quoted 1 line · Tomasz Fujak

Hi,

Hi, Tomasz!

Quoted 4 lines

The event count may be useful for the reason Laurent mentioned. In case we don't have dequeue multiple (DQEVENT_MULTIPLE?) a flag should be enough, saying if there are any events immediately available. That'd be just one bit we could mash into the 'type' field.

We could have also another field for flags. It's nicer to do that than use the type field for that --- we're not short of bits here.

Quoted 6 lines

On the other hand I can imagine an event type that come swarming once a client registers to them (i.e.: VSYNC). In such a case they may overflow a queue and discard potentially useful events (i.e.: a cable detached from the output). We could do one of the following:
- nothing (let the above happen if the application is not fast enough to
retrieve events),

Quoted 8 lines

- suggest using separate event feed for periodic events,
- compress periodic events (provide 'compressed' flag, and stamp the event
with the timestamp of the last of the kind) - thus at most one of a periodic event type would reside in the queue,
- let the client define the window size,
- define event priorities (low, normal, high) and discard overflowing
events starting with the lowest priorities. I.e.: low for VSYNC, normal for picture decoding error and high for cable attach

I think it's up to the driver to define the queue size. Then the queue can just overflow when it becomes full. If the client isn't fast enough to handle the events buffering them won't help in the end... for temporary scheduling delays a deeper queue should do the trick.

Another ioctl would probably be required for queue size setting if it's ever needed. This is IMO more or less equivalent to setting the maximum allocatable memory for video buffers, which is indeed fixed to video drivers themselves.

Quoted 3 lines

Third, the event subscription scheme. What does a subscription call mean:
"Add these new events to what I already collect" or "Discard whatever I have subscribed for and now give me this"?

Add this one / remove this one. The type is a 32-number so we should have enough different kind of events. :)

Quoted 4 lines

In the latter use, there are just 27 event types available; can't tell if that's enough till we try to enumerate the event types we currently have. I've just seen a few of them (DVB, UVC, ACPI), but I think the list would grow once people start using the v4l2 events. How big is it going to be?

Let's hope people start using this once it's available...

Signature · 2 lines

Sakari Ailus
[email protected]