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