[RFC] Video events, version 2.1

[RFC] Video events, version 2.1

[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.

-- 
Sakari Ailus
sakari.ailus@maxwell.research.nokia.com

Re: [RFC] Video events, version 2.1

[Michael Krufky]

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

Thanks,

Mike

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.
>
> 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.
>
> -- 
> Sakari Ailus
> sakari.ailus@maxwell.research.nokia.com
>

Re: [RFC] Video events, version 2.1

[Hans Verkuil]

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.
>
> 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 :-)

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

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

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.

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

Yeah, lets implement this only when needed.

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

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

> 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

-- 
Hans Verkuil - video4linux developer - sponsored by TANDBERG

Re: [RFC] Video events, version 2.1

[Sakari Ailus]

Hans Verkuil wrote:
[clip]
>> #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.

>> #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.

>> 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)
> 
> 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.

>> 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.
> 
> Yeah, lets implement this only when needed.
> 
>> 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.

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

-- 
Sakari Ailus
sakari.ailus@maxwell.research.nokia.com

Re: [RFC] Video events, version 2.1

[Hans Verkuil]

> Hans Verkuil wrote:
> [clip]
>>> #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.
>
>>> #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.
>
>>> 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)
>>
>> 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.

>>> 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.
>>
>> Yeah, lets implement this only when needed.
>>
>>> 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.

Good points. I agree with you.

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

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

>
> --
> Sakari Ailus
> sakari.ailus@maxwell.research.nokia.com
>


-- 
Hans Verkuil - video4linux developer - sponsored by TANDBERG Telecom

RE: [RFC] Video events, version 2.1

[Tomasz Fujak]

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
-- 
Tomasz Fujak

Re: [RFC] Video events, version 2.1

[Sakari Ailus]

Tomasz Fujak wrote:
> Hi,

Hi, Tomasz!

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

> 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

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.

> 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. :)

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

-- 
Sakari Ailus
sakari.ailus@maxwell.research.nokia.com