Documentation/media/kapi/v4l2-event.rst

   1
   2 V4L2 events
   3 -----------
   4
   5 The V4L2 events provide a generic way to pass events to user space.
   6 The driver must use :c:type:`v4l2_fh` to be able to support V4L2 events.
   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
  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.
  29
  30 This way no status information is lost, just the intermediate steps leading
  31 up to that state.
  32
  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.
  35
  36 .. note::
  37         these callbacks can be called from interrupt context, so they must
  38         be fast.
  39
  40 In 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
  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.
  47
  48 Event subscription
  49 ~~~~~~~~~~~~~~~~~~
  50
  51 Subscribing 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
  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 :c:func:`v4l2_event_subscribe` to subscribe the event.
  63
  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).
  67
  68 The ops argument allows the driver to specify a number of callbacks:
  69
  70 .. tabularcolumns:: |p{1.5cm}|p{16.0cm}|
  71
  72 ======== ==============================================================
  73 Callback Description
  74 ======== ==============================================================
  75 add      called when a new listener gets added (subscribing to the same
  76          event twice will only cause this callback to get called once)
  77 del      called when a listener stops listening
  78 replace  replace event 'old' with event 'new'.
  79 merge    merge event 'old' into event 'new'.
  80 ======== ==============================================================
  81
  82 All 4 callbacks are optional, if you don't want to specify any callbacks
  83 the ops argument itself maybe ``NULL``.
  84
  85 Unsubscribing an event
  86 ~~~~~~~~~~~~~~~~~~~~~~
  87
  88 Unsubscribing 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
  93 This function is used to implement :c:type:`video_device`->
  94 :c:type:`ioctl_ops <v4l2_ioctl_ops>`-> ``vidioc_unsubscribe_event``.
  95 A driver may call :c:func:`v4l2_event_unsubscribe` directly unless it
  96 wants to be involved in unsubscription process.
  97
  98 The special type ``V4L2_EVENT_ALL`` may be used to unsubscribe all events. The
  99 drivers may want to handle this in a special way.
 100
 101 Check if there's a pending event
 102 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 103
 104 Checking 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
 110 This function returns the number of pending events. Useful when implementing
 111 poll.
 112
 113 How events work
 114 ~~~~~~~~~~~~~~~
 115
 116 Events are delivered to user space through the poll system call. The driver
 117 can use :c:type:`v4l2_fh`->wait (a wait_queue_head_t) as the argument for
 118 ``poll_wait()``.
 119
 120 There are standard and private events. New standard events must use the
 121 smallest available event type. The drivers must allocate their events from
 122 their own class starting from class base. Class base is
 123 ``V4L2_EVENT_PRIVATE_START`` + n * 1000 where n is the lowest available number.
 124 The first event type in the class is reserved for future use, so the first
 125 available event type is 'class base + 1'.
 126
 127 An example on how the V4L2 events may be used can be found in the OMAP
 128 3 ISP driver (``drivers/media/platform/omap3isp``).
 129
 130 A subdev can directly send an event to the :c:type:`v4l2_device` notify
 131 function with ``V4L2_DEVICE_NOTIFY_EVENT``. This allows the bridge to map
 132 the subdev that sends the event to the video node(s) associated with the
 133 subdev that need to be informed about such an event.
 134
 135 V4L2 event functions and data structures
 136 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 137
 138 .. kernel-doc:: include/media/v4l2-event.h
 139