[PATCH v3 2/5] docs: media: add documentation for V4L2 driver usage metrics

[Detlev Casanova <detlev.casanova@collabora.com>]

From: Christopher Healy <healych@amazon.com>

Document the V4L2 fdinfo interface for per-file-descriptor usage
metrics exposed by V4L2 drivers via /proc/<pid>/fdinfo/<fd>.

The interface is defined generically for V4L2 drivers, with a set of
mandatory keys ("v4l2-driver", "v4l2-driver-type") that identify the
driver and its type, and per-driver-type sections describing
additional keys. This leaves room to extend the interface to other
driver types (stateful codecs, capture devices, ISPs, ...) later
without breaking existing users.

The initial per-type section targets stateless (request API based)
codec devices, both decoders and encoders. With stateless codecs the
kernel driver explicitly submits each frame to the hardware and
receives a completion interrupt, providing a clean per-job metrics
update.

The specification defines "v4l2-" prefixed keys for per-core engine
utilization time and operating frequency, following the same
conventions as the DRM fdinfo mechanism documented in
drm-usage-stats.rst.

"v4l2-core-usage-cycles-<core_id>" is added as an optional key for HW
cycle counters, when supported.

Also provide ABI documentation, currently as testing.

Signed-off-by: Christopher Healy <healych@amazon.com>
Signed-off-by: Detlev Casanova <detlev.casanova@collabora.com>
---
 Documentation/ABI/testing/procfs-fdinfo-v4l2       | 129 +++++++++++++++++++
 .../userspace-api/media/drivers/index.rst          |   1 +
 .../media/drivers/v4l2-usage-metrics.rst           | 137 +++++++++++++++++++++
 3 files changed, 267 insertions(+)

