Something went wrong. Try again.
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Something went wrong. Try again.
6.6 kB · 180 lines
at master
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181.. SPDX-License-Identifier: GPL-2.0
============================================Debugging and tracing in the media subsystem============================================
This document serves as a starting point and lookup for debugging devicedrivers 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 getfurther 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 devicedebugging`
dev_dbg() / v4l2_dbg()----------------------
Two debug print statements, which are specific for devices and for the v4l2subsystem, avoid adding these to your final submission unless they havelong-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, functioncalls, etc. Very useful for debugging problems without changing the kernel andunderstanding 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 filesin 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 SoCwith 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 LinuxKernel 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 isused, which is part of the `v4l_utils<https://git.linuxtv.org/v4l-utils.git>`__, a suite of userspace tools to workwith 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 themedia topology with::
v4l2-compliance -m /dev/mediaX
Debugging problems with receiving video---------------------------------------
Implementing vidioc_log_status in the driver: this can log the current statusto the kernel log. It's called by v4l2-ctl --log-status. Very useful fordebugging problems with receiving video (TV/S-Video/HDMI/etc) since the videosignal is external (so unpredictable). Less useful with camera sensor inputssince 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