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 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 v4l2_subscribed_event has merge() and
  21 replace() callbacks which drivers can set. These callbacks are called when
  22 a new event is raised and there is no more room. The replace() callback
  23 allows you to replace the payload of the old event with that of the new event,
  24 merging any relevant data from the old payload into the new payload that
  25 replaces it. It is called when this event type has only one kevent struct
  26 allocated. The merge() callback allows you to merge the oldest event payload
  27 into that of the second-oldest event payload. It is called when there are two
  28 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: these callbacks can be called from interrupt context, so they must be
  37 fast.
  38
  39 Useful functions:
  40
  41 .. code-block:: none
  42
  43         void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev)
  44
  45   Queue events to video device. The driver's only responsibility is to fill
  46   in the type and the data fields. The other fields will be filled in by
  47   V4L2.
  48
  49 .. code-block:: none
  50
  51         int v4l2_event_subscribe(struct v4l2_fh *fh,
  52                                  struct v4l2_event_subscription *sub, unsigned elems,
  53                                  const struct v4l2_subscribed_event_ops *ops)
  54
  55   The video_device->ioctl_ops->vidioc_subscribe_event must check the driver
  56   is able to produce events with specified event id. Then it calls
  57   v4l2_event_subscribe() to subscribe the event.
  58
  59   The elems argument is the size of the event queue for this event. If it is 0,
  60   then the framework will fill in a default value (this depends on the event
  61   type).
  62
  63   The ops argument allows the driver to specify a number of callbacks:
  64   * add:     called when a new listener gets added (subscribing to the same
  65              event twice will only cause this callback to get called once)
  66   * del:     called when a listener stops listening
  67   * replace: replace event 'old' with event 'new'.
  68   * merge:   merge event 'old' into event 'new'.
  69   All 4 callbacks are optional, if you don't want to specify any callbacks
  70   the ops argument itself maybe NULL.
  71
  72 .. code-block:: none
  73
  74         int v4l2_event_unsubscribe(struct v4l2_fh *fh,
  75                                    struct v4l2_event_subscription *sub)
  76
  77   vidioc_unsubscribe_event in struct v4l2_ioctl_ops. A driver may use
  78   v4l2_event_unsubscribe() directly unless it wants to be involved in
  79   unsubscription process.
  80
  81   The special type V4L2_EVENT_ALL may be used to unsubscribe all events. The
  82   drivers may want to handle this in a special way.
  83
  84 .. code-block:: none
  85
  86         int v4l2_event_pending(struct v4l2_fh *fh)
  87
  88   Returns the number of pending events. Useful when implementing poll.
  89
  90 Events are delivered to user space through the poll system call. The driver
  91 can use v4l2_fh->wait (a wait_queue_head_t) as the argument for poll_wait().
  92
  93 There are standard and private events. New standard events must use the
  94 smallest available event type. The drivers must allocate their events from
  95 their own class starting from class base. Class base is
  96 V4L2_EVENT_PRIVATE_START + n * 1000 where n is the lowest available number.
  97 The first event type in the class is reserved for future use, so the first
  98 available event type is 'class base + 1'.
  99
 100 An example on how the V4L2 events may be used can be found in the OMAP
 101 3 ISP driver (drivers/media/platform/omap3isp).
 102
 103 A subdev can directly send an event to the v4l2_device notify function with
 104 V4L2_DEVICE_NOTIFY_EVENT. This allows the bridge to map the subdev that sends
 105 the event to the video node(s) associated with the subdev that need to be
 106 informed about such an event.
 107
 108 V4L2 event kAPI
 109 ^^^^^^^^^^^^^^^
 110
 111 .. kernel-doc:: include/media/v4l2-event.h