Skip to content

Commit 83a474c

Browse files
sefrickeJonathan Corbet
sefricke
authored and
Jonathan Corbet
committed
docs: Add debugging guide for the media subsystem
Provide a guide for developers on how to debug code with a focus on the media subsystem. This document aims to provide a rough overview over the possibilities and a rational to help choosing the right tool for the given circumstances. Signed-off-by: Sebastian Fricke <sebastian.fricke@collabora.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20241028-media_docs_improve_v3-v3-2-edf5c5b3746f@collabora.com
1 parent a037699 commit 83a474c

File tree

3 files changed

+198
-0
lines changed

3 files changed

+198
-0
lines changed

‎Documentation/admin-guide/media/index.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,11 @@ Documentation/driver-api/media/index.rst
2020
- for driver development information and Kernel APIs used by
2121
media devices;
2222

23+
Documentation/process/debugging/media_specific_debugging_guide.rst
24+
25+
- for advice about essential tools and techniques to debug drivers on this
26+
subsystem
27+
2328
.. toctree::
2429
:caption: Table of Contents
2530
:maxdepth: 2

‎Documentation/process/debugging/index.rst

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,25 @@
44
Debugging advice for Linux Kernel developers
55
============================================
66

7+
general guides
8+
--------------
9+
710
.. toctree::
811
:maxdepth: 1
912

1013
driver_development_debugging_guide
1114
userspace_debugging_guide
1215

16+
.. only:: subproject and html
17+
18+
subsystem specific guides
19+
-------------------------
20+
21+
.. toctree::
22+
:maxdepth: 1
23+
24+
media_specific_debugging_guide
25+
1326
.. only:: subproject and html
1427

1528
Indices

‎Documentation/process/debugging/media_specific_debugging_guide.rst

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
.. SPDX-License-Identifier: GPL-2.0
2+
3+
============================================
4+
Debugging and tracing in the media subsystem
5+
============================================
6+
7+
This document serves as a starting point and lookup for debugging device
8+
drivers in the media subsystem and to debug these drivers from userspace.
9+
10+
.. contents::
11+
:depth: 3
12+
13+
General debugging advice
14+
------------------------
15+
16+
For general advice see the :doc:`general advice document
17+
</process/debugging/index>`.
18+
19+
The following sections show you some of the available tools.
20+
21+
dev_debug module parameter
22+
--------------------------
23+
24+
Every video device provides a ``dev_debug`` parameter, which allows to get
25+
further insights into the IOCTLs in the background.::
26+
27+
# cat /sys/class/video4linux/video3/name
28+
rkvdec
29+
# echo 0xff > /sys/class/video4linux/video3/dev_debug
30+
# dmesg -wH
31+
[...] videodev: v4l2_open: video3: open (0)
32+
[ +0.000036] video3: VIDIOC_QUERYCAP: driver=rkvdec, card=rkvdec,
33+
bus=platform:rkvdec, version=0x00060900, capabilities=0x84204000,
34+
device_caps=0x04204000
35+
36+
For the full documentation see :ref:`driver-api/media/v4l2-dev:video device
37+
debugging`
38+
39+
dev_dbg() / v4l2_dbg()
40+
----------------------
41+
42+
Two debug print statements, which are specific for devices and for the v4l2
43+
subsystem, avoid adding these to your final submission unless they have
44+
long-term value for investigations.
45+
46+
For a general overview please see the
47+
:ref:`process/debugging/driver_development_debugging_guide:printk() & friends`
48+
guide.
49+
50+
- Difference between both?
51+
52+
- v4l2_dbg() utilizes v4l2_printk() under the hood, which further uses
53+
printk() directly, thus it cannot be targeted by dynamic debug
54+
- dev_dbg() can be targeted by dynamic debug
55+
- v4l2_dbg() has a more specific prefix format for the media subsystem, while
56+
dev_dbg only highlights the driver name and the location of the log
57+
58+
Dynamic debug
59+
-------------
60+
61+
A method to trim down the debug output to your needs.
62+
63+
For general advice see the
64+
:ref:`process/debugging/userspace_debugging_guide:dynamic debug` guide.
65+
66+
Here is one example, that enables all available pr_debug()'s within the file::
67+
68+
$ alias ddcmd='echo $* > /proc/dynamic_debug/control'
69+
$ ddcmd '-p; file v4l2-h264.c +p'
70+
$ grep =p /proc/dynamic_debug/control
71+
drivers/media/v4l2-core/v4l2-h264.c:372 [v4l2_h264]print_ref_list_b =p
72+
"ref_pic_list_b%u (cur_poc %u%c) %s"
73+
drivers/media/v4l2-core/v4l2-h264.c:333 [v4l2_h264]print_ref_list_p =p
74+
"ref_pic_list_p (cur_poc %u%c) %s\n"
75+
76+
Ftrace
77+
------
78+
79+
An internal kernel tracer that can trace static predefined events, function
80+
calls, etc. Very useful for debugging problems without changing the kernel and
81+
understanding the behavior of subsystems.
82+
83+
For general advice see the
84+
:ref:`process/debugging/userspace_debugging_guide:ftrace` guide.
85+
86+
DebugFS
87+
-------
88+
89+
This tool allows you to dump or modify internal values of your driver to files
90+
in a custom filesystem.
91+
92+
For general advice see the
93+
:ref:`process/debugging/driver_development_debugging_guide:debugfs` guide.
94+
95+
Perf & alternatives
96+
-------------------
97+
98+
Tools to measure the various stats on a running system to diagnose issues.
99+
100+
For general advice see the
101+
:ref:`process/debugging/userspace_debugging_guide:perf & alternatives` guide.
102+
103+
Example for media devices:
104+
105+
Gather statistics data for a decoding job: (This example is on a RK3399 SoC
106+
with the rkvdec codec driver using the `fluster test suite
107+
<https://github.com/fluendo/fluster>`__)::
108+
109+
perf stat -d python3 fluster.py run -d GStreamer-H.264-V4L2SL-Gst1.0 -ts
110+
JVT-AVC_V1 -tv AUD_MW_E -j1
111+
...
112+
Performance counter stats for 'python3 fluster.py run -d
113+
GStreamer-H.264-V4L2SL-Gst1.0 -ts JVT-AVC_V1 -tv AUD_MW_E -j1 -v':
114+
115+
7794.23 msec task-clock:u # 0.697 CPUs utilized
116+
0 context-switches:u # 0.000 /sec
117+
0 cpu-migrations:u # 0.000 /sec
118+
11901 page-faults:u # 1.527 K/sec
119+
882671556 cycles:u # 0.113 GHz (95.79%)
120+
711708695 instructions:u # 0.81 insn per cycle (95.79%)
121+
10581935 branches:u # 1.358 M/sec (15.13%)
122+
6871144 branch-misses:u # 64.93% of all branches (95.79%)
123+
281716547 L1-dcache-loads:u # 36.144 M/sec (95.79%)
124+
9019581 L1-dcache-load-misses:u # 3.20% of all L1-dcache accesses (95.79%)
125+
<not supported> LLC-loads:u
126+
<not supported> LLC-load-misses:u
127+
128+
11.180830431 seconds time elapsed
129+
130+
1.502318000 seconds user
131+
6.377221000 seconds sys
132+
133+
The availability of events and metrics depends on the system you are running.
134+
135+
Error checking & panic analysis
136+
-------------------------------
137+
138+
Various Kernel configuration options to enhance error detection of the Linux
139+
Kernel with the cost of lowering performance.
140+
141+
For general advice see the
142+
:ref:`process/debugging/driver_development_debugging_guide:kasan, ubsan,
143+
lockdep and other error checkers` guide.
144+
145+
Driver verification with v4l2-compliance
146+
----------------------------------------
147+
148+
To verify, that a driver adheres to the v4l2 API, the tool v4l2-compliance is
149+
used, which is part of the `v4l_utils
150+
<https://git.linuxtv.org/v4l-utils.git>`__, a suite of userspace tools to work
151+
with the media subsystem.
152+
153+
To see the detailed media topology (and check it) use::
154+
155+
v4l2-compliance -M /dev/mediaX --verbose
156+
157+
You can also run a full compliance check for all devices referenced in the
158+
media topology with::
159+
160+
v4l2-compliance -m /dev/mediaX
161+
162+
Debugging problems with receiving video
163+
---------------------------------------
164+
165+
Implementing vidioc_log_status in the driver: this can log the current status
166+
to the kernel log. It's called by v4l2-ctl --log-status. Very useful for
167+
debugging problems with receiving video (TV/S-Video/HDMI/etc) since the video
168+
signal is external (so unpredictable). Less useful with camera sensor inputs
169+
since you have control over what the camera sensor does.
170+
171+
Usually you can just assign the default::
172+
173+
.vidioc_log_status = v4l2_ctrl_log_status,
174+
175+
But you can also create your own callback, to create a custom status log.
176+
177+
You can find an example in the cobalt driver
178+
(`drivers/media/pci/cobalt/cobalt-v4l2.c <https://elixir.bootlin.com/linux/v6.11.6/source/drivers/media/pci/cobalt/cobalt-v4l2.c#L567>`__).
179+
180+
**Copyright** ©2024 : Collabora

0 commit comments

Comments
 (0)