diff --git a/Documentation/ABI/testing/procfs-fdinfo-v4l2 b/Documentation/ABI/testing/procfs-fdinfo-v4l2
new file mode 100644
index 000000000000..7c64403b6814
--- /dev/null
+++ b/Documentation/ABI/testing/procfs-fdinfo-v4l2
@@ -0,0 +1,129 @@
+What:		/proc/<pid>/fdinfo/<fd> (V4L2 device file descriptors)
+Date:		July 2026
+Contact:	Detlev Casanova <detlev.casanova@collabora.com>
+		linux-media@vger.kernel.org
+Description:
+		Per-file-descriptor usage metrics for V4L2 devices, exposed
+		as a set of "key:\tvalue\n" lines in the fdinfo file
+		associated with an open /dev/video<N> file descriptor.
+
+		All standardised keys are prefixed with "v4l2-". Driver
+		specific keys are prefixed with "<driver_name>-".
+
+		Counter values are cumulative since the file descriptor was
+		created and strictly monotonically increasing.
+
+		See Documentation/userspace-api/media/drivers/v4l2-usage-metrics.rst
+		for the full specification.
+
+What:		/proc/<pid>/fdinfo/<fd>: v4l2-driver
+Date:		July 2026
+Contact:	Detlev Casanova <detlev.casanova@collabora.com>
+		linux-media@vger.kernel.org
+Description:
+		String. Name of the V4L2 driver backing this file descriptor.
+
+		Format:
+		  v4l2-driver:\t<name>\n
+
+		Mandatory for every driver that implements this interface.
+
+What:		/proc/<pid>/fdinfo/<fd>: v4l2-driver-type
+Date:		July 2026
+Contact:	Detlev Casanova <detlev.casanova@collabora.com>
+		linux-media@vger.kernel.org
+Description:
+		String. Type of V4L2 device exposed through this file
+		descriptor. Tells userspace which additional type-specific
+		keys to expect.
+
+		Format:
+		  v4l2-driver-type:\t<type>\n
+
+		Standard values currently defined:
+		  - "stateless-decoder"
+		  - "stateless-encoder"
+
+		Additional values will be defined as the interface is
+		extended to other driver types.
+
+		Mandatory for every driver that implements this interface.
+
+What:		/proc/<pid>/fdinfo/<fd>: v4l2-core-usage-time-<core_id>
+Date:		July 2026
+Contact:	Detlev Casanova <detlev.casanova@collabora.com>
+		linux-media@vger.kernel.org
+Description:
+		Unsigned integer, in nanoseconds. Time the hardware core
+		identified by <core_id> spent busy processing work belonging
+		to this file descriptor, cumulative since the file descriptor
+		was created.
+
+		<core_id> must be a non-negative decimal integer (0, 1, 2,
+		...). Strings or other non-numeric identifiers are not
+		allowed.
+
+		Format:
+		  v4l2-core-usage-time-<core_id>:\t<uint> ns\n
+
+		Time is measured by the driver, typically from just before
+		the hardware is started to just after the completion
+		interrupt is handled, so it is slightly less precise than a
+		hardware cycle counter but is always available.
+
+		Mandatory for stateless-decoder and stateless-encoder driver
+		types.
+
+What:		/proc/<pid>/fdinfo/<fd>: v4l2-core-usage-cycles-<core_id>
+Date:		July 2026
+Contact:	Detlev Casanova <detlev.casanova@collabora.com>
+		linux-media@vger.kernel.org
+Description:
+		Unsigned integer. Number of hardware clock cycles the core
+		identified by <core_id> spent busy processing work belonging
+		to this file descriptor, cumulative since the file descriptor
+		was created.
+
+		<core_id> must be a non-negative decimal integer.
+
+		Format:
+		  v4l2-core-usage-cycles-<core_id>:\t<uint>\n
+
+		More precise than v4l2-core-usage-time-<core_id>, but
+		requires the hardware to expose a cycle counter. When
+		available together with v4l2-maxfreq-<core_id> and
+		v4l2-curfreq-<core_id>, userspace can derive an accurate
+		utilization percentage. Otherwise, userspace should fall back
+		to v4l2-core-usage-time-<core_id>.
+
+		Optional.
+
+What:		/proc/<pid>/fdinfo/<fd>: v4l2-maxfreq-<core_id>
+Date:		July 2026
+Contact:	Detlev Casanova <detlev.casanova@collabora.com>
+		linux-media@vger.kernel.org
+Description:
+		Unsigned integer, in Hz. Maximum operating frequency of the
+		main clock of the core identified by <core_id>.
+
+		<core_id> must be a non-negative decimal integer.
+
+		Format:
+		  v4l2-maxfreq-<core_id>:\t<uint> Hz\n
+
+		A core may have several clocks associated with it, but only
+		the one that actually clocks the hardware processing engine
+		of the core (its "main clock") is reported.
+
+What:		/proc/<pid>/fdinfo/<fd>: v4l2-curfreq-<core_id>
+Date:		July 2026
+Contact:	Detlev Casanova <detlev.casanova@collabora.com>
+		linux-media@vger.kernel.org
+Description:
+		Unsigned integer, in Hz. Current operating frequency of the
+		main clock of the core identified by <core_id>.
+
+		<core_id> must be a non-negative decimal integer.
+
+		Format:
+		  v4l2-curfreq-<core_id>:\t<uint> Hz\n
diff --git a/Documentation/userspace-api/media/drivers/index.rst b/Documentation/userspace-api/media/drivers/index.rst
index 02967c9b18d6..0b82df83b2d0 100644
--- a/Documentation/userspace-api/media/drivers/index.rst
+++ b/Documentation/userspace-api/media/drivers/index.rst
@@ -34,6 +34,7 @@ For more details see the file COPYING in the source distribution of Linux.
 	imx-uapi
 	mali-c55
 	max2175
+	v4l2-usage-metrics
 	npcm-video
 	omap3isp-uapi
 	thp7312
diff --git a/Documentation/userspace-api/media/drivers/v4l2-usage-metrics.rst b/Documentation/userspace-api/media/drivers/v4l2-usage-metrics.rst
new file mode 100644
index 000000000000..c56b1d608cd4
--- /dev/null
+++ b/Documentation/userspace-api/media/drivers/v4l2-usage-metrics.rst
@@ -0,0 +1,137 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _v4l2-usage-metrics:
+
+==========================
+V4L2 client usage metrics
+==========================
+
+V4L2 drivers can optionally expose per-file-descriptor usage metrics via
+``/proc/<pid>/fdinfo/<fd>``. This is analogous to the DRM fdinfo mechanism
+documented in :ref:`drm-client-usage-stats`, but uses the ``v4l2-`` key
+prefix for V4L2 devices.
+
+The interface is generic to V4L2: any driver type (stateless or stateful
+codecs, capture devices, ISPs, converters, ...) may implement it and provide
+the metrics relevant to its hardware. This document defines a common set of
+mandatory keys that identify the driver and the kind of device, plus per
+driver-type sections describing additional keys.
+
+The initial set of type-specific keys documented here targets stateless
+(request API based) codec devices, both decoders and encoders. With
+stateless codecs, the kernel driver explicitly submits each frame to the
+hardware and receives a completion interrupt, providing a clean per-job
+boundary that can be attributed to the submitting file descriptor. Other
+device types (stateful codecs, capture devices, ISPs, ...) can be added
+later with their own set of type-specific keys.
+
+Implementation
+==============
+
+The V4L2 core provides the plumbing: drivers implement the ``show_fdinfo``
+callback in ``struct v4l2_file_operations``, and the core wires it into the
+kernel ``struct file_operations`` so that ``/proc/<pid>/fdinfo/<fd>`` output
+includes the driver-provided keys.
+
+File format specification
+=========================
+
+- File shall contain one key value pair per one line of text.
+- Colon character (``:``) must be used to delimit keys and values.
+- All standardised keys shall be prefixed with ``v4l2-``.
+- Driver-specific keys shall be prefixed with ``driver_name-``.
+
+All counter values reported through this interface are cumulative since the
+file descriptor was created, and are strictly monotonically increasing.
+
+Mandatory keys
+==============
+
+The following keys must be exposed by every driver that implements this
+interface, regardless of the device type.
+
+- v4l2-driver: <valstr>
+
+  String shall contain the name of the V4L2 driver.
+
+- v4l2-driver-type: <valstr>
+
+  String shall identify the type of V4L2 device exposed through this file
+  descriptor. This key tells userspace which additional type-specific keys
+  to expect. Standard values currently defined are ``stateless-decoder``
+  and ``stateless-encoder``. Additional values will be defined as this
+  interface is extended to other driver types.
+
+Stateless codec keys
+====================
+
+The keys described in this section apply to file descriptors whose
+``v4l2-driver-type`` is ``stateless-decoder`` or ``stateless-encoder``.
+
+A stateless codec may be composed of one or more independent hardware
+cores. Per-core metrics are reported using keys suffixed with a
+``<core_id>`` identifier, so a single file descriptor can report metrics
+for multiple cores.
+
+``<core_id>`` must be a non-negative decimal integer (e.g. ``0``, ``1``,
+``2``, ...). Strings or other non-numeric identifiers are not allowed, so
+that userspace can reliably parse and enumerate cores.
+
+Utilization keys
+----------------
+
+- v4l2-core-usage-time-<core_id>: <uint> ns
+
+  Mandatory.
+
+  Time in nanoseconds that the hardware core identified by ``<core_id>``
+  spent busy processing work belonging to this file descriptor, cumulative
+  since the file descriptor was created.
+
+  Time is measured by the driver, typically from just before the hardware
+  is started to just after the completion interrupt is handled, so it is
+  slightly less precise than a hardware cycle counter but is always
+  available.
+
+- v4l2-core-usage-cycles-<core_id>: <uint>
+
+  Optional.
+
+  Number of hardware clock cycles that the core identified by ``<core_id>``
+  spent busy processing work belonging to this file descriptor, cumulative
+  since the file descriptor was created.
+
+  This is more precise than ``v4l2-core-usage-time-<core_id>`` but requires
+  the hardware to expose a cycle counter. When available together with
+  ``v4l2-maxfreq-<core_id>`` and ``v4l2-curfreq-<core_id>``, userspace can
+  derive an accurate utilization percentage. Otherwise, userspace should
+  fall back to ``v4l2-core-usage-time-<core_id>``.
+
+Frequency keys
+--------------
+
+- v4l2-maxfreq-<core_id>: <uint> Hz
+
+  Maximum operating frequency of the main clock of the core identified by
+  ``<core_id>``.
+
+- v4l2-curfreq-<core_id>: <uint> Hz
+
+  Current operating frequency of the main clock of the core identified by
+  ``<core_id>``.
+
+A core may have several clocks associated with it, but only the one that
+actually clocks the hardware processing engine of the core (its "main
+clock") should be reported through these keys.
+
+Example output
+==============
+
+::
+
+  v4l2-driver:                  hantro-vpu
+  v4l2-driver-type:             stateless-decoder
+  v4l2-core-usage-time-0:       123456789 ns
+  v4l2-core-usage-cycles-0:     74000000
+  v4l2-maxfreq-0:               600000000 Hz
+  v4l2-curfreq-0:               600000000 Hz

-- 
2.54.0