| Sakari Ailus | dd96608 | 2010-03-27 10:58:24 -0300 | [diff] [blame] | 1 | <title>Event Interface</title> |
| 2 | |
| Hans Verkuil | e969084 | 2011-06-18 06:58:29 -0300 | [diff] [blame] | 3 | <para>The V4L2 event interface provides a means for a user to get |
| Sakari Ailus | dd96608 | 2010-03-27 10:58:24 -0300 | [diff] [blame] | 4 | immediately notified on certain conditions taking place on a device. |
| 5 | This might include start of frame or loss of signal events, for |
| Hans Verkuil | e969084 | 2011-06-18 06:58:29 -0300 | [diff] [blame] | 6 | example. Changes in the value or state of a V4L2 control can also be |
| 7 | reported through events. |
| Sakari Ailus | dd96608 | 2010-03-27 10:58:24 -0300 | [diff] [blame] | 8 | </para> |
| 9 | |
| 10 | <para>To receive events, the events the user is interested in first must |
| 11 | be subscribed using the &VIDIOC-SUBSCRIBE-EVENT; ioctl. Once an event is |
| 12 | subscribed, the events of subscribed types are dequeueable using the |
| 13 | &VIDIOC-DQEVENT; ioctl. Events may be unsubscribed using |
| 14 | VIDIOC_UNSUBSCRIBE_EVENT ioctl. The special event type V4L2_EVENT_ALL may |
| 15 | be used to unsubscribe all the events the driver supports.</para> |
| 16 | |
| 17 | <para>The event subscriptions and event queues are specific to file |
| 18 | handles. Subscribing an event on one file handle does not affect |
| Hans Verkuil | e969084 | 2011-06-18 06:58:29 -0300 | [diff] [blame] | 19 | other file handles.</para> |
| Sakari Ailus | dd96608 | 2010-03-27 10:58:24 -0300 | [diff] [blame] | 20 | |
| 21 | <para>The information on dequeueable events is obtained by using select or |
| 22 | poll system calls on video devices. The V4L2 events use POLLPRI events on |
| Hans Verkuil | e969084 | 2011-06-18 06:58:29 -0300 | [diff] [blame] | 23 | poll system call and exceptions on select system call.</para> |
| 24 | |
| 25 | <para>Starting with kernel 3.1 certain guarantees can be given with |
| 26 | regards to events:<orderedlist> |
| 27 | <listitem> |
| 28 | <para>Each subscribed event has its own internal dedicated event queue. |
| 29 | This means that flooding of one event type will not interfere with other |
| 30 | event types.</para> |
| 31 | </listitem> |
| 32 | <listitem> |
| 33 | <para>If the internal event queue for a particular subscribed event |
| 34 | becomes full, then the oldest event in that queue will be dropped.</para> |
| 35 | </listitem> |
| 36 | <listitem> |
| 37 | <para>Where applicable, certain event types can ensure that the payload |
| 38 | of the oldest event that is about to be dropped will be merged with the payload |
| 39 | of the next oldest event. Thus ensuring that no information is lost, but only an |
| 40 | intermediate step leading up to that information. See the documentation for the |
| 41 | event you want to subscribe to whether this is applicable for that event or not.</para> |
| 42 | </listitem> |
| 43 | </orderedlist></para> |