diff options
author | Linus Torvalds <torvalds@linux-foundation.org> | 2016-07-27 21:58:31 (GMT) |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2016-07-27 21:58:31 (GMT) |
commit | ff9a082fda424257976f08fce942609f358015e0 (patch) | |
tree | 478e6b449b19baaf842369a13923499ce83ef895 /Documentation/media/kapi/v4l2-event.rst | |
parent | 6a492b0f23d28e1f946cdf08e54617484400dafb (diff) | |
parent | 85538b1ad145c67198cb55d02de14ba269cc323d (diff) | |
download | linux-ff9a082fda424257976f08fce942609f358015e0.tar.xz |
Merge tag 'media/v4.8-4' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media
Pull media documentation updates from Mauro Carvalho Chehab:
"This patch series does the conversion of all media documentation stuff
to Restrutured Text markup format and add them to the
Documentation/index.rst file.
The media documentation was grouped into 4 books:
- media uAPI
- media kAPI
- V4L driver-specific documentation
- DVB driver-specific documentation
It also contains several documentation improvements and one fixup
patch for a core issue with cropcap.
PS. After this patch series, the media DocBook is deprecated and
should be removed. I'll add such patch on a future pull request"
* tag 'media/v4.8-4' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (322 commits)
[media] cx23885-cardlist.rst: add a new card
[media] doc-rst: add some needed escape codes
[media] doc-rst: kapi: use :c:func: instead of :cpp:func
doc-rst: kernel-doc: fix a change introduced by mistake
[media] v4l2-ioctl.h add debug info for struct v4l2_ioctl_ops
[media] dvb_ringbuffer.h: some documentation improvements
[media] v4l2-ctrls.h: fully document the header file
[media] doc-rst: Fix some typedef ugly warnings
[media] doc-rst: reorganize the kAPI v4l2 chapters
[media] rename v4l2-framework.rst to v4l2-intro.rst
[media] move V4L2 clocks to a separate .rst file
[media] v4l2-fh.rst: add cross references and markups
[media] v4l2-fh.rst: add fh contents from v4l2-framework.rst
[media] v4l2-fh.h: add documentation for it
[media] v4l2-event.rst: add cross-references and markups
[media] v4l2-event.h: document all functions
[media] v4l2-event.rst: add text from v4l2-framework.rst
[media] v4l2-framework.rst: remove videobuf quick chapter
[media] v4l2-dev: add cross-references and improve markup
[media] doc-rst: move v4l2-dev doc to a separate file
...
Diffstat (limited to 'Documentation/media/kapi/v4l2-event.rst')
-rw-r--r-- | Documentation/media/kapi/v4l2-event.rst | 137 |
1 files changed, 137 insertions, 0 deletions
diff --git a/Documentation/media/kapi/v4l2-event.rst b/Documentation/media/kapi/v4l2-event.rst new file mode 100644 index 0000000..f962686 --- /dev/null +++ b/Documentation/media/kapi/v4l2-event.rst @@ -0,0 +1,137 @@ + +V4L2 events +----------- + +The V4L2 events provide a generic way to pass events to user space. +The driver must use :c:type:`v4l2_fh` to be able to support V4L2 events. + +Events are defined by a type and an optional ID. The ID may refer to a V4L2 +object such as a control ID. If unused, then the ID is 0. + +When the user subscribes to an event the driver will allocate a number of +kevent structs for that event. So every (type, ID) event tuple will have +its own set of kevent structs. This guarantees that if a driver is generating +lots of events of one type in a short time, then that will not overwrite +events of another type. + +But if you get more events of one type than the number of kevents that were +reserved, then the oldest event will be dropped and the new one added. + +Furthermore, the internal struct :c:type:`v4l2_subscribed_event` has +``merge()`` and ``replace()`` callbacks which drivers can set. These +callbacks are called when a new event is raised and there is no more room. +The ``replace()`` callback allows you to replace the payload of the old event +with that of the new event, merging any relevant data from the old payload +into the new payload that replaces it. It is called when this event type has +only one kevent struct allocated. The ``merge()`` callback allows you to merge +the oldest event payload into that of the second-oldest event payload. It is +called when there are two or more kevent structs allocated. + +This way no status information is lost, just the intermediate steps leading +up to that state. + +A good example of these ``replace``/``merge`` callbacks is in v4l2-event.c: +``ctrls_replace()`` and ``ctrls_merge()`` callbacks for the control event. + +.. note:: + these callbacks can be called from interrupt context, so they must + be fast. + +In order to queue events to video device, drivers should call: + + :c:func:`v4l2_event_queue <v4l2_event_queue>` + (:c:type:`vdev <video_device>`, :ref:`ev <v4l2-event>`) + +The driver's only responsibility is to fill in the type and the data fields. +The other fields will be filled in by V4L2. + +Event subscription +~~~~~~~~~~~~~~~~~~ + +Subscribing to an event is via: + + :c:func:`v4l2_event_subscribe <v4l2_event_subscribe>` + (:c:type:`fh <v4l2_fh>`, :ref:`sub <v4l2-event-subscription>` , + elems, :c:type:`ops <v4l2_subscribed_event_ops>`) + + +This function is used to implement :c:type:`video_device`-> +:c:type:`ioctl_ops <v4l2_ioctl_ops>`-> ``vidioc_subscribe_event``, +but the driver must check first if the driver is able to produce events +with specified event id, and then should call +:c:func:`v4l2_event_subscribe` to subscribe the event. + +The elems argument is the size of the event queue for this event. If it is 0, +then the framework will fill in a default value (this depends on the event +type). + +The ops argument allows the driver to specify a number of callbacks: + +======== ============================================================== +Callback Description +======== ============================================================== +add called when a new listener gets added (subscribing to the same + event twice will only cause this callback to get called once) +del called when a listener stops listening +replace replace event 'old' with event 'new'. +merge merge event 'old' into event 'new'. +======== ============================================================== + +All 4 callbacks are optional, if you don't want to specify any callbacks +the ops argument itself maybe ``NULL``. + +Unsubscribing an event +~~~~~~~~~~~~~~~~~~~~~~ + +Unsubscribing to an event is via: + + :c:func:`v4l2_event_unsubscribe <v4l2_event_unsubscribe>` + (:c:type:`fh <v4l2_fh>`, :ref:`sub <v4l2-event-subscription>`) + +This function is used to implement :c:type:`video_device`-> +:c:type:`ioctl_ops <v4l2_ioctl_ops>`-> ``vidioc_unsubscribe_event``. +A driver may call :c:func:`v4l2_event_unsubscribe` directly unless it +wants to be involved in unsubscription process. + +The special type ``V4L2_EVENT_ALL`` may be used to unsubscribe all events. The +drivers may want to handle this in a special way. + +Check if there's a pending event +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Checking if there's a pending event is via: + + :c:func:`v4l2_event_pending <v4l2_event_pending>` + (:c:type:`fh <v4l2_fh>`) + + +This function returns the number of pending events. Useful when implementing +poll. + +How events work +~~~~~~~~~~~~~~~ + +Events are delivered to user space through the poll system call. The driver +can use :c:type:`v4l2_fh`->wait (a wait_queue_head_t) as the argument for +``poll_wait()``. + +There are standard and private events. New standard events must use the +smallest available event type. The drivers must allocate their events from +their own class starting from class base. Class base is +``V4L2_EVENT_PRIVATE_START`` + n * 1000 where n is the lowest available number. +The first event type in the class is reserved for future use, so the first +available event type is 'class base + 1'. + +An example on how the V4L2 events may be used can be found in the OMAP +3 ISP driver (``drivers/media/platform/omap3isp``). + +A subdev can directly send an event to the :c:type:`v4l2_device` notify +function with ``V4L2_DEVICE_NOTIFY_EVENT``. This allows the bridge to map +the subdev that sends the event to the video node(s) associated with the +subdev that need to be informed about such an event. + +V4L2 event functions and data structures +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. kernel-doc:: include/media/v4l2-event.h + |