[PATCH v2 0/5] media: Add fdinfo support for v4l2 drivers

[PATCH v2 0/5] media: Add fdinfo support for v4l2 drivers

[Detlev Casanova]

fdinfo is useful to poll information from the driver.
Unlike the ftrace interface, it lets userspace tools get a snapshot of
the state of the driver at their own pace, instead of getting events for
each driver status change.

This works better to get information like HW usage time or clock
frequencies, as well as memory usage.
This patch set focuses on mem2mem drivers that are per-frame based and
an implementation is proposed for the Verisilicon Hantro and Rockchip
rkvdec drivers, limited to main clock frequency and HW usage time.

To ease support in drivers, a v4l2_stats struct is added.
It stores statistics information and provides helper functions to write
the fdinfo file in a standard way.

An example of usage of this from userspace is implemented in v4l2top:

https://github.com/cazou/v4l2top (Check the upstream branch)

checkpatch.pl warning: The 2 arguments in the show_fdinfo callback
definition are kept unnamed to match with the rest of the struct
definition.

Signed-off-by: Detlev Casanova <detlev.casanova@collabora.com>
---
Changes in v2:
- Simplify key/value pairs by removing repeated <eng> suffix
- Add media type support
- Add v4l2_stats helpers
- Add support in rkvdec too
- Link to v1: https://patch.msgid.link/20260612-v4l2-add-fdinfo-v1-0-723211abc861@collabora.com

To: Mauro Carvalho Chehab <mchehab@kernel.org>
To: Nicolas Dufresne <nicolas.dufresne@collabora.com>
To: Benjamin Gaignard <benjamin.gaignard@collabora.com>
To: Philipp Zabel <p.zabel@pengutronix.de>
To: Detlev Casanova <detlev.casanova@collabora.com>
To: Ezequiel Garcia <ezequiel@vanguardiasur.com.ar>
To: Heiko Stuebner <heiko@sntech.de>
Cc: kernel@collabora.com
Cc: linux-media@vger.kernel.org
Cc: linux-kernel@vger.kernel.org
Cc: linux-rockchip@lists.infradead.org
Cc: linux-arm-kernel@lists.infradead.org

---
Christopher Healy (2):
      docs: media: add documentation for media client usage stats
      media: hantro: add per-context fdinfo usage stats

Detlev Casanova (3):
      media: v4l2: Add callback for show_fdinfo
      media: v4l2-core: Add v4l2-stats interface
      media: rkvdec: Add per-context fdinfo usage stats

 .../userspace-api/media/drivers/index.rst          |  1 +
 .../media/drivers/media-usage-stats.rst            | 85 ++++++++++++++++++++++
 drivers/media/platform/rockchip/rkvdec/rkvdec.c    | 19 +++++
 drivers/media/platform/rockchip/rkvdec/rkvdec.h    |  1 +
 drivers/media/platform/verisilicon/hantro.h        |  3 +
 drivers/media/platform/verisilicon/hantro_drv.c    | 19 +++++
 drivers/media/v4l2-core/Makefile                   |  2 +-
 drivers/media/v4l2-core/v4l2-dev.c                 | 12 +++
 drivers/media/v4l2-core/v4l2-fh.c                  |  3 +
 drivers/media/v4l2-core/v4l2-stats.c               | 65 +++++++++++++++++
 include/media/v4l2-dev.h                           |  1 +
 include/media/v4l2-fh.h                            |  2 +
 include/media/v4l2-stats.h                         | 44 +++++++++++
 13 files changed, 256 insertions(+), 1 deletion(-)
---
base-commit: 66affa37cfac0aec061cc4bcf4a065b0c52f7e19
change-id: 20260610-v4l2-add-fdinfo-a790fceab329

Best regards,
--  
Detlev Casanova <detlev.casanova@collabora.com>

[PATCH v2 1/5] media: v4l2: Add callback for show_fdinfo

[Detlev Casanova]

Allow v4l2 drivers to add information in the fdinfo file matching the
opened /dev/videoX file.

Signed-off-by: Detlev Casanova <detlev.casanova@collabora.com>
---
 drivers/media/v4l2-core/v4l2-dev.c | 10 ++++++++++
 include/media/v4l2-dev.h           |  1 +
 2 files changed, 11 insertions(+)

diff --git a/drivers/media/v4l2-core/v4l2-dev.c b/drivers/media/v4l2-core/v4l2-dev.c
index 6ce623a1245a..3878fa2ff73e 100644
--- a/drivers/media/v4l2-core/v4l2-dev.c
+++ b/drivers/media/v4l2-core/v4l2-dev.c
@@ -481,6 +481,15 @@ static int v4l2_release(struct inode *inode, struct file *filp)
 	return ret;
 }
 
+/* Override for the show_fdinfo function */
+static void v4l2_show_fdinfo(struct seq_file *m, struct file *filp)
+{
+	struct video_device *vdev = video_devdata(filp);
+
+	if (vdev->fops->show_fdinfo)
+		vdev->fops->show_fdinfo(m, filp);
+}
+
 static const struct file_operations v4l2_fops = {
 	.owner = THIS_MODULE,
 	.read = v4l2_read,
@@ -494,6 +503,7 @@ static const struct file_operations v4l2_fops = {
 #endif
 	.release = v4l2_release,
 	.poll = v4l2_poll,
+	.show_fdinfo = v4l2_show_fdinfo,
 };
 
 /**
diff --git a/include/media/v4l2-dev.h b/include/media/v4l2-dev.h
index 2e0f6d2e6a78..1635ab186f21 100644
--- a/include/media/v4l2-dev.h
+++ b/include/media/v4l2-dev.h
@@ -212,6 +212,7 @@ struct v4l2_file_operations {
 	int (*mmap) (struct file *, struct vm_area_struct *);
 	int (*open) (struct file *);
 	int (*release) (struct file *);
+	void (*show_fdinfo)(struct seq_file *, struct file *);
 };
 
 /*

-- 
2.54.0

[PATCH v2 2/5] docs: media: add documentation for media client usage stats

[Detlev Casanova]

From: Christopher Healy <healych@amazon.com>

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

This interface is designed for stateless (request API based) codec
devices where the kernel driver has per-job visibility into hardware
execution. Stateful codecs cannot support all of this because their
firmware manages job scheduling opaquely.

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

More fields can be added later.

Signed-off-by: Christopher Healy <healych@amazon.com>
Signed-off-by: Detlev Casanova <detlev.casanova@collabora.com>
---
 .../userspace-api/media/drivers/index.rst          |  1 +
 .../media/drivers/media-usage-stats.rst            | 85 ++++++++++++++++++++++
 2 files changed, 86 insertions(+)

diff --git a/Documentation/userspace-api/media/drivers/index.rst b/Documentation/userspace-api/media/drivers/index.rst
index 02967c9b18d6..61879738836c 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
+	media-usage-stats
 	npcm-video
 	omap3isp-uapi
 	thp7312
diff --git a/Documentation/userspace-api/media/drivers/media-usage-stats.rst b/Documentation/userspace-api/media/drivers/media-usage-stats.rst
new file mode 100644
index 000000000000..d3dc07002f62
--- /dev/null
+++ b/Documentation/userspace-api/media/drivers/media-usage-stats.rst
@@ -0,0 +1,85 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _media-usage-stats:
+
+==========================
+Media client usage stats
+==========================
+
+Stateless V4L2 codec drivers can optionally expose per-file-descriptor usage
+statistics via ``/proc/<pid>/fdinfo/<fd>``. This is analogous to the DRM fdinfo
+mechanism documented in :ref:`drm-client-usage-stats`, but uses the ``media-``
+key prefix for V4L2 media devices.
+
+This interface is specific to stateless (request API based) codec devices,
+including 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.
+
+Stateful codec devices cannot support this interface because their firmware
+manages job scheduling internally. The kernel driver submits bitstream data
+but has no visibility into per-frame hardware execution timing.
+
+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 ``media-``.
+- Driver-specific keys shall be prefixed with ``driver_name-``.
+
+Mandatory keys
+--------------
+
+- media-driver: <valstr>
+
+  String shall contain the name of the media driver.
+
+- media-type: <valstr>
+
+  String shall identify the type of media engine exposed through this file
+  descriptor. Standard values are ``decoder`` and ``encoder``.
+
+Utilization keys
+----------------
+
+- media-engine-usage: <uint> ns
+
+  Time in nanoseconds that the hardware engine spent busy processing work
+  belonging to this file descriptor. The engine being measured is identified
+  by the ``media-type`` key.
+
+  Values are not required to be constantly monotonic if it makes the driver
+  implementation easier, but are required to catch up with the previously
+  reported larger value within a reasonable period.
+
+Frequency keys
+--------------
+
+- media-maxfreq: <uint> Hz
+
+  Maximum operating frequency of the main engine clock.
+
+- media-curfreq: <uint> Hz
+
+  Current operating frequency of the main engine clock.
+
+Example output
+==============
+
+::
+
+  media-driver:           hantro-vpu
+  media-type:             decoder
+  media-engine-usage:     123456789 ns
+  media-maxfreq:          600000000 Hz
+  media-curfreq:          600000000 Hz

-- 
2.54.0

[PATCH v2 3/5] media: v4l2-core: Add v4l2-stats interface

[Detlev Casanova]

Provide helpers for media drivers to set fdinfo data and print the
key:value pairs in a standard way.

User drivers can set stats values with helpers like:
 - v4l2_stats_update_hw_usage
 - v4l2_stats_set_media_dev_type

And also call the show helpers from their show_fdinfo callback with:
 - v4l2_stats_show -- Shows the values set previously
 - v4l2_stats_show_clock -- Shows the main clock state.

The show_clock helper is used instead of updating a clock value in
v4l2_stats for the following reasons:
 - Clocks are at the device level, this is not a per-fd information
 - This avoids having clock references in v4l2-core
 - Drivers can use different approaches to manage clocks
   (e.g.: bulk_data or not: A set helper wouldn't please all drivers)
 - Arguably, clocks could be exposed elsewhere (like a debugfs), but we
   want something close to what DRM does and centralizing information has
   its advantages for userspace tooling.

In DRM the key:value pair format for clocks is documented and each driver
can write them directly based on that.
In this case, provide a helper and document the format.

Signed-off-by: Detlev Casanova <detlev.casanova@collabora.com>
---
 drivers/media/v4l2-core/Makefile     |  2 +-
 drivers/media/v4l2-core/v4l2-dev.c   |  2 ++
 drivers/media/v4l2-core/v4l2-fh.c    |  3 ++
 drivers/media/v4l2-core/v4l2-stats.c | 65 ++++++++++++++++++++++++++++++++++++
 include/media/v4l2-fh.h              |  2 ++
 include/media/v4l2-stats.h           | 44 ++++++++++++++++++++++++
 6 files changed, 117 insertions(+), 1 deletion(-)

diff --git a/drivers/media/v4l2-core/Makefile b/drivers/media/v4l2-core/Makefile
index 329f0eadce99..20e1ab74ac09 100644
--- a/drivers/media/v4l2-core/Makefile
+++ b/drivers/media/v4l2-core/Makefile
@@ -9,7 +9,7 @@ ccflags-y += -I$(srctree)/drivers/media/tuners
 tuner-objs	:=	tuner-core.o
 
 videodev-objs	:=	v4l2-dev.o v4l2-ioctl.o v4l2-device.o v4l2-fh.o \
-			v4l2-event.o v4l2-subdev.o v4l2-common.o \
+			v4l2-event.o v4l2-subdev.o v4l2-common.o v4l2-stats.o \
 			v4l2-ctrls-core.o v4l2-ctrls-api.o \
 			v4l2-ctrls-request.o v4l2-ctrls-defs.o
 
diff --git a/drivers/media/v4l2-core/v4l2-dev.c b/drivers/media/v4l2-core/v4l2-dev.c
index 3878fa2ff73e..3e7a6876dffd 100644
--- a/drivers/media/v4l2-core/v4l2-dev.c
+++ b/drivers/media/v4l2-core/v4l2-dev.c
@@ -486,6 +486,8 @@ static void v4l2_show_fdinfo(struct seq_file *m, struct file *filp)
 {
 	struct video_device *vdev = video_devdata(filp);
 
+	seq_printf(m, "media-driver:\t%s\n", vdev->v4l2_dev->name);
+
 	if (vdev->fops->show_fdinfo)
 		vdev->fops->show_fdinfo(m, filp);
 }
diff --git a/drivers/media/v4l2-core/v4l2-fh.c b/drivers/media/v4l2-core/v4l2-fh.c
index b184bed8aca9..1b655672c718 100644
--- a/drivers/media/v4l2-core/v4l2-fh.c
+++ b/drivers/media/v4l2-core/v4l2-fh.c
@@ -17,6 +17,7 @@
 #include <media/v4l2-event.h>
 #include <media/v4l2-ioctl.h>
 #include <media/v4l2-mc.h>
+#include <media/v4l2-stats.h>
 
 void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev)
 {
@@ -38,6 +39,7 @@ void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev)
 	INIT_LIST_HEAD(&fh->subscribed);
 	fh->sequence = -1;
 	mutex_init(&fh->subscribe_lock);
+	v4l2_stats_init(&fh->stats);
 }
 EXPORT_SYMBOL_GPL(v4l2_fh_init);
 
@@ -88,6 +90,7 @@ void v4l2_fh_exit(struct v4l2_fh *fh)
 	v4l2_event_unsubscribe_all(fh);
 	mutex_destroy(&fh->subscribe_lock);
 	fh->vdev = NULL;
+	v4l2_stats_exit(&fh->stats);
 }
 EXPORT_SYMBOL_GPL(v4l2_fh_exit);
 
diff --git a/drivers/media/v4l2-core/v4l2-stats.c b/drivers/media/v4l2-core/v4l2-stats.c
new file mode 100644
index 000000000000..93e64ef2e7bb
--- /dev/null
+++ b/drivers/media/v4l2-core/v4l2-stats.c
@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: GPL-2.0-only
+/*
+ * v4l2-stats.c
+ *
+ * V4L2 statistics management.
+ *
+ * Maintain a per-file handle list of statistics about the hardware and handle
+ * exposing it in the fdinfo.
+ *
+ * Copyright (C) 2026 Collabora.
+ *
+ * Contact: Detlev Casanova <detlev.casanova@collabora.com>
+ */
+
+#include <linux/types.h>
+#include <linux/seq_file.h>
+#include <linux/clk.h>
+#include <media/v4l2-stats.h>
+
+static const char * const dev_type_name[] = {
+	[MEDIA_DEV_TYPE_V4L2] = "media",
+	[MEDIA_DEV_TYPE_V4L2_STATELESS_ENCODER] = "encoder",
+	[MEDIA_DEV_TYPE_V4L2_STATELESS_DECODER] = "decoder",
+};
+
+void v4l2_stats_init(struct v4l2_stats *stats)
+{
+	stats->hw_usage_time = 0;
+	stats->media_dev_type = MEDIA_DEV_TYPE_V4L2;
+}
+
+void v4l2_stats_exit(struct v4l2_stats *stats)
+{
+}
+
+void v4l2_stats_update_hw_usage(struct v4l2_stats *stats, u64 usage_time)
+{
+	stats->hw_usage_time += usage_time;
+}
+EXPORT_SYMBOL_GPL(v4l2_stats_update_hw_usage);
+
+void v4l2_stats_set_media_dev_type(struct v4l2_stats *stats, enum v4l2_media_dev_type type)
+{
+	if (type >= MEDIA_DEV_TYPE_COUNT)
+		return;
+
+	stats->media_dev_type = type;
+}
+EXPORT_SYMBOL_GPL(v4l2_stats_set_media_dev_type);
+
+void v4l2_stats_show(struct v4l2_stats *stats, struct seq_file *m)
+{
+	seq_printf(m, "media-type:\t%s\n", dev_type_name[stats->media_dev_type]);
+	seq_printf(m, "media-engine-usage:\t%llu ns\n", stats->hw_usage_time);
+}
+EXPORT_SYMBOL_GPL(v4l2_stats_show);
+
+void v4l2_stats_show_clock(struct seq_file *m, struct clk *clk)
+{
+	seq_printf(m, "media-maxfreq:\t%lu Hz\n",
+		   clk_get_rate(clk));
+	seq_printf(m, "media-curfreq:\t%lu Hz\n",
+		   clk_get_rate(clk));
+}
+EXPORT_SYMBOL_GPL(v4l2_stats_show_clock);
diff --git a/include/media/v4l2-fh.h b/include/media/v4l2-fh.h
index aad4b3689d7e..ae6688722bee 100644
--- a/include/media/v4l2-fh.h
+++ b/include/media/v4l2-fh.h
@@ -17,6 +17,7 @@
 #include <linux/kconfig.h>
 #include <linux/list.h>
 #include <linux/videodev2.h>
+#include <media/v4l2-stats.h>
 
 struct video_device;
 struct v4l2_ctrl_handler;
@@ -43,6 +44,7 @@ struct v4l2_fh {
 	struct list_head	list;
 	struct video_device	*vdev;
 	struct v4l2_ctrl_handler *ctrl_handler;
+	struct v4l2_stats	stats;
 	enum v4l2_priority	prio;
 
 	/* Events */
diff --git a/include/media/v4l2-stats.h b/include/media/v4l2-stats.h
new file mode 100644
index 000000000000..d580933c4181
--- /dev/null
+++ b/include/media/v4l2-stats.h
@@ -0,0 +1,44 @@
+/* SPDX-License-Identifier: GPL-2.0-only */
+/*
+ * v4l2-stats.h
+ *
+ * V4L2 statistics management.
+ *
+ * Maintain a per-file handle list of statistics about the hardware and handle
+ * exposing it in the fdinfo.
+ *
+ * Copyright (C) 2026 Collabora.
+ *
+ * Contact: Detlev Casanova <detlev.casanova@collabora.com>
+ */
+#ifndef V4L2_STATS_H
+#define V4L2_STATS_H
+
+#include <linux/types.h>
+
+struct clk;
+struct seq_file;
+
+enum v4l2_media_dev_type {
+	MEDIA_DEV_TYPE_V4L2 = 0,
+	MEDIA_DEV_TYPE_V4L2_STATELESS_ENCODER,
+	MEDIA_DEV_TYPE_V4L2_STATELESS_DECODER,
+
+	MEDIA_DEV_TYPE_COUNT,
+};
+
+struct v4l2_stats {
+	u64 hw_usage_time;
+	enum v4l2_media_dev_type media_dev_type;
+};
+
+void v4l2_stats_init(struct v4l2_stats *stats);
+void v4l2_stats_exit(struct v4l2_stats *stats);
+
+void v4l2_stats_update_hw_usage(struct v4l2_stats *stats, u64 usage_time);
+void v4l2_stats_set_media_dev_type(struct v4l2_stats *stats, enum v4l2_media_dev_type type);
+
+void v4l2_stats_show(struct v4l2_stats *stats, struct seq_file *m);
+void v4l2_stats_show_clock(struct seq_file *m, struct clk *clk);
+
+#endif /* V4L2_STATS_H */

-- 
2.54.0

[PATCH v2 4/5] media: hantro: add per-context fdinfo usage stats

[Detlev Casanova]

From: Christopher Healy <healych@amazon.com>

Add per-file-descriptor hardware utilization tracking to the Hantro
VPU stateless codec driver, exposed via v4l2_stats.

Update the v4l2_stats instance each time a job completes with the
time it took in ns.

This enables userspace monitoring tools to compute per-process decoder
and encoder utilization. The current and max frequency keys report the
same value today since the driver lacks devfreq support, but will
diverge once DVFS is added, allowing userspace to approximate true
capacity utilization without any fdinfo code changes. A future series
can add hardware cycle counter support (via media-cycles) to v4l2_stats
for exact utilization under DVFS, with no changes to the existing uAPI.

Signed-off-by: Christopher Healy <healych@amazon.com>
Signed-off-by: Detlev Casanova <detlev.casanova@collabora.com>
---
 drivers/media/platform/verisilicon/hantro.h     |  3 +++
 drivers/media/platform/verisilicon/hantro_drv.c | 19 +++++++++++++++++++
 2 files changed, 22 insertions(+)

diff --git a/drivers/media/platform/verisilicon/hantro.h b/drivers/media/platform/verisilicon/hantro.h
index 0353de154a1e..37fd13cc7afa 100644
--- a/drivers/media/platform/verisilicon/hantro.h
+++ b/drivers/media/platform/verisilicon/hantro.h
@@ -16,6 +16,7 @@
 #include <linux/videodev2.h>
 #include <linux/wait.h>
 #include <linux/clk.h>
+#include <linux/ktime.h>
 #include <linux/reset.h>
 
 #include <media/v4l2-ctrls.h>
@@ -268,6 +269,8 @@ struct hantro_ctx {
 	struct hantro_postproc_ctx postproc;
 	bool need_postproc;
 
+	ktime_t start_time;
+
 	/* Specific for particular codec modes. */
 	union {
 		struct hantro_h264_dec_hw_ctx h264_dec;
diff --git a/drivers/media/platform/verisilicon/hantro_drv.c b/drivers/media/platform/verisilicon/hantro_drv.c
index 2e81877f640f..3b837ef0f3bc 100644
--- a/drivers/media/platform/verisilicon/hantro_drv.c
+++ b/drivers/media/platform/verisilicon/hantro_drv.c
@@ -21,6 +21,7 @@
 #include <linux/videodev2.h>
 #include <linux/workqueue.h>
 #include <media/v4l2-event.h>
+#include <media/v4l2-stats.h>
 #include <media/v4l2-mem2mem.h>
 #include <media/videobuf2-core.h>
 #include <media/videobuf2-vmalloc.h>
@@ -90,6 +91,9 @@ static void hantro_job_finish(struct hantro_dev *vpu,
 			      struct hantro_ctx *ctx,
 			      enum vb2_buffer_state result)
 {
+	v4l2_stats_update_hw_usage(&ctx->fh.stats,
+				   ktime_to_ns(ktime_sub(ktime_get(), ctx->start_time)));
+
 	pm_runtime_put_autosuspend(vpu->dev);
 
 	clk_bulk_disable(vpu->variant->num_clocks, vpu->clocks);
@@ -186,6 +190,8 @@ static void device_run(void *priv)
 
 	v4l2_m2m_buf_copy_metadata(src, dst);
 
+	ctx->start_time = ktime_get();
+
 	if (ctx->codec_ops->run(ctx))
 		goto err_cancel_job;
 
@@ -664,6 +670,9 @@ static int hantro_open(struct file *filp)
 
 	v4l2_fh_init(&ctx->fh, vdev);
 	v4l2_fh_add(&ctx->fh, filp);
+	v4l2_stats_set_media_dev_type(&ctx->fh.stats,
+				      ctx->is_encoder ? MEDIA_DEV_TYPE_V4L2_STATELESS_ENCODER
+						      : MEDIA_DEV_TYPE_V4L2_STATELESS_DECODER);
 
 	hantro_reset_fmts(ctx);
 
@@ -701,10 +710,20 @@ static int hantro_release(struct file *filp)
 	return 0;
 }
 
+static void hantro_show_fdinfo(struct seq_file *m, struct file *f)
+{
+	struct hantro_ctx *ctx = file_to_ctx(f);
+	struct hantro_dev *vpu = ctx->dev;
+
+	v4l2_stats_show(&ctx->fh.stats, m);
+	v4l2_stats_show_clock(m, vpu->clocks[0].clk);
+}
+
 static const struct v4l2_file_operations hantro_fops = {
 	.owner = THIS_MODULE,
 	.open = hantro_open,
 	.release = hantro_release,
+	.show_fdinfo = hantro_show_fdinfo,
 	.poll = v4l2_m2m_fop_poll,
 	.unlocked_ioctl = video_ioctl2,
 	.mmap = v4l2_m2m_fop_mmap,

-- 
2.54.0

[PATCH v2 5/5] media: rkvdec: Add per-context fdinfo usage stats

[Detlev Casanova]

Add per-file-descriptor hardware utilization tracking to the rkvdec
stateless codec driver, exposed via v4l2_stats.

Update the v4l2_stats instance each time a job completes with the
time it took in ns.

This enables userspace monitoring tools to compute per-process decoder
and encoder utilization. The current and max frequency keys report the
same value today since the driver lacks devfreq support, but will
diverge once DVFS is added, allowing userspace to approximate true
capacity utilization without any fdinfo code changes. A future series
can add hardware cycle counter support (via media-cycles) to v4l2_stats
for exact utilization under DVFS, with no changes to the existing uAPI.

Signed-off-by: Detlev Casanova <detlev.casanova@collabora.com>
---
 drivers/media/platform/rockchip/rkvdec/rkvdec.c | 19 +++++++++++++++++++
 drivers/media/platform/rockchip/rkvdec/rkvdec.h |  1 +
 2 files changed, 20 insertions(+)

diff --git a/drivers/media/platform/rockchip/rkvdec/rkvdec.c b/drivers/media/platform/rockchip/rkvdec/rkvdec.c
index 1d1e9bfef8e9..929171232ccf 100644
--- a/drivers/media/platform/rockchip/rkvdec/rkvdec.c
+++ b/drivers/media/platform/rockchip/rkvdec/rkvdec.c
@@ -25,6 +25,7 @@
 #include <linux/workqueue.h>
 #include <media/v4l2-event.h>
 #include <media/v4l2-mem2mem.h>
+#include <media/v4l2-stats.h>
 #include <media/videobuf2-core.h>
 #include <media/videobuf2-vmalloc.h>
 
@@ -1094,6 +1095,9 @@ static void rkvdec_job_finish(struct rkvdec_ctx *ctx,
 {
 	struct rkvdec_dev *rkvdec = ctx->dev;
 
+	v4l2_stats_update_hw_usage(&ctx->fh.stats,
+				   ktime_to_ns(ktime_sub(ktime_get(), ctx->start_time)));
+
 	pm_runtime_put_autosuspend(rkvdec->dev);
 	rkvdec_job_finish_no_pm(ctx, result);
 }
@@ -1174,6 +1178,8 @@ static void rkvdec_device_run(void *priv)
 		return;
 	}
 
+	ctx->start_time = ktime_get();
+
 	ret = desc->ops->run(ctx);
 	if (ret)
 		rkvdec_job_finish(ctx, VB2_BUF_STATE_ERROR);
@@ -1304,6 +1310,8 @@ static int rkvdec_open(struct file *filp)
 
 	v4l2_fh_add(&ctx->fh, filp);
 
+	v4l2_stats_set_media_dev_type(&ctx->fh.stats, MEDIA_DEV_TYPE_V4L2_STATELESS_DECODER);
+
 	return 0;
 
 err_cleanup_m2m_ctx:
@@ -1327,10 +1335,21 @@ static int rkvdec_release(struct file *filp)
 	return 0;
 }
 
+static void rkvdec_show_fdinfo(struct seq_file *m, struct file *file)
+{
+	struct rkvdec_ctx *ctx = file_to_rkvdec_ctx(file);
+	struct rkvdec_dev *rkvdec = ctx->dev;
+
+	v4l2_stats_show(&ctx->fh.stats, m);
+
+	v4l2_stats_show_clock(m, rkvdec->axi_clk);
+}
+
 static const struct v4l2_file_operations rkvdec_fops = {
 	.owner = THIS_MODULE,
 	.open = rkvdec_open,
 	.release = rkvdec_release,
+	.show_fdinfo = rkvdec_show_fdinfo,
 	.poll = v4l2_m2m_fop_poll,
 	.unlocked_ioctl = video_ioctl2,
 	.mmap = v4l2_m2m_fop_mmap,
diff --git a/drivers/media/platform/rockchip/rkvdec/rkvdec.h b/drivers/media/platform/rockchip/rkvdec/rkvdec.h
index a24be6638b6b..590e213bd800 100644
--- a/drivers/media/platform/rockchip/rkvdec/rkvdec.h
+++ b/drivers/media/platform/rockchip/rkvdec/rkvdec.h
@@ -157,6 +157,7 @@ struct rkvdec_ctx {
 	void *priv;
 	u8 has_sps_st_rps: 1;
 	u8 has_sps_lt_rps: 1;
+	ktime_t start_time;
 };
 
 static inline struct rkvdec_ctx *file_to_rkvdec_ctx(struct file *filp)

-- 
2.54.0

Re: [PATCH v2 2/5] docs: media: add documentation for media client usage stats

[Hans Verkuil]

Hi Detlev,

Interesting, I had never heard of fdinfo, so if nothing else, I learned something new!

On 17/06/2026 20:10, Detlev Casanova wrote:
> From: Christopher Healy <healych@amazon.com>
> 
> Document the media fdinfo interface for per-file-descriptor usage
> statistics exposed by stateless V4L2 codec drivers via
> /proc/<pid>/fdinfo/<fd>.
> 
> This interface is designed for stateless (request API based) codec
> devices where the kernel driver has per-job visibility into hardware
> execution. Stateful codecs cannot support all of this because their
> firmware manages job scheduling opaquely.
> 
> The specification defines media- prefixed keys for engine utilization
> time, and operating frequency, following the same conventions as the DRM
> fdinfo mechanism documented in drm-usage-stats.rst.
> 
> More fields can be added later.
> 
> Signed-off-by: Christopher Healy <healych@amazon.com>
> Signed-off-by: Detlev Casanova <detlev.casanova@collabora.com>
> ---
>  .../userspace-api/media/drivers/index.rst          |  1 +
>  .../media/drivers/media-usage-stats.rst            | 85 ++++++++++++++++++++++
>  2 files changed, 86 insertions(+)
> 
> diff --git a/Documentation/userspace-api/media/drivers/index.rst b/Documentation/userspace-api/media/drivers/index.rst
> index 02967c9b18d6..61879738836c 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
> +	media-usage-stats
>  	npcm-video
>  	omap3isp-uapi
>  	thp7312
> diff --git a/Documentation/userspace-api/media/drivers/media-usage-stats.rst b/Documentation/userspace-api/media/drivers/media-usage-stats.rst
> new file mode 100644
> index 000000000000..d3dc07002f62
> --- /dev/null
> +++ b/Documentation/userspace-api/media/drivers/media-usage-stats.rst
> @@ -0,0 +1,85 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _media-usage-stats:
> +
> +==========================
> +Media client usage stats

stats -> statistics

But are these really statistics? Isn't it just the current status?
In many ways this feature looks to me similar to what VIDIOC_LOG_STATUS does,
except in a nicer format. When VIDIOC_LOG_STATUS was first added, fdinfo
didn't exist yet.

And I wouldn't call it 'Media client': it's specific to stateless V4L2
codec drivers.

> +==========================
> +
> +Stateless V4L2 codec drivers can optionally expose per-file-descriptor usage
> +statistics via ``/proc/<pid>/fdinfo/<fd>``. This is analogous to the DRM fdinfo
> +mechanism documented in :ref:`drm-client-usage-stats`, but uses the ``media-``
> +key prefix for V4L2 media devices.
> +
> +This interface is specific to stateless (request API based) codec devices,
> +including 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.
> +
> +Stateful codec devices cannot support this interface because their firmware
> +manages job scheduling internally. The kernel driver submits bitstream data
> +but has no visibility into per-frame hardware execution timing.
> +
> +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 ``media-``.
> +- Driver-specific keys shall be prefixed with ``driver_name-``.
> +
> +Mandatory keys
> +--------------
> +
> +- media-driver: <valstr>

I'd pick 'v4l2-driver'. Since 'media-driver' is too generic for this
since that encompasses also DVB/CEC/RC drivers.

> +
> +  String shall contain the name of the media driver.

'V4L2 stateless codec driver'

> +
> +- media-type: <valstr>

Poor name.

> +
> +  String shall identify the type of media engine exposed through this file
> +  descriptor. Standard values are ``decoder`` and ``encoder``.

I think I would use 'stateless-decoder' and 'stateless-encoder'. It's more
specific than de/encoder since that can be stateful as well.

So I am missing the big picture here: right now this patch adds support for
this for stateless codecs, but what happens in the future if this is also
added for regular video capture devices, ISPs, etc.?

The naming here matters, it has to have some sort of scheme so it can be
extended to other types of drivers. So a 'media' prefix is too generic,
and it also looks like it refers to the /dev/mediaX device.

> +
> +Utilization keys
> +----------------
> +
> +- media-engine-usage: <uint> ns

'Media Engine': very vague.

> +
> +  Time in nanoseconds that the hardware engine spent busy processing work

Cumulative since creating the file handle? Or since the last read?

> +  belonging to this file descriptor. The engine being measured is identified
> +  by the ``media-type`` key.
> +
> +  Values are not required to be constantly monotonic if it makes the driver
> +  implementation easier, but are required to catch up with the previously
> +  reported larger value within a reasonable period.

Does this make sense for codecs?

I can tell that this is heavily influenced by the drm documentation, but that
does not necessarily translate to V4L2.

> +
> +Frequency keys
> +--------------
> +
> +- media-maxfreq: <uint> Hz
> +
> +  Maximum operating frequency of the main engine clock.
> +
> +- media-curfreq: <uint> Hz
> +
> +  Current operating frequency of the main engine clock.

'Main engine clock'?

> +
> +Example output
> +==============
> +
> +::
> +
> +  media-driver:           hantro-vpu
> +  media-type:             decoder
> +  media-engine-usage:     123456789 ns
> +  media-maxfreq:          600000000 Hz
> +  media-curfreq:          600000000 Hz
> 

Regards,

	Hans

Re: [PATCH v2 3/5] media: v4l2-core: Add v4l2-stats interface

[Hans Verkuil]

On 17/06/2026 20:10, Detlev Casanova wrote:
> Provide helpers for media drivers to set fdinfo data and print the
> key:value pairs in a standard way.
> 
> User drivers can set stats values with helpers like:
>  - v4l2_stats_update_hw_usage
>  - v4l2_stats_set_media_dev_type
> 
> And also call the show helpers from their show_fdinfo callback with:
>  - v4l2_stats_show -- Shows the values set previously
>  - v4l2_stats_show_clock -- Shows the main clock state.
> 
> The show_clock helper is used instead of updating a clock value in
> v4l2_stats for the following reasons:
>  - Clocks are at the device level, this is not a per-fd information
>  - This avoids having clock references in v4l2-core
>  - Drivers can use different approaches to manage clocks
>    (e.g.: bulk_data or not: A set helper wouldn't please all drivers)
>  - Arguably, clocks could be exposed elsewhere (like a debugfs), but we
>    want something close to what DRM does and centralizing information has
>    its advantages for userspace tooling.
> 
> In DRM the key:value pair format for clocks is documented and each driver
> can write them directly based on that.
> In this case, provide a helper and document the format.
> 
> Signed-off-by: Detlev Casanova <detlev.casanova@collabora.com>
> ---
>  drivers/media/v4l2-core/Makefile     |  2 +-
>  drivers/media/v4l2-core/v4l2-dev.c   |  2 ++
>  drivers/media/v4l2-core/v4l2-fh.c    |  3 ++
>  drivers/media/v4l2-core/v4l2-stats.c | 65 ++++++++++++++++++++++++++++++++++++
>  include/media/v4l2-fh.h              |  2 ++
>  include/media/v4l2-stats.h           | 44 ++++++++++++++++++++++++
>  6 files changed, 117 insertions(+), 1 deletion(-)
> 
> diff --git a/drivers/media/v4l2-core/Makefile b/drivers/media/v4l2-core/Makefile
> index 329f0eadce99..20e1ab74ac09 100644
> --- a/drivers/media/v4l2-core/Makefile
> +++ b/drivers/media/v4l2-core/Makefile
> @@ -9,7 +9,7 @@ ccflags-y += -I$(srctree)/drivers/media/tuners
>  tuner-objs	:=	tuner-core.o
>  
>  videodev-objs	:=	v4l2-dev.o v4l2-ioctl.o v4l2-device.o v4l2-fh.o \
> -			v4l2-event.o v4l2-subdev.o v4l2-common.o \
> +			v4l2-event.o v4l2-subdev.o v4l2-common.o v4l2-stats.o \
>  			v4l2-ctrls-core.o v4l2-ctrls-api.o \
>  			v4l2-ctrls-request.o v4l2-ctrls-defs.o
>  
> diff --git a/drivers/media/v4l2-core/v4l2-dev.c b/drivers/media/v4l2-core/v4l2-dev.c
> index 3878fa2ff73e..3e7a6876dffd 100644
> --- a/drivers/media/v4l2-core/v4l2-dev.c
> +++ b/drivers/media/v4l2-core/v4l2-dev.c
> @@ -486,6 +486,8 @@ static void v4l2_show_fdinfo(struct seq_file *m, struct file *filp)
>  {
>  	struct video_device *vdev = video_devdata(filp);
>  
> +	seq_printf(m, "media-driver:\t%s\n", vdev->v4l2_dev->name);
> +
>  	if (vdev->fops->show_fdinfo)
>  		vdev->fops->show_fdinfo(m, filp);
>  }
> diff --git a/drivers/media/v4l2-core/v4l2-fh.c b/drivers/media/v4l2-core/v4l2-fh.c
> index b184bed8aca9..1b655672c718 100644
> --- a/drivers/media/v4l2-core/v4l2-fh.c
> +++ b/drivers/media/v4l2-core/v4l2-fh.c
> @@ -17,6 +17,7 @@
>  #include <media/v4l2-event.h>
>  #include <media/v4l2-ioctl.h>
>  #include <media/v4l2-mc.h>
> +#include <media/v4l2-stats.h>
>  
>  void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev)
>  {
> @@ -38,6 +39,7 @@ void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev)
>  	INIT_LIST_HEAD(&fh->subscribed);
>  	fh->sequence = -1;
>  	mutex_init(&fh->subscribe_lock);
> +	v4l2_stats_init(&fh->stats);
>  }
>  EXPORT_SYMBOL_GPL(v4l2_fh_init);
>  
> @@ -88,6 +90,7 @@ void v4l2_fh_exit(struct v4l2_fh *fh)
>  	v4l2_event_unsubscribe_all(fh);
>  	mutex_destroy(&fh->subscribe_lock);
>  	fh->vdev = NULL;
> +	v4l2_stats_exit(&fh->stats);
>  }
>  EXPORT_SYMBOL_GPL(v4l2_fh_exit);
>  
> diff --git a/drivers/media/v4l2-core/v4l2-stats.c b/drivers/media/v4l2-core/v4l2-stats.c
> new file mode 100644
> index 000000000000..93e64ef2e7bb
> --- /dev/null
> +++ b/drivers/media/v4l2-core/v4l2-stats.c
> @@ -0,0 +1,65 @@
> +// SPDX-License-Identifier: GPL-2.0-only
> +/*
> + * v4l2-stats.c
> + *
> + * V4L2 statistics management.
> + *
> + * Maintain a per-file handle list of statistics about the hardware and handle
> + * exposing it in the fdinfo.
> + *
> + * Copyright (C) 2026 Collabora.
> + *
> + * Contact: Detlev Casanova <detlev.casanova@collabora.com>
> + */
> +
> +#include <linux/types.h>
> +#include <linux/seq_file.h>
> +#include <linux/clk.h>
> +#include <media/v4l2-stats.h>
> +
> +static const char * const dev_type_name[] = {
> +	[MEDIA_DEV_TYPE_V4L2] = "media",
> +	[MEDIA_DEV_TYPE_V4L2_STATELESS_ENCODER] = "encoder",
> +	[MEDIA_DEV_TYPE_V4L2_STATELESS_DECODER] = "decoder",
> +};
> +
> +void v4l2_stats_init(struct v4l2_stats *stats)
> +{
> +	stats->hw_usage_time = 0;
> +	stats->media_dev_type = MEDIA_DEV_TYPE_V4L2;
> +}
> +
> +void v4l2_stats_exit(struct v4l2_stats *stats)
> +{
> +}
> +
> +void v4l2_stats_update_hw_usage(struct v4l2_stats *stats, u64 usage_time)
> +{
> +	stats->hw_usage_time += usage_time;
> +}
> +EXPORT_SYMBOL_GPL(v4l2_stats_update_hw_usage);
> +
> +void v4l2_stats_set_media_dev_type(struct v4l2_stats *stats, enum v4l2_media_dev_type type)
> +{
> +	if (type >= MEDIA_DEV_TYPE_COUNT)
> +		return;
> +
> +	stats->media_dev_type = type;
> +}
> +EXPORT_SYMBOL_GPL(v4l2_stats_set_media_dev_type);
> +
> +void v4l2_stats_show(struct v4l2_stats *stats, struct seq_file *m)
> +{
> +	seq_printf(m, "media-type:\t%s\n", dev_type_name[stats->media_dev_type]);
> +	seq_printf(m, "media-engine-usage:\t%llu ns\n", stats->hw_usage_time);
> +}
> +EXPORT_SYMBOL_GPL(v4l2_stats_show);
> +
> +void v4l2_stats_show_clock(struct seq_file *m, struct clk *clk)
> +{
> +	seq_printf(m, "media-maxfreq:\t%lu Hz\n",
> +		   clk_get_rate(clk));
> +	seq_printf(m, "media-curfreq:\t%lu Hz\n",
> +		   clk_get_rate(clk));
> +}
> +EXPORT_SYMBOL_GPL(v4l2_stats_show_clock);
> diff --git a/include/media/v4l2-fh.h b/include/media/v4l2-fh.h
> index aad4b3689d7e..ae6688722bee 100644
> --- a/include/media/v4l2-fh.h
> +++ b/include/media/v4l2-fh.h
> @@ -17,6 +17,7 @@
>  #include <linux/kconfig.h>
>  #include <linux/list.h>
>  #include <linux/videodev2.h>
> +#include <media/v4l2-stats.h>
>  
>  struct video_device;
>  struct v4l2_ctrl_handler;
> @@ -43,6 +44,7 @@ struct v4l2_fh {
>  	struct list_head	list;
>  	struct video_device	*vdev;
>  	struct v4l2_ctrl_handler *ctrl_handler;
> +	struct v4l2_stats	stats;
>  	enum v4l2_priority	prio;
>  
>  	/* Events */
> diff --git a/include/media/v4l2-stats.h b/include/media/v4l2-stats.h
> new file mode 100644
> index 000000000000..d580933c4181
> --- /dev/null
> +++ b/include/media/v4l2-stats.h
> @@ -0,0 +1,44 @@
> +/* SPDX-License-Identifier: GPL-2.0-only */
> +/*
> + * v4l2-stats.h
> + *
> + * V4L2 statistics management.
> + *
> + * Maintain a per-file handle list of statistics about the hardware and handle
> + * exposing it in the fdinfo.
> + *
> + * Copyright (C) 2026 Collabora.
> + *
> + * Contact: Detlev Casanova <detlev.casanova@collabora.com>
> + */
> +#ifndef V4L2_STATS_H
> +#define V4L2_STATS_H
> +
> +#include <linux/types.h>
> +
> +struct clk;
> +struct seq_file;
> +
> +enum v4l2_media_dev_type {
> +	MEDIA_DEV_TYPE_V4L2 = 0,
> +	MEDIA_DEV_TYPE_V4L2_STATELESS_ENCODER,
> +	MEDIA_DEV_TYPE_V4L2_STATELESS_DECODER,
> +
> +	MEDIA_DEV_TYPE_COUNT,

I'm a bit unhappy about introducing yet another type. Do we need it?

> +};
> +
> +struct v4l2_stats {

Poor name, and it conflicts with ISP statistics.

How about v4l2_pdinfo? And v4l2-fdinfo.h etc. That avoids any confusion and
also clearly says what this is about.

> +	u64 hw_usage_time;
> +	enum v4l2_media_dev_type media_dev_type;

This should be the first field.

> +};
> +
> +void v4l2_stats_init(struct v4l2_stats *stats);
> +void v4l2_stats_exit(struct v4l2_stats *stats);
> +
> +void v4l2_stats_update_hw_usage(struct v4l2_stats *stats, u64 usage_time);
> +void v4l2_stats_set_media_dev_type(struct v4l2_stats *stats, enum v4l2_media_dev_type type);
> +
> +void v4l2_stats_show(struct v4l2_stats *stats, struct seq_file *m);
> +void v4l2_stats_show_clock(struct seq_file *m, struct clk *clk);
> +
> +#endif /* V4L2_STATS_H */
> 

Regards,

	Hans

Re: [PATCH v2 2/5] docs: media: add documentation for media client usage stats

[Mauro Carvalho Chehab]

On Wed, Jun 17, 2026 at 02:10:57PM -0400, Detlev Casanova wrote:
> From: Christopher Healy <healych@amazon.com>
> 
> Document the media fdinfo interface for per-file-descriptor usage
> statistics exposed by stateless V4L2 codec drivers via
> /proc/<pid>/fdinfo/<fd>.
> 
> This interface is designed for stateless (request API based) codec
> devices where the kernel driver has per-job visibility into hardware
> execution. Stateful codecs cannot support all of this because their
> firmware manages job scheduling opaquely.
> 
> The specification defines media- prefixed keys for engine utilization
> time, and operating frequency, following the same conventions as the DRM
> fdinfo mechanism documented in drm-usage-stats.rst.
> 
> More fields can be added later.
> 
> Signed-off-by: Christopher Healy <healych@amazon.com>
> Signed-off-by: Detlev Casanova <detlev.casanova@collabora.com>
> ---
>  .../userspace-api/media/drivers/index.rst          |  1 +
>  .../media/drivers/media-usage-stats.rst            | 85 ++++++++++++++++++++++

Please notice that sysfs/procfs APIs are usually documented at
Documentation/ABI/, using a machine-readable format[1]. Still, we do want
it also at media uAPI. So, please add it there as well on your next spin.

[1] As those are new, Documentation/ABI/testing/ is probably the best place.

>  2 files changed, 86 insertions(+)
> 
> diff --git a/Documentation/userspace-api/media/drivers/index.rst b/Documentation/userspace-api/media/drivers/index.rst
> index 02967c9b18d6..61879738836c 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
> +	media-usage-stats
>  	npcm-video
>  	omap3isp-uapi
>  	thp7312
> diff --git a/Documentation/userspace-api/media/drivers/media-usage-stats.rst b/Documentation/userspace-api/media/drivers/media-usage-stats.rst
> new file mode 100644
> index 000000000000..d3dc07002f62
> --- /dev/null
> +++ b/Documentation/userspace-api/media/drivers/media-usage-stats.rst
> @@ -0,0 +1,85 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _media-usage-stats:
> +
> +==========================
> +Media client usage stats
> +==========================
> +
> +Stateless V4L2 codec drivers can optionally expose per-file-descriptor usage
> +statistics via ``/proc/<pid>/fdinfo/<fd>``. This is analogous to the DRM fdinfo
> +mechanism documented in :ref:`drm-client-usage-stats`, but uses the ``media-``
> +key prefix for V4L2 media devices.
> +
> +This interface is specific to stateless (request API based) codec devices,
> +including 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.
> +
> +Stateful codec devices cannot support this interface because their firmware
> +manages job scheduling internally. The kernel driver submits bitstream data
> +but has no visibility into per-frame hardware execution timing.
> +
> +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 ``media-``.
> +- Driver-specific keys shall be prefixed with ``driver_name-``.
> +
> +Mandatory keys
> +--------------
> +
> +- media-driver: <valstr>
> +
> +  String shall contain the name of the media driver.
> +
> +- media-type: <valstr>
> +
> +  String shall identify the type of media engine exposed through this file
> +  descriptor. Standard values are ``decoder`` and ``encoder``.
> +
> +Utilization keys
> +----------------
> +
> +- media-engine-usage: <uint> ns
> +
> +  Time in nanoseconds that the hardware engine spent busy processing work
> +  belonging to this file descriptor. The engine being measured is identified
> +  by the ``media-type`` key.
> +
> +  Values are not required to be constantly monotonic if it makes the driver
> +  implementation easier, but are required to catch up with the previously
> +  reported larger value within a reasonable period.
> +
> +Frequency keys
> +--------------
> +
> +- media-maxfreq: <uint> Hz
> +
> +  Maximum operating frequency of the main engine clock.
> +
> +- media-curfreq: <uint> Hz
> +
> +  Current operating frequency of the main engine clock.
> +
> +Example output
> +==============
> +
> +::
> +
> +  media-driver:           hantro-vpu
> +  media-type:             decoder
> +  media-engine-usage:     123456789 ns
> +  media-maxfreq:          600000000 Hz
> +  media-curfreq:          600000000 Hz
> 
> -- 
> 2.54.0
> 

-- 
Thanks,
Mauro

Re: [PATCH v2 2/5] docs: media: add documentation for media client usage stats

[Nicolas Dufresne]

[-- Attachment #1: Type: text/plain, Size: 9829 bytes --]

Hi,

Le vendredi 19 juin 2026 à 14:58 +0200, Hans Verkuil a écrit :
> Hi Detlev,
> 
> Interesting, I had never heard of fdinfo, so if nothing else, I learned something new!
> 
> On 17/06/2026 20:10, Detlev Casanova wrote:
> > From: Christopher Healy <healych@amazon.com>
> > 
> > Document the media fdinfo interface for per-file-descriptor usage
> > statistics exposed by stateless V4L2 codec drivers via
> > /proc/<pid>/fdinfo/<fd>.
> > 
> > This interface is designed for stateless (request API based) codec
> > devices where the kernel driver has per-job visibility into hardware
> > execution. Stateful codecs cannot support all of this because their
> > firmware manages job scheduling opaquely.
> > 
> > The specification defines media- prefixed keys for engine utilization
> > time, and operating frequency, following the same conventions as the DRM
> > fdinfo mechanism documented in drm-usage-stats.rst.
> > 
> > More fields can be added later.
> > 
> > Signed-off-by: Christopher Healy <healych@amazon.com>
> > Signed-off-by: Detlev Casanova <detlev.casanova@collabora.com>
> > ---
> >  .../userspace-api/media/drivers/index.rst          |  1 +
> >  .../media/drivers/media-usage-stats.rst            | 85 ++++++++++++++++++++++
> >  2 files changed, 86 insertions(+)
> > 
> > diff --git a/Documentation/userspace-api/media/drivers/index.rst b/Documentation/userspace-api/media/drivers/index.rst
> > index 02967c9b18d6..61879738836c 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
> > +	media-usage-stats
> >  	npcm-video
> >  	omap3isp-uapi
> >  	thp7312
> > diff --git a/Documentation/userspace-api/media/drivers/media-usage-stats.rst b/Documentation/userspace-api/media/drivers/media-usage-stats.rst
> > new file mode 100644
> > index 000000000000..d3dc07002f62
> > --- /dev/null
> > +++ b/Documentation/userspace-api/media/drivers/media-usage-stats.rst
> > @@ -0,0 +1,85 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +.. _media-usage-stats:
> > +
> > +==========================
> > +Media client usage stats
> 
> stats -> statistics
> 
> But are these really statistics? Isn't it just the current status?
> In many ways this feature looks to me similar to what VIDIOC_LOG_STATUS does,
> except in a nicer format. When VIDIOC_LOG_STATUS was first added, fdinfo
> didn't exist yet.
> 
> And I wouldn't call it 'Media client': it's specific to stateless V4L2
> codec drivers.

While it is currently implemented for sateless m2m codec drivers as example
(because we can't implement this everywhere at once really, its not practical),
there is no reason why we cannot track to a process fdinfo memory usage
associated with other video devices. In fact, I would pretty much want to see
capture devices showing up in v4l2top, as these are using a lot of memory too,
specially the new camera pipelines. And this is also perfectly suitable for
stateful codec, converters, everything.

So please, let's agree this is not "stateless V4L2 codec drivers" specific.

About VIDIOC_LOG_STATUS, this is effectively broken for m2m, only the owning
session process could call that. Its also pretty bad for tools to have to
monitor the dmesg and filter it up. fdinfo on the other end, does not require
opening the device and permissions are very clear, and bound to user process.

> 
> > +==========================
> > +
> > +Stateless V4L2 codec drivers can optionally expose per-file-descriptor usage
> > +statistics via ``/proc/<pid>/fdinfo/<fd>``. This is analogous to the DRM fdinfo
> > +mechanism documented in :ref:`drm-client-usage-stats`, but uses the ``media-``
> > +key prefix for V4L2 media devices.
> > +
> > +This interface is specific to stateless (request API based) codec devices,
> > +including 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.
> > +
> > +Stateful codec devices cannot support this interface because their firmware
> > +manages job scheduling internally. The kernel driver submits bitstream data
> > +but has no visibility into per-frame hardware execution timing.
> > +
> > +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 ``media-``.
> > +- Driver-specific keys shall be prefixed with ``driver_name-``.
> > +
> > +Mandatory keys
> > +--------------
> > +
> > +- media-driver: <valstr>
> 
> I'd pick 'v4l2-driver'. Since 'media-driver' is too generic for this
> since that encompasses also DVB/CEC/RC drivers.
> 
> > +
> > +  String shall contain the name of the media driver.
> 
> 'V4L2 stateless codec driver'

With that said, we can refine, but not in that direction.

> 
> > +
> > +- media-type: <valstr>
> 
> Poor name.
> 
> > +
> > +  String shall identify the type of media engine exposed through this file
> > +  descriptor. Standard values are ``decoder`` and ``encoder``.
> 
> I think I would use 'stateless-decoder' and 'stateless-encoder'. It's more
> specific than de/encoder since that can be stateful as well.
> 
> So I am missing the big picture here: right now this patch adds support for
> this for stateless codecs, but what happens in the future if this is also
> added for regular video capture devices, ISPs, etc.?

We should work further on the type system, then we'd simply have to extend it.
Different type of driver will provide different key/value pair. We should well
document which key are mandatory for the type (or for all type, like giving a
name for general identification purpose).

Of course, the current proposal is very torward processing cores, hence the one
to one match with what GPUs present in fdinfo today in mainline, such are
frequency, core utilization time, etc.

Though, DMA devices such as capture may expose more of a bandwidth kind of
information. I really don't want to make up too may cases, so owners of these
don't feel like this is mandated though. As we develop software using our
drivers, we should be able to figure-out what kind of things are important to
monitor. For CODECs, we have two majors things. a) core utilization (which can
be with a timer like this one, but ideally using cycle counters, or firmware
provided data). b) memory usage.

> 
> The naming here matters, it has to have some sort of scheme so it can be
> extended to other types of drivers. So a 'media' prefix is too generic,
> and it also looks like it refers to the /dev/mediaX device.
> 
> > +
> > +Utilization keys
> > +----------------
> > +
> > +- media-engine-usage: <uint> ns
> 
> 'Media Engine': very vague.
> 
> > +
> > +  Time in nanoseconds that the hardware engine spent busy processing work
> 
> Cumulative since creating the file handle? Or since the last read?
> 
> > +  belonging to this file descriptor. The engine being measured is identified
> > +  by the ``media-type`` key.
> > +
> > +  Values are not required to be constantly monotonic if it makes the driver
> > +  implementation easier, but are required to catch up with the previously
> > +  reported larger value within a reasonable period.
> 
> Does this make sense for codecs?
> 
> I can tell that this is heavily influenced by the drm documentation, but that
> does not necessarily translate to V4L2.

I would guess this is bound to usage of cycle counter, which we definitely have
in some codec HW exposing. As the frequency fluctuate, I suppose there is ways
you can get your calculation a bit off, as this is being sampled. Basically, the
frequence change is not strictly tracked by our drivers, which is ok. But I also
don't seen why we wouldn't keep the counters monotonic, its really easy to do.

> 
> > +
> > +Frequency keys
> > +--------------
> > +
> > +- media-maxfreq: <uint> Hz
> > +
> > +  Maximum operating frequency of the main engine clock.
> > +
> > +- media-curfreq: <uint> Hz
> > +
> > +  Current operating frequency of the main engine clock.
> 
> 'Main engine clock'?

The word "engine" seems indeed alien in this subsystem. It is referring to a
system where you open one devices, so you have one fdinfo, but multiple cores.
Each cores may be running at it owns frequency. But I think this is a little too
vague to my taste.

Hope this feedback does not cross to many wires, but tagging this as specific to
stateless codec drivers did spark a little in my head. And we are really in need
for a way to monitor our drivers.

Nicolas

> 
> > +
> > +Example output
> > +==============
> > +
> > +::
> > +
> > +  media-driver:           hantro-vpu
> > +  media-type:             decoder
> > +  media-engine-usage:     123456789 ns
> > +  media-maxfreq:          600000000 Hz
> > +  media-curfreq:          600000000 Hz
> > 
> 
> Regards,
> 
> 	Hans

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 228 bytes --]