Commit | Line | Data |
---|---|---|
8f511fc4 MCC |
1 | |
2 | V4L2 events | |
3 | ----------- | |
4 | ||
5 | The V4L2 events provide a generic way to pass events to user space. | |
d2316856 | 6 | The driver must use :c:type:`v4l2_fh` to be able to support V4L2 events. |
8f511fc4 MCC |
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 | ||
d2316856 MCC |
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. | |
8f511fc4 MCC |
29 | |
30 | This way no status information is lost, just the intermediate steps leading | |
31 | up to that state. | |
32 | ||
d2316856 MCC |
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. | |
8f511fc4 | 35 | |
d2316856 MCC |
36 | .. note:: |
37 | these callbacks can be called from interrupt context, so they must | |
38 | be fast. | |
8f511fc4 | 39 | |
d2316856 | 40 | In order to queue events to video device, drivers should call: |
8f511fc4 | 41 | |
7b998bae | 42 | :c:func:`v4l2_event_queue <v4l2_event_queue>` |
e8be7e97 | 43 | (:c:type:`vdev <video_device>`, :c:type:`ev <v4l2_event>`) |
8f511fc4 | 44 | |
d2316856 MCC |
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. | |
8f511fc4 | 47 | |
d2316856 MCC |
48 | Event subscription |
49 | ~~~~~~~~~~~~~~~~~~ | |
8f511fc4 | 50 | |
d2316856 | 51 | Subscribing to an event is via: |
8f511fc4 | 52 | |
7b998bae | 53 | :c:func:`v4l2_event_subscribe <v4l2_event_subscribe>` |
e8be7e97 | 54 | (:c:type:`fh <v4l2_fh>`, :c:type:`sub <v4l2_event_subscription>` , |
d2316856 | 55 | elems, :c:type:`ops <v4l2_subscribed_event_ops>`) |
8f511fc4 | 56 | |
8f511fc4 | 57 | |
d2316856 MCC |
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 | |
7b998bae | 62 | :c:func:`v4l2_event_subscribe` to subscribe the event. |
8f511fc4 | 63 | |
d2316856 MCC |
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). | |
8f511fc4 | 67 | |
d2316856 | 68 | The ops argument allows the driver to specify a number of callbacks: |
8f511fc4 | 69 | |
d2316856 MCC |
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 | ======== ============================================================== | |
8f511fc4 | 79 | |
d2316856 MCC |
80 | All 4 callbacks are optional, if you don't want to specify any callbacks |
81 | the ops argument itself maybe ``NULL``. | |
8f511fc4 | 82 | |
d2316856 MCC |
83 | Unsubscribing an event |
84 | ~~~~~~~~~~~~~~~~~~~~~~ | |
8f511fc4 | 85 | |
d2316856 | 86 | Unsubscribing to an event is via: |
8f511fc4 | 87 | |
7b998bae | 88 | :c:func:`v4l2_event_unsubscribe <v4l2_event_unsubscribe>` |
e8be7e97 | 89 | (:c:type:`fh <v4l2_fh>`, :c:type:`sub <v4l2_event_subscription>`) |
8f511fc4 | 90 | |
d2316856 MCC |
91 | This function is used to implement :c:type:`video_device`-> |
92 | :c:type:`ioctl_ops <v4l2_ioctl_ops>`-> ``vidioc_unsubscribe_event``. | |
7b998bae | 93 | A driver may call :c:func:`v4l2_event_unsubscribe` directly unless it |
d2316856 MCC |
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 | ||
7b998bae | 104 | :c:func:`v4l2_event_pending <v4l2_event_pending>` |
d2316856 MCC |
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 | ~~~~~~~~~~~~~~~ | |
8f511fc4 MCC |
113 | |
114 | Events are delivered to user space through the poll system call. The driver | |
d2316856 MCC |
115 | can use :c:type:`v4l2_fh`->wait (a wait_queue_head_t) as the argument for |
116 | ``poll_wait()``. | |
8f511fc4 MCC |
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 | |
d2316856 | 121 | ``V4L2_EVENT_PRIVATE_START`` + n * 1000 where n is the lowest available number. |
8f511fc4 MCC |
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 | |
d2316856 | 126 | 3 ISP driver (``drivers/media/platform/omap3isp``). |
8f511fc4 | 127 | |
d2316856 MCC |
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. | |
8f511fc4 | 132 | |
f6fa883b MCC |
133 | V4L2 event functions and data structures |
134 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
58759874 MCC |
135 | |
136 | .. kernel-doc:: include/media/v4l2-event.h | |
f6fa883b | 137 |