| 1 | |
| 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
|