Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 1 | .. -*- coding: utf-8; mode: rst -*- |
| 2 | |
| 3 | .. _event: |
| 4 | |
| 5 | *************** |
| 6 | Event Interface |
| 7 | *************** |
| 8 | |
| 9 | The V4L2 event interface provides a means for a user to get immediately |
| 10 | notified on certain conditions taking place on a device. This might |
| 11 | include start of frame or loss of signal events, for example. Changes in |
| 12 | the value or state of a V4L2 control can also be reported through |
| 13 | events. |
| 14 | |
| 15 | To receive events, the events the user is interested in first must be |
| 16 | subscribed using the |
Mauro Carvalho Chehab | af4a4d0 | 2016-07-01 13:42:29 -0300 | [diff] [blame^] | 17 | :ref:`VIDIOC_SUBSCRIBE_EVENT <VIDIOC_SUBSCRIBE_EVENT>` ioctl. Once |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 18 | an event is subscribed, the events of subscribed types are dequeueable |
Mauro Carvalho Chehab | af4a4d0 | 2016-07-01 13:42:29 -0300 | [diff] [blame^] | 19 | using the :ref:`VIDIOC_DQEVENT <VIDIOC_DQEVENT>` ioctl. Events may be |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 20 | unsubscribed using VIDIOC_UNSUBSCRIBE_EVENT ioctl. The special event |
| 21 | type V4L2_EVENT_ALL may be used to unsubscribe all the events the |
| 22 | driver supports. |
| 23 | |
| 24 | The event subscriptions and event queues are specific to file handles. |
| 25 | Subscribing an event on one file handle does not affect other file |
| 26 | handles. |
| 27 | |
| 28 | The information on dequeueable events is obtained by using select or |
| 29 | poll system calls on video devices. The V4L2 events use POLLPRI events |
| 30 | on poll system call and exceptions on select system call. |
| 31 | |
| 32 | Starting with kernel 3.1 certain guarantees can be given with regards to |
| 33 | events: |
| 34 | |
| 35 | 1. Each subscribed event has its own internal dedicated event queue. |
| 36 | This means that flooding of one event type will not interfere with |
| 37 | other event types. |
| 38 | |
| 39 | 2. If the internal event queue for a particular subscribed event becomes |
| 40 | full, then the oldest event in that queue will be dropped. |
| 41 | |
| 42 | 3. Where applicable, certain event types can ensure that the payload of |
| 43 | the oldest event that is about to be dropped will be merged with the |
| 44 | payload of the next oldest event. Thus ensuring that no information |
| 45 | is lost, but only an intermediate step leading up to that |
| 46 | information. See the documentation for the event you want to |
| 47 | subscribe to whether this is applicable for that event or not. |
| 48 | |
| 49 | |
| 50 | .. ------------------------------------------------------------------------------ |
| 51 | .. This file was automatically converted from DocBook-XML with the dbxml |
| 52 | .. library (https://github.com/return42/sphkerneldoc). The origin XML comes |
| 53 | .. from the linux kernel, refer to: |
| 54 | .. |
| 55 | .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook |
| 56 | .. ------------------------------------------------------------------------------ |