Documentation/media/kapi/v4l2-event.rst

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