summaryrefslogtreecommitdiffstats
path: root/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-11 08:27:49 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-11 08:27:49 +0000
commitace9429bb58fd418f0c81d4c2835699bddf6bde6 (patch)
treeb2d64bc10158fdd5497876388cd68142ca374ed3 /Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst
parentInitial commit. (diff)
downloadlinux-ace9429bb58fd418f0c81d4c2835699bddf6bde6.tar.xz
linux-ace9429bb58fd418f0c81d4c2835699bddf6bde6.zip
Adding upstream version 6.6.15.upstream/6.6.15
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst')
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst113
1 files changed, 113 insertions, 0 deletions
diff --git a/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst b/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst
new file mode 100644
index 0000000000..a6fc3c5fe9
--- /dev/null
+++ b/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst
@@ -0,0 +1,113 @@
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
+
+.. _VIDIOC_SUBSCRIBE_EVENT:
+.. _VIDIOC_UNSUBSCRIBE_EVENT:
+
+******************************************************
+ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT
+******************************************************
+
+Name
+====
+
+VIDIOC_SUBSCRIBE_EVENT - VIDIOC_UNSUBSCRIBE_EVENT - Subscribe or unsubscribe event
+
+Synopsis
+========
+
+.. c:macro:: VIDIOC_SUBSCRIBE_EVENT
+
+``int ioctl(int fd, VIDIOC_SUBSCRIBE_EVENT, struct v4l2_event_subscription *argp)``
+
+.. c:macro:: VIDIOC_UNSUBSCRIBE_EVENT
+
+``int ioctl(int fd, VIDIOC_UNSUBSCRIBE_EVENT, struct v4l2_event_subscription *argp)``
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :c:func:`open()`.
+
+``argp``
+ Pointer to struct :c:type:`v4l2_event_subscription`.
+
+Description
+===========
+
+Subscribe or unsubscribe V4L2 event. Subscribed events are dequeued by
+using the :ref:`VIDIOC_DQEVENT` ioctl.
+
+.. tabularcolumns:: |p{2.6cm}|p{4.4cm}|p{10.3cm}|
+
+.. c:type:: v4l2_event_subscription
+
+.. flat-table:: struct v4l2_event_subscription
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - __u32
+ - ``type``
+ - Type of the event, see :ref:`event-type`.
+
+ .. note::
+
+ ``V4L2_EVENT_ALL`` can be used with
+ :ref:`VIDIOC_UNSUBSCRIBE_EVENT <VIDIOC_SUBSCRIBE_EVENT>` for
+ unsubscribing all events at once.
+ * - __u32
+ - ``id``
+ - ID of the event source. If there is no ID associated with the
+ event source, then set this to 0. Whether or not an event needs an
+ ID depends on the event type.
+ * - __u32
+ - ``flags``
+ - Event flags, see :ref:`event-flags`.
+ * - __u32
+ - ``reserved``\ [5]
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+.. tabularcolumns:: |p{7.5cm}|p{2.0cm}|p{7.8cm}|
+
+.. _event-flags:
+
+.. flat-table:: Event Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+ * - ``V4L2_EVENT_SUB_FL_SEND_INITIAL``
+ - 0x0001
+ - When this event is subscribed an initial event will be sent
+ containing the current status. This only makes sense for events
+ that are triggered by a status change such as ``V4L2_EVENT_CTRL``.
+ Other events will ignore this flag.
+ * - ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK``
+ - 0x0002
+ - If set, then events directly caused by an ioctl will also be sent
+ to the filehandle that called that ioctl. For example, changing a
+ control using :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` will cause
+ a V4L2_EVENT_CTRL to be sent back to that same filehandle.
+ Normally such events are suppressed to prevent feedback loops
+ where an application changes a control to a one value and then
+ another, and then receives an event telling it that that control
+ has changed to the first value.
+
+ Since it can't tell whether that event was caused by another
+ application or by the :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>`
+ call it is hard to decide whether to set the control to the value
+ in the event, or ignore it.
+
+ Think carefully when you set this flag so you won't get into
+ situations like that.
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.