1 2V4L2 events 3----------- 4 5The V4L2 events provide a generic way to pass events to user space. 6The driver must use :c:type:`v4l2_fh` to be able to support V4L2 events. 7 8Events are subscribed per-filehandle. An event specification consists of a 9``type`` and is optionally associated with an object identified through the 10``id`` field. If unused, then the ``id`` is 0. So an event is uniquely 11identified by the ``(type, id)`` tuple. 12 13The :c:type:`v4l2_fh` struct has a list of subscribed events on its 14``subscribed`` field. 15 16When the user subscribes to an event, a :c:type:`v4l2_subscribed_event` 17struct is added to :c:type:`v4l2_fh`\ ``.subscribed``, one for every 18subscribed event. 19 20Each :c:type:`v4l2_subscribed_event` struct ends with a 21:c:type:`v4l2_kevent` ringbuffer, with the size given by the caller 22of :c:func:`v4l2_event_subscribe`. This ringbuffer is used to store any events 23raised by the driver. 24 25So every ``(type, ID)`` event tuple will have its own 26:c:type:`v4l2_kevent` ringbuffer. This guarantees that if a driver is 27generating lots of events of one type in a short time, then that will 28not overwrite events of another type. 29 30But if you get more events of one type than the size of the 31:c:type:`v4l2_kevent` ringbuffer, then the oldest event will be dropped 32and the new one added. 33 34The :c:type:`v4l2_kevent` struct links into the ``available`` 35list of the :c:type:`v4l2_fh` struct so :ref:`VIDIOC_DQEVENT` will 36know which event to dequeue first. 37 38Finally, if the event subscription is associated with a particular object 39such as a V4L2 control, then that object needs to know about that as well 40so that an event can be raised by that object. So the ``node`` field can 41be used to link the :c:type:`v4l2_subscribed_event` struct into a list of 42such objects. 43 44So to summarize: 45 46- struct :c:type:`v4l2_fh` has two lists: one of the ``subscribed`` events, 47 and one of the ``available`` events. 48 49- struct :c:type:`v4l2_subscribed_event` has a ringbuffer of raised 50 (pending) events of that particular type. 51 52- If struct :c:type:`v4l2_subscribed_event` is associated with a specific 53 object, then that object will have an internal list of 54 struct :c:type:`v4l2_subscribed_event` so it knows who subscribed an 55 event to that object. 56 57Furthermore, the internal struct :c:type:`v4l2_subscribed_event` has 58``merge()`` and ``replace()`` callbacks which drivers can set. These 59callbacks are called when a new event is raised and there is no more room. 60 61The ``replace()`` callback allows you to replace the payload of the old event 62with that of the new event, merging any relevant data from the old payload 63into the new payload that replaces it. It is called when this event type has 64a ringbuffer with size is one, i.e. only one event can be stored in the 65ringbuffer. 66 67The ``merge()`` callback allows you to merge the oldest event payload into 68that of the second-oldest event payload. It is called when 69the ringbuffer has size is greater than one. 70 71This way no status information is lost, just the intermediate steps leading 72up to that state. 73 74A good example of these ``replace``/``merge`` callbacks is in v4l2-event.c: 75``ctrls_replace()`` and ``ctrls_merge()`` callbacks for the control event. 76 77.. note:: 78 these callbacks can be called from interrupt context, so they must 79 be fast. 80 81In order to queue events to video device, drivers should call: 82 83 :c:func:`v4l2_event_queue <v4l2_event_queue>` 84 (:c:type:`vdev <video_device>`, :c:type:`ev <v4l2_event>`) 85 86The driver's only responsibility is to fill in the type and the data fields. 87The other fields will be filled in by V4L2. 88 89Event subscription 90~~~~~~~~~~~~~~~~~~ 91 92Subscribing to an event is via: 93 94 :c:func:`v4l2_event_subscribe <v4l2_event_subscribe>` 95 (:c:type:`fh <v4l2_fh>`, :c:type:`sub <v4l2_event_subscription>` , 96 elems, :c:type:`ops <v4l2_subscribed_event_ops>`) 97 98 99This function is used to implement :c:type:`video_device`-> 100:c:type:`ioctl_ops <v4l2_ioctl_ops>`-> ``vidioc_subscribe_event``, 101but the driver must check first if the driver is able to produce events 102with specified event id, and then should call 103:c:func:`v4l2_event_subscribe` to subscribe the event. 104 105The elems argument is the size of the event queue for this event. If it is 0, 106then the framework will fill in a default value (this depends on the event 107type). 108 109The ops argument allows the driver to specify a number of callbacks: 110 111.. tabularcolumns:: |p{1.5cm}|p{16.0cm}| 112 113======== ============================================================== 114Callback Description 115======== ============================================================== 116add called when a new listener gets added (subscribing to the same 117 event twice will only cause this callback to get called once) 118del called when a listener stops listening 119replace replace event 'old' with event 'new'. 120merge merge event 'old' into event 'new'. 121======== ============================================================== 122 123All 4 callbacks are optional, if you don't want to specify any callbacks 124the ops argument itself maybe ``NULL``. 125 126Unsubscribing an event 127~~~~~~~~~~~~~~~~~~~~~~ 128 129Unsubscribing to an event is via: 130 131 :c:func:`v4l2_event_unsubscribe <v4l2_event_unsubscribe>` 132 (:c:type:`fh <v4l2_fh>`, :c:type:`sub <v4l2_event_subscription>`) 133 134This function is used to implement :c:type:`video_device`-> 135:c:type:`ioctl_ops <v4l2_ioctl_ops>`-> ``vidioc_unsubscribe_event``. 136A driver may call :c:func:`v4l2_event_unsubscribe` directly unless it 137wants to be involved in unsubscription process. 138 139The special type ``V4L2_EVENT_ALL`` may be used to unsubscribe all events. The 140drivers may want to handle this in a special way. 141 142Check if there's a pending event 143~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 144 145Checking if there's a pending event is via: 146 147 :c:func:`v4l2_event_pending <v4l2_event_pending>` 148 (:c:type:`fh <v4l2_fh>`) 149 150 151This function returns the number of pending events. Useful when implementing 152poll. 153 154How events work 155~~~~~~~~~~~~~~~ 156 157Events are delivered to user space through the poll system call. The driver 158can use :c:type:`v4l2_fh`->wait (a wait_queue_head_t) as the argument for 159``poll_wait()``. 160 161There are standard and private events. New standard events must use the 162smallest available event type. The drivers must allocate their events from 163their own class starting from class base. Class base is 164``V4L2_EVENT_PRIVATE_START`` + n * 1000 where n is the lowest available number. 165The first event type in the class is reserved for future use, so the first 166available event type is 'class base + 1'. 167 168An example on how the V4L2 events may be used can be found in the OMAP 1693 ISP driver (``drivers/media/platform/omap3isp``). 170 171A subdev can directly send an event to the :c:type:`v4l2_device` notify 172function with ``V4L2_DEVICE_NOTIFY_EVENT``. This allows the bridge to map 173the subdev that sends the event to the video node(s) associated with the 174subdev that need to be informed about such an event. 175 176V4L2 event functions and data structures 177^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 178 179.. kernel-doc:: include/media/v4l2-event.h 180 181