[PATCH RFC v2 09/16] Documentation: media: Add Media controller event documentation
From: Mattijs Korpershoek
Date: Wed Nov 18 2026 - 07:45:07 EST
From: Sakari Ailus <sakari.ailus@xxxxxxxxxxxxxxx>
Add documentation for the Media controller event IOCTLs as well as an
event, MEDIA_EVENT_ENTITY_REGISTRATION.
Signed-off-by: Sakari Ailus <sakari.ailus@xxxxxxxxxxxxxxx>
---
.../userspace-api/media/mediactl/media-funcs.rst | 2 +
.../media/mediactl/media-ioc-dqevent.rst | 125 +++++++++++++++++++++
.../media/mediactl/media-ioc-subscribe-event.rst | 112 ++++++++++++++++++
3 files changed, 239 insertions(+)
diff --git a/Documentation/userspace-api/media/mediactl/media-funcs.rst b/Documentation/userspace-api/media/mediactl/media-funcs.rst
index e896296812c1..a9ce38b7144f 100644
--- a/Documentation/userspace-api/media/mediactl/media-funcs.rst
+++ b/Documentation/userspace-api/media/mediactl/media-funcs.rst
@@ -19,6 +19,8 @@ Function Reference
media-ioc-enum-links
media-ioc-setup-link
media-ioc-request-alloc
+ media-ioc-subscribe-event
+ media-ioc-dqevent
request-func-close
request-func-ioctl
request-func-poll
diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-dqevent.rst b/Documentation/userspace-api/media/mediactl/media-ioc-dqevent.rst
new file mode 100644
index 000000000000..f7a2cd2675f5
--- /dev/null
+++ b/Documentation/userspace-api/media/mediactl/media-ioc-dqevent.rst
@@ -0,0 +1,125 @@
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
+
+.. _media_ioc_dqevent:
+
+***********************
+ioctl MEDIA_IOC_DQEVENT
+***********************
+
+Name
+====
+
+MEDIA_IOC_DQEVENT - Dequeue a Media controller event
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, MEDIA_IOC_DQEVENT, struct media_event *argp )
+ :name: MEDIA_IOC_DQEVENT
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <media-func-open>`.
+
+``argp``
+ Pointer to struct :c:type:`media_event`.
+
+
+Description
+===========
+
+The MEDIA_IOC_DQEVENT IOCTL may be used to dequeue Media controller events from
+the file handle. The :ref:`MEDIA_IOC_SUBSCRIBE_EVENT` IOCTL can be used to
+subscribe the events.
+
+.. tabularcolumns:: |p{4.6cm}|p{4.4cm}|p{8.7cm}|
+
+.. c:type:: media_event
+
+.. flat-table:: struct media_event
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 2
+
+ * - __u32
+ - ``type``
+ -
+ - Type of the event, see :ref:`media-event-type`.
+ * - union
+ - ``u``
+ -
+ -
+ * -
+ - struct :c:type:`media_event_entity_reg`
+ - ``entity_reg``
+ - Event data for event ``MEDIA_EVENT_ENTITY_REGISTRATION``.
+ * -
+ - __u8
+ - ``data``\ [64]
+ - Event data. Defined by the event type. The union should be used to
+ define easily accessible type for events.
+ * - __u32
+ - ``reserved``\ [8]
+ -
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+ * - __u32
+ - ``pending``
+ -
+ - The number of pending events excluding this one.
+ * - __u32
+ - ``sequence``
+ -
+ - Event sequence number. The sequence number is incremented for
+ every subscribed event that takes place. If sequence numbers are
+ not contiguous it means that events have been lost.
+ * - __u64
+ - ``timestamp``
+ -
+ - Event timestamp. The timestamp has been taken from the
+ ``CLOCK_MONOTONIC`` clock.
+ * - __u32
+ - ``id``
+ -
+ - The ID associated with the event source. If the event does not
+ have an associated ID (this depends on the event type), then this
+ is 0.
+
+.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
+
+.. cssclass:: longtable
+
+.. _media-event-type:
+
+.. flat-table:: Media Event Types
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+ * - ``MEDIA_EVENT_ALL``
+ - 0
+ - All events. MEDIA_EVENT_ALL is valid only for
+ MEDIA_IOC_UNSUBSCRIBE_EVENT for unsubscribing all events at once.
+ * - ``MEDIA_EVENT_ENTITY_REGISTRATION``
+ - 1
+ - Triggered when a media entity is registered to a Media controller
+ device. The pending field designates the number of entities that are
+ known to be still missing. This number may be less than the total
+ number of all missing entities. However if this number is zero, then
+ all entities have been registered to the media device.
+
+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.
+
+ENOENT
+ The event queue is empty and the file descriptor is in non-blocking
+ mode.
diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-subscribe-event.rst b/Documentation/userspace-api/media/mediactl/media-ioc-subscribe-event.rst
new file mode 100644
index 000000000000..61e537b6ba6d
--- /dev/null
+++ b/Documentation/userspace-api/media/mediactl/media-ioc-subscribe-event.rst
@@ -0,0 +1,112 @@
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
+
+.. _media_ioc_subscribe_event:
+
+************************************************************
+ioctl MEDIA_IOC_SUBSCRIBE_EVENT, MEDIA_IOC_UNSUBSCRIBE_EVENT
+************************************************************
+
+Name
+====
+
+MEDIA_IOC_SUBSCRIBE_EVENT - MEDIA_IOC_UNSUBSCRIBE_EVENT - Subscribe or unsubscribe a Media controller event
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, MEDIA_IOC_SUBSCRIBE_EVENT, struct media_event_subscription *argp )
+ :name: MEDIA_IOC_SUBSCRIBE_EVENT
+
+.. c:function:: int ioctl( int fd, MEDIA_IOC_UNSUBSCRIBE_EVENT, struct media_event_subscription *argp )
+ :name: MEDIA_IOC_UNSUBSCRIBE_EVENT
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <media-func-open>`.
+
+``argp``
+ Pointer to struct :c:type:`media_event_subscription`.
+
+
+Description
+===========
+
+The MEDIA_IOC_SUBSCRIBE_EVENT IOCTL may be used to subscribe Media controller
+events to the file handle. The events are identified by their type and id, and
+the user may set the flags field to specify properties of the subscription. The
+subscriptions are specific to a file handle.
+
+The caller is responsible for setting the value of all fields in the argument
+struct by either initialising the fields of the entire struct to a known value
+or by setting the memory of the entire struct to zero and then filling the
+desired fields.
+
+The events may be dequeued using the :ref:`MEDIA_IOC_DQEVENT` IOCTL.
+
+The MEDIA_IOC_UNSUBSCRIBE_EVENT IOCTL is used to unsubscribe a subscribed
+event. A special value of ''MEDIA_EVENT_ALL'' may be used to unsubscribe all
+events on a file handle.
+
+.. tabularcolumns:: |p{4.6cm}|p{4.4cm}|p{8.7cm}|
+
+.. c:type:: media_event_subscription
+
+.. flat-table:: struct media_event_subscription
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - __u32
+ - ``type``
+ - Type of the event, see :ref:`media-event-type`.
+
+ .. note::
+
+ ``MEDIA_EVENT_ALL`` can be used with
+ :ref:`MEDIA_IOC_UNSUBSCRIBE_EVENT <MEDIA_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:`media-event-flags`.
+ * - __u32
+ - ``reserved``\ [5]
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+.. tabularcolumns:: |p{6.8cm}|p{2.2cm}|p{8.5cm}|
+
+.. _media-event-flags:
+
+.. flat-table:: Media event Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+ * - ``MEDIA_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.
+
+
+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.
+
+EINVAL
+ The struct :c:type:`media_event_subscription` specifies an event that may not
+ generated by the given Media device.
--
2.56.0