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.compull/1090/head
Sebastian Fricke
Jonathan Corbet
parent
a037699da0
commit
83a474c11e
|
|
@ -20,6 +20,11 @@ Documentation/driver-api/media/index.rst
|
|||
- for driver development information and Kernel APIs used by
|
||||
media devices;
|
||||
|
||||
Documentation/process/debugging/media_specific_debugging_guide.rst
|
||||
|
||||
- for advice about essential tools and techniques to debug drivers on this
|
||||
subsystem
|
||||
|
||||
.. toctree::
|
||||
:caption: Table of Contents
|
||||
:maxdepth: 2
|
||||
|
|
|
|||
|
|
@ -4,12 +4,25 @@
|
|||
Debugging advice for Linux Kernel developers
|
||||
============================================
|
||||
|
||||
general guides
|
||||
--------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
driver_development_debugging_guide
|
||||
userspace_debugging_guide
|
||||
|
||||
.. only:: subproject and html
|
||||
|
||||
subsystem specific guides
|
||||
-------------------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
media_specific_debugging_guide
|
||||
|
||||
.. only:: subproject and html
|
||||
|
||||
Indices
|
||||
|
|
|
|||
|
|
@ -0,0 +1,180 @@
|
|||
.. SPDX-License-Identifier: GPL-2.0
|
||||
|
||||
============================================
|
||||
Debugging and tracing in the media subsystem
|
||||
============================================
|
||||
|
||||
This document serves as a starting point and lookup for debugging device
|
||||
drivers in the media subsystem and to debug these drivers from userspace.
|
||||
|
||||
.. contents::
|
||||
:depth: 3
|
||||
|
||||
General debugging advice
|
||||
------------------------
|
||||
|
||||
For general advice see the :doc:`general advice document
|
||||
</process/debugging/index>`.
|
||||
|
||||
The following sections show you some of the available tools.
|
||||
|
||||
dev_debug module parameter
|
||||
--------------------------
|
||||
|
||||
Every video device provides a ``dev_debug`` parameter, which allows to get
|
||||
further insights into the IOCTLs in the background.::
|
||||
|
||||
# cat /sys/class/video4linux/video3/name
|
||||
rkvdec
|
||||
# echo 0xff > /sys/class/video4linux/video3/dev_debug
|
||||
# dmesg -wH
|
||||
[...] videodev: v4l2_open: video3: open (0)
|
||||
[ +0.000036] video3: VIDIOC_QUERYCAP: driver=rkvdec, card=rkvdec,
|
||||
bus=platform:rkvdec, version=0x00060900, capabilities=0x84204000,
|
||||
device_caps=0x04204000
|
||||
|
||||
For the full documentation see :ref:`driver-api/media/v4l2-dev:video device
|
||||
debugging`
|
||||
|
||||
dev_dbg() / v4l2_dbg()
|
||||
----------------------
|
||||
|
||||
Two debug print statements, which are specific for devices and for the v4l2
|
||||
subsystem, avoid adding these to your final submission unless they have
|
||||
long-term value for investigations.
|
||||
|
||||
For a general overview please see the
|
||||
:ref:`process/debugging/driver_development_debugging_guide:printk() & friends`
|
||||
guide.
|
||||
|
||||
- Difference between both?
|
||||
|
||||
- v4l2_dbg() utilizes v4l2_printk() under the hood, which further uses
|
||||
printk() directly, thus it cannot be targeted by dynamic debug
|
||||
- dev_dbg() can be targeted by dynamic debug
|
||||
- v4l2_dbg() has a more specific prefix format for the media subsystem, while
|
||||
dev_dbg only highlights the driver name and the location of the log
|
||||
|
||||
Dynamic debug
|
||||
-------------
|
||||
|
||||
A method to trim down the debug output to your needs.
|
||||
|
||||
For general advice see the
|
||||
:ref:`process/debugging/userspace_debugging_guide:dynamic debug` guide.
|
||||
|
||||
Here is one example, that enables all available pr_debug()'s within the file::
|
||||
|
||||
$ alias ddcmd='echo $* > /proc/dynamic_debug/control'
|
||||
$ ddcmd '-p; file v4l2-h264.c +p'
|
||||
$ grep =p /proc/dynamic_debug/control
|
||||
drivers/media/v4l2-core/v4l2-h264.c:372 [v4l2_h264]print_ref_list_b =p
|
||||
"ref_pic_list_b%u (cur_poc %u%c) %s"
|
||||
drivers/media/v4l2-core/v4l2-h264.c:333 [v4l2_h264]print_ref_list_p =p
|
||||
"ref_pic_list_p (cur_poc %u%c) %s\n"
|
||||
|
||||
Ftrace
|
||||
------
|
||||
|
||||
An internal kernel tracer that can trace static predefined events, function
|
||||
calls, etc. Very useful for debugging problems without changing the kernel and
|
||||
understanding the behavior of subsystems.
|
||||
|
||||
For general advice see the
|
||||
:ref:`process/debugging/userspace_debugging_guide:ftrace` guide.
|
||||
|
||||
DebugFS
|
||||
-------
|
||||
|
||||
This tool allows you to dump or modify internal values of your driver to files
|
||||
in a custom filesystem.
|
||||
|
||||
For general advice see the
|
||||
:ref:`process/debugging/driver_development_debugging_guide:debugfs` guide.
|
||||
|
||||
Perf & alternatives
|
||||
-------------------
|
||||
|
||||
Tools to measure the various stats on a running system to diagnose issues.
|
||||
|
||||
For general advice see the
|
||||
:ref:`process/debugging/userspace_debugging_guide:perf & alternatives` guide.
|
||||
|
||||
Example for media devices:
|
||||
|
||||
Gather statistics data for a decoding job: (This example is on a RK3399 SoC
|
||||
with the rkvdec codec driver using the `fluster test suite
|
||||
<https://github.com/fluendo/fluster>`__)::
|
||||
|
||||
perf stat -d python3 fluster.py run -d GStreamer-H.264-V4L2SL-Gst1.0 -ts
|
||||
JVT-AVC_V1 -tv AUD_MW_E -j1
|
||||
...
|
||||
Performance counter stats for 'python3 fluster.py run -d
|
||||
GStreamer-H.264-V4L2SL-Gst1.0 -ts JVT-AVC_V1 -tv AUD_MW_E -j1 -v':
|
||||
|
||||
7794.23 msec task-clock:u # 0.697 CPUs utilized
|
||||
0 context-switches:u # 0.000 /sec
|
||||
0 cpu-migrations:u # 0.000 /sec
|
||||
11901 page-faults:u # 1.527 K/sec
|
||||
882671556 cycles:u # 0.113 GHz (95.79%)
|
||||
711708695 instructions:u # 0.81 insn per cycle (95.79%)
|
||||
10581935 branches:u # 1.358 M/sec (15.13%)
|
||||
6871144 branch-misses:u # 64.93% of all branches (95.79%)
|
||||
281716547 L1-dcache-loads:u # 36.144 M/sec (95.79%)
|
||||
9019581 L1-dcache-load-misses:u # 3.20% of all L1-dcache accesses (95.79%)
|
||||
<not supported> LLC-loads:u
|
||||
<not supported> LLC-load-misses:u
|
||||
|
||||
11.180830431 seconds time elapsed
|
||||
|
||||
1.502318000 seconds user
|
||||
6.377221000 seconds sys
|
||||
|
||||
The availability of events and metrics depends on the system you are running.
|
||||
|
||||
Error checking & panic analysis
|
||||
-------------------------------
|
||||
|
||||
Various Kernel configuration options to enhance error detection of the Linux
|
||||
Kernel with the cost of lowering performance.
|
||||
|
||||
For general advice see the
|
||||
:ref:`process/debugging/driver_development_debugging_guide:kasan, ubsan,
|
||||
lockdep and other error checkers` guide.
|
||||
|
||||
Driver verification with v4l2-compliance
|
||||
----------------------------------------
|
||||
|
||||
To verify, that a driver adheres to the v4l2 API, the tool v4l2-compliance is
|
||||
used, which is part of the `v4l_utils
|
||||
<https://git.linuxtv.org/v4l-utils.git>`__, a suite of userspace tools to work
|
||||
with the media subsystem.
|
||||
|
||||
To see the detailed media topology (and check it) use::
|
||||
|
||||
v4l2-compliance -M /dev/mediaX --verbose
|
||||
|
||||
You can also run a full compliance check for all devices referenced in the
|
||||
media topology with::
|
||||
|
||||
v4l2-compliance -m /dev/mediaX
|
||||
|
||||
Debugging problems with receiving video
|
||||
---------------------------------------
|
||||
|
||||
Implementing vidioc_log_status in the driver: this can log the current status
|
||||
to the kernel log. It's called by v4l2-ctl --log-status. Very useful for
|
||||
debugging problems with receiving video (TV/S-Video/HDMI/etc) since the video
|
||||
signal is external (so unpredictable). Less useful with camera sensor inputs
|
||||
since you have control over what the camera sensor does.
|
||||
|
||||
Usually you can just assign the default::
|
||||
|
||||
.vidioc_log_status = v4l2_ctrl_log_status,
|
||||
|
||||
But you can also create your own callback, to create a custom status log.
|
||||
|
||||
You can find an example in the cobalt driver
|
||||
(`drivers/media/pci/cobalt/cobalt-v4l2.c <https://elixir.bootlin.com/linux/v6.11.6/source/drivers/media/pci/cobalt/cobalt-v4l2.c#L567>`__).
|
||||
|
||||
**Copyright** ©2024 : Collabora
|
||||
Loading…
Reference in New Issue