Mauro Carvalho Chehab | 8f511fc | 2016-07-22 06:54:48 -0300 | [diff] [blame] | 1 | |
| 2 | V4L2 events |
| 3 | ----------- |
| 4 | |
| 5 | The V4L2 events provide a generic way to pass events to user space. |
Mauro Carvalho Chehab | d231685 | 2016-07-22 08:43:30 -0300 | [diff] [blame] | 6 | The driver must use :c:type:`v4l2_fh` to be able to support V4L2 events. |
Mauro Carvalho Chehab | 8f511fc | 2016-07-22 06:54:48 -0300 | [diff] [blame] | 7 | |
| 8 | Events are defined by a type and an optional ID. The ID may refer to a V4L2 |
| 9 | object such as a control ID. If unused, then the ID is 0. |
| 10 | |
| 11 | When the user subscribes to an event the driver will allocate a number of |
| 12 | kevent structs for that event. So every (type, ID) event tuple will have |
| 13 | its own set of kevent structs. This guarantees that if a driver is generating |
| 14 | lots of events of one type in a short time, then that will not overwrite |
| 15 | events of another type. |
| 16 | |
| 17 | But if you get more events of one type than the number of kevents that were |
| 18 | reserved, then the oldest event will be dropped and the new one added. |
| 19 | |
Mauro Carvalho Chehab | d231685 | 2016-07-22 08:43:30 -0300 | [diff] [blame] | 20 | Furthermore, the internal struct :c:type:`v4l2_subscribed_event` has |
| 21 | ``merge()`` and ``replace()`` callbacks which drivers can set. These |
| 22 | callbacks are called when a new event is raised and there is no more room. |
| 23 | The ``replace()`` callback allows you to replace the payload of the old event |
| 24 | with that of the new event, merging any relevant data from the old payload |
| 25 | into the new payload that replaces it. It is called when this event type has |
| 26 | only one kevent struct allocated. The ``merge()`` callback allows you to merge |
| 27 | the oldest event payload into that of the second-oldest event payload. It is |
| 28 | called when there are two or more kevent structs allocated. |
Mauro Carvalho Chehab | 8f511fc | 2016-07-22 06:54:48 -0300 | [diff] [blame] | 29 | |
| 30 | This way no status information is lost, just the intermediate steps leading |
| 31 | up to that state. |
| 32 | |
Mauro Carvalho Chehab | d231685 | 2016-07-22 08:43:30 -0300 | [diff] [blame] | 33 | A good example of these ``replace``/``merge`` callbacks is in v4l2-event.c: |
| 34 | ``ctrls_replace()`` and ``ctrls_merge()`` callbacks for the control event. |
Mauro Carvalho Chehab | 8f511fc | 2016-07-22 06:54:48 -0300 | [diff] [blame] | 35 | |
Mauro Carvalho Chehab | d231685 | 2016-07-22 08:43:30 -0300 | [diff] [blame] | 36 | .. note:: |
| 37 | these callbacks can be called from interrupt context, so they must |
| 38 | be fast. |
Mauro Carvalho Chehab | 8f511fc | 2016-07-22 06:54:48 -0300 | [diff] [blame] | 39 | |
Mauro Carvalho Chehab | d231685 | 2016-07-22 08:43:30 -0300 | [diff] [blame] | 40 | In order to queue events to video device, drivers should call: |
Mauro Carvalho Chehab | 8f511fc | 2016-07-22 06:54:48 -0300 | [diff] [blame] | 41 | |
Mauro Carvalho Chehab | d231685 | 2016-07-22 08:43:30 -0300 | [diff] [blame] | 42 | :cpp:func:`v4l2_event_queue <v4l2_event_queue>` |
| 43 | (:c:type:`vdev <video_device>`, :ref:`ev <v4l2-event>`) |
Mauro Carvalho Chehab | 8f511fc | 2016-07-22 06:54:48 -0300 | [diff] [blame] | 44 | |
Mauro Carvalho Chehab | d231685 | 2016-07-22 08:43:30 -0300 | [diff] [blame] | 45 | The driver's only responsibility is to fill in the type and the data fields. |
| 46 | The other fields will be filled in by V4L2. |
Mauro Carvalho Chehab | 8f511fc | 2016-07-22 06:54:48 -0300 | [diff] [blame] | 47 | |
Mauro Carvalho Chehab | d231685 | 2016-07-22 08:43:30 -0300 | [diff] [blame] | 48 | Event subscription |
| 49 | ~~~~~~~~~~~~~~~~~~ |
Mauro Carvalho Chehab | 8f511fc | 2016-07-22 06:54:48 -0300 | [diff] [blame] | 50 | |
Mauro Carvalho Chehab | d231685 | 2016-07-22 08:43:30 -0300 | [diff] [blame] | 51 | Subscribing to an event is via: |
Mauro Carvalho Chehab | 8f511fc | 2016-07-22 06:54:48 -0300 | [diff] [blame] | 52 | |
Mauro Carvalho Chehab | d231685 | 2016-07-22 08:43:30 -0300 | [diff] [blame] | 53 | :cpp:func:`v4l2_event_subscribe <v4l2_event_subscribe>` |
| 54 | (:c:type:`fh <v4l2_fh>`, :ref:`sub <v4l2-event-subscription>` , |
| 55 | elems, :c:type:`ops <v4l2_subscribed_event_ops>`) |
Mauro Carvalho Chehab | 8f511fc | 2016-07-22 06:54:48 -0300 | [diff] [blame] | 56 | |
Mauro Carvalho Chehab | 8f511fc | 2016-07-22 06:54:48 -0300 | [diff] [blame] | 57 | |
Mauro Carvalho Chehab | d231685 | 2016-07-22 08:43:30 -0300 | [diff] [blame] | 58 | This function is used to implement :c:type:`video_device`-> |
| 59 | :c:type:`ioctl_ops <v4l2_ioctl_ops>`-> ``vidioc_subscribe_event``, |
| 60 | but the driver must check first if the driver is able to produce events |
| 61 | with specified event id, and then should call |
| 62 | :cpp:func:`v4l2_event_subscribe` to subscribe the event. |
Mauro Carvalho Chehab | 8f511fc | 2016-07-22 06:54:48 -0300 | [diff] [blame] | 63 | |
Mauro Carvalho Chehab | d231685 | 2016-07-22 08:43:30 -0300 | [diff] [blame] | 64 | The elems argument is the size of the event queue for this event. If it is 0, |
| 65 | then the framework will fill in a default value (this depends on the event |
| 66 | type). |
Mauro Carvalho Chehab | 8f511fc | 2016-07-22 06:54:48 -0300 | [diff] [blame] | 67 | |
Mauro Carvalho Chehab | d231685 | 2016-07-22 08:43:30 -0300 | [diff] [blame] | 68 | The ops argument allows the driver to specify a number of callbacks: |
Mauro Carvalho Chehab | 8f511fc | 2016-07-22 06:54:48 -0300 | [diff] [blame] | 69 | |
Mauro Carvalho Chehab | d231685 | 2016-07-22 08:43:30 -0300 | [diff] [blame] | 70 | ======== ============================================================== |
| 71 | Callback Description |
| 72 | ======== ============================================================== |
| 73 | add called when a new listener gets added (subscribing to the same |
| 74 | event twice will only cause this callback to get called once) |
| 75 | del called when a listener stops listening |
| 76 | replace replace event 'old' with event 'new'. |
| 77 | merge merge event 'old' into event 'new'. |
| 78 | ======== ============================================================== |
Mauro Carvalho Chehab | 8f511fc | 2016-07-22 06:54:48 -0300 | [diff] [blame] | 79 | |
Mauro Carvalho Chehab | d231685 | 2016-07-22 08:43:30 -0300 | [diff] [blame] | 80 | All 4 callbacks are optional, if you don't want to specify any callbacks |
| 81 | the ops argument itself maybe ``NULL``. |
Mauro Carvalho Chehab | 8f511fc | 2016-07-22 06:54:48 -0300 | [diff] [blame] | 82 | |
Mauro Carvalho Chehab | d231685 | 2016-07-22 08:43:30 -0300 | [diff] [blame] | 83 | Unsubscribing an event |
| 84 | ~~~~~~~~~~~~~~~~~~~~~~ |
Mauro Carvalho Chehab | 8f511fc | 2016-07-22 06:54:48 -0300 | [diff] [blame] | 85 | |
Mauro Carvalho Chehab | d231685 | 2016-07-22 08:43:30 -0300 | [diff] [blame] | 86 | Unsubscribing to an event is via: |
Mauro Carvalho Chehab | 8f511fc | 2016-07-22 06:54:48 -0300 | [diff] [blame] | 87 | |
Mauro Carvalho Chehab | d231685 | 2016-07-22 08:43:30 -0300 | [diff] [blame] | 88 | :cpp:func:`v4l2_event_unsubscribe <v4l2_event_unsubscribe>` |
| 89 | (:c:type:`fh <v4l2_fh>`, :ref:`sub <v4l2-event-subscription>`) |
Mauro Carvalho Chehab | 8f511fc | 2016-07-22 06:54:48 -0300 | [diff] [blame] | 90 | |
Mauro Carvalho Chehab | d231685 | 2016-07-22 08:43:30 -0300 | [diff] [blame] | 91 | This function is used to implement :c:type:`video_device`-> |
| 92 | :c:type:`ioctl_ops <v4l2_ioctl_ops>`-> ``vidioc_unsubscribe_event``. |
| 93 | A driver may call :cpp:func:`v4l2_event_unsubscribe` directly unless it |
| 94 | wants to be involved in unsubscription process. |
| 95 | |
| 96 | The special type ``V4L2_EVENT_ALL`` may be used to unsubscribe all events. The |
| 97 | drivers may want to handle this in a special way. |
| 98 | |
| 99 | Check if there's a pending event |
| 100 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 101 | |
| 102 | Checking if there's a pending event is via: |
| 103 | |
| 104 | :cpp:func:`v4l2_event_pending <v4l2_event_pending>` |
| 105 | (:c:type:`fh <v4l2_fh>`) |
| 106 | |
| 107 | |
| 108 | This function returns the number of pending events. Useful when implementing |
| 109 | poll. |
| 110 | |
| 111 | How events work |
| 112 | ~~~~~~~~~~~~~~~ |
Mauro Carvalho Chehab | 8f511fc | 2016-07-22 06:54:48 -0300 | [diff] [blame] | 113 | |
| 114 | Events are delivered to user space through the poll system call. The driver |
Mauro Carvalho Chehab | d231685 | 2016-07-22 08:43:30 -0300 | [diff] [blame] | 115 | can use :c:type:`v4l2_fh`->wait (a wait_queue_head_t) as the argument for |
| 116 | ``poll_wait()``. |
Mauro Carvalho Chehab | 8f511fc | 2016-07-22 06:54:48 -0300 | [diff] [blame] | 117 | |
| 118 | There are standard and private events. New standard events must use the |
| 119 | smallest available event type. The drivers must allocate their events from |
| 120 | their own class starting from class base. Class base is |
Mauro Carvalho Chehab | d231685 | 2016-07-22 08:43:30 -0300 | [diff] [blame] | 121 | ``V4L2_EVENT_PRIVATE_START`` + n * 1000 where n is the lowest available number. |
Mauro Carvalho Chehab | 8f511fc | 2016-07-22 06:54:48 -0300 | [diff] [blame] | 122 | The first event type in the class is reserved for future use, so the first |
| 123 | available event type is 'class base + 1'. |
| 124 | |
| 125 | An example on how the V4L2 events may be used can be found in the OMAP |
Mauro Carvalho Chehab | d231685 | 2016-07-22 08:43:30 -0300 | [diff] [blame] | 126 | 3 ISP driver (``drivers/media/platform/omap3isp``). |
Mauro Carvalho Chehab | 8f511fc | 2016-07-22 06:54:48 -0300 | [diff] [blame] | 127 | |
Mauro Carvalho Chehab | d231685 | 2016-07-22 08:43:30 -0300 | [diff] [blame] | 128 | A subdev can directly send an event to the :c:type:`v4l2_device` notify |
| 129 | function with ``V4L2_DEVICE_NOTIFY_EVENT``. This allows the bridge to map |
| 130 | the subdev that sends the event to the video node(s) associated with the |
| 131 | subdev that need to be informed about such an event. |
Mauro Carvalho Chehab | 8f511fc | 2016-07-22 06:54:48 -0300 | [diff] [blame] | 132 | |
Mauro Carvalho Chehab | f6fa883 | 2016-07-22 10:15:42 -0300 | [diff] [blame^] | 133 | V4L2 event functions and data structures |
| 134 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
Mauro Carvalho Chehab | 5875987 | 2016-07-20 14:14:37 -0300 | [diff] [blame] | 135 | |
| 136 | .. kernel-doc:: include/media/v4l2-event.h |
Mauro Carvalho Chehab | f6fa883 | 2016-07-22 10:15:42 -0300 | [diff] [blame^] | 137 | |