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