mirror of https://lore.kernel.org/lkml/
 help / color / mirror / Atom feed
From: Mattijs Korpershoek <mkorpershoek@kernel.org>
To: Hans Verkuil <hverkuil+cisco@kernel.org>,
	 Laurent Pinchart <laurent.pinchart@ideasonboard.com>,
	 Kieran Bingham <kieran.bingham@ideasonboard.com>,
	 Sakari Ailus <sakari.ailus@linux.intel.com>,
	 Mauro Carvalho Chehab <mchehab@kernel.org>,
	 Andy Walls <awalls@md.metrocast.net>,
	Kees Cook <kees@kernel.org>,
	 "Gustavo A. R. Silva" <gustavoars@kernel.org>
Cc: Mattijs Korpershoek <mkorpershoek@kernel.org>,
	 Nicolas Dufresne <nicolas.dufres@collabora.com>,
	 Hans de Goede <hansg@kernel.org>,
	 Michael Riesch <michael.riesch@collabora.com>,
	 Dave Stevenson <dave.stevenson@raspberrypi.com>,
	 Maxime Ripard <mripard@kernel.org>,
	linux-media@vger.kernel.org,  linux-kernel@vger.kernel.org,
	linux-hardening@vger.kernel.org
Subject: [PATCH RFC v2 09/16] Documentation: media: Add Media controller event documentation
Date: Wed, 18 Nov 2026 13:43:53 +0100	[thread overview]
Message-ID: <20261118-v4l2-sensor-detect-v2-9-1bb1a445b556@kernel.org> (raw)
In-Reply-To: <20261118-v4l2-sensor-detect-v2-0-1bb1a445b556@kernel.org>

From: Sakari Ailus <sakari.ailus@linux.intel.com>

Add documentation for the Media controller event IOCTLs as well as an
event, MEDIA_EVENT_ENTITY_REGISTRATION.

Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
---
 .../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


  parent reply	other threads:[~2026-11-18 12:44 UTC|newest]

Thread overview: 17+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-18 12:43 [PATCH RFC v2 00/16] media: Fault-Tolerant V4L2 Mattijs Korpershoek
2026-11-18 12:43 ` [PATCH RFC v2 01/16] media: mc: Add struct media_device_fh pointer to media device IOCTL op Mattijs Korpershoek
2026-11-18 12:43 ` [PATCH RFC v2 02/16] media: mc: Add per-file-handle data support Mattijs Korpershoek
2026-11-18 12:43 ` [PATCH RFC v2 03/16] v4l: event: Separate event related information from struct v4l2_fh Mattijs Korpershoek
2026-11-18 12:43 ` [PATCH RFC v2 04/16] v4l: event: Rework data structures for separating events and V4L2 Mattijs Korpershoek
2026-11-18 12:43 ` [PATCH RFC v2 05/16] v4l: event: Split the event framework into generic and V4L2 bits Mattijs Korpershoek
2026-11-18 12:43 ` [PATCH RFC v2 06/16] media: mc: Maintain a list of open file handles in a media device Mattijs Korpershoek
2026-11-18 12:43 ` [PATCH RFC v2 07/16] media: mc: Add MEDIA_IOC_DQEVENT Mattijs Korpershoek
2026-11-18 12:43 ` [PATCH RFC v2 08/16] media: mc: Add MEDIA_EVENT_ENTITY_REGISTRATION Mattijs Korpershoek
2026-11-18 12:43 ` Mattijs Korpershoek [this message]
2026-11-18 12:43 ` [PATCH RFC v2 10/16] media: media.h: Add entity connection status Mattijs Korpershoek
2026-11-18 12:43 ` [PATCH RFC v2 11/16] media: mc: Add .detect() to media_entity_operations Mattijs Korpershoek
2026-11-18 12:43 ` [PATCH RFC v2 12/16] media: mc: Add MEDIA_IOC_G_ENTITY_STATUS ioctl Mattijs Korpershoek
2026-11-18 12:43 ` [PATCH RFC v2 13/16] media: mc: Add MEDIA_EVENT_ENTITY_STATUS_CHANGE event Mattijs Korpershoek
2026-11-18 12:43 ` [PATCH RFC v2 14/16] media: mc: Add detect polling helpers for drivers Mattijs Korpershoek
2026-11-18 12:43 ` [PATCH RFC v2 15/16] media: imx219: Allow driver probe with missing sensor Mattijs Korpershoek
2026-11-18 12:44 ` [PATCH RFC v2 16/16] media: imx219: Implement .detect() sensor operation Mattijs Korpershoek

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20261118-v4l2-sensor-detect-v2-9-1bb1a445b556@kernel.org \
    --to=mkorpershoek@kernel.org \
    --cc=awalls@md.metrocast.net \
    --cc=dave.stevenson@raspberrypi.com \
    --cc=gustavoars@kernel.org \
    --cc=hansg@kernel.org \
    --cc=hverkuil+cisco@kernel.org \
    --cc=kees@kernel.org \
    --cc=kieran.bingham@ideasonboard.com \
    --cc=laurent.pinchart@ideasonboard.com \
    --cc=linux-hardening@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-media@vger.kernel.org \
    --cc=mchehab@kernel.org \
    --cc=michael.riesch@collabora.com \
    --cc=mripard@kernel.org \
    --cc=nicolas.dufres@collabora.com \
    --cc=sakari.ailus@linux.intel.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox

all inboxes | Powered by JetHome®