Documentation/media/uapi/v4l/dev-event.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _event:
   4
   5 ***************
   6 Event Interface
   7 ***************
   8
   9 The V4L2 event interface provides a means for a user to get immediately
  10 notified on certain conditions taking place on a device. This might
  11 include start of frame or loss of signal events, for example. Changes in
  12 the value or state of a V4L2 control can also be reported through
  13 events.
  14
  15 To receive events, the events the user is interested in first must be
  16 subscribed using the
  17 :ref:`VIDIOC_SUBSCRIBE_EVENT` ioctl. Once
  18 an event is subscribed, the events of subscribed types are dequeueable
  19 using the :ref:`VIDIOC_DQEVENT` ioctl. Events may be
  20 unsubscribed using VIDIOC_UNSUBSCRIBE_EVENT ioctl. The special event
  21 type V4L2_EVENT_ALL may be used to unsubscribe all the events the
  22 driver supports.
  23
  24 The event subscriptions and event queues are specific to file handles.
  25 Subscribing an event on one file handle does not affect other file
  26 handles.
  27
  28 The information on dequeueable events is obtained by using select or
  29 poll system calls on video devices. The V4L2 events use POLLPRI events
  30 on poll system call and exceptions on select system call.
  31
  32 Starting with kernel 3.1 certain guarantees can be given with regards to
  33 events:
  34
  35 1. Each subscribed event has its own internal dedicated event queue.
  36    This means that flooding of one event type will not interfere with
  37    other event types.
  38
  39 2. If the internal event queue for a particular subscribed event becomes
  40    full, then the oldest event in that queue will be dropped.
  41
  42 3. Where applicable, certain event types can ensure that the payload of
  43    the oldest event that is about to be dropped will be merged with the
  44    payload of the next oldest event. Thus ensuring that no information
  45    is lost, but only an intermediate step leading up to that
  46    information. See the documentation for the event you want to
  47    subscribe to whether this is applicable for that event or not.