Media subsystem debugging과 tracing | Linux 6.18.37

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

dev_debug, dev_dbg와 v4l2_dbg

media_specific_debugging_guide.rst:4-75

많은 media driver는 module의 dev_debug parameter로 bit별 debug 범위를 켠다. Driver source의 parameter description과 bit mask를 확인한다. dev_dbg와 v4l2_dbg message는 dynamic debug control로 file, function과 format 단위 enable할 수 있다.

High-rate frame path에 log를 켜면 buffer timing과 underrun을 바꿀 수 있으므로 필요한 category만 좁게 선택하고 reproduction 전후 설정을 기록한다.

Ftrace, debugfs와 performance tool

media_specific_debugging_guide.rst:76-144

V4L2·VB2 tracepoint와 function graph tracer로 ioctl에서 queue, DMA completion, buffer return까지 latency를 연결한다. Debugfs의 media state는 topology와 driver queue를 확인하는 개발 interface이며 stable ABI가 아니다.

perf, trace-cmd, KernelShark와 Perfetto로 CPU scheduling, interrupt와 userspace pipeline을 함께 본다. Panic·oops는 첫 fault stack과 media callback context를 symbolized trace로 남긴다.

v4l2-compliance로 driver contract 검증

media_specific_debugging_guide.rst:145-161

v4l2-compliance는 ioctl behavior, format negotiation, buffer queue와 streaming state machine이 V4L2 API contract를 지키는지 검사한다. 실패 testcase와 command line, device topology, kernel log를 patch test 결과에 포함한다.

Video 수신 문제를 layer별로 분리

media_specific_debugging_guide.rst:162-181

Signal lock·timing, media-bus format, endpoint link frequency, DMA buffer, sequence counter와 userspace dequeue를 차례로 확인한다. Sensor·bridge·receiver 중 어느 subdevice에서 frame과 metadata가 처음 달라지는지 trace해 hardware link 문제와 queue starvation을 구분한다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기

1 .. SPDX-License-Identifier: GPL-2.0

3 ============================================

4 Debugging and tracing in the media subsystem

5 ============================================

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.

10 .. contents::

11 :depth: 3

13 General debugging advice

14 ------------------------

16 For general advice see the :doc:`general advice document

17 </process/debugging/index>`.

19 The following sections show you some of the available tools.

21 dev_debug module parameter

22 --------------------------

24 Every video device provides a ``dev_debug`` parameter, which allows to get

25 further insights into the IOCTLs in the background.::

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

36 For the full documentation see :ref:`driver-api/media/v4l2-dev:video device

37 debugging`

39 dev_dbg() / v4l2_dbg()

40 ----------------------

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.

46 For a general overview please see the

47 :ref:`process/debugging/driver_development_debugging_guide:printk() & friends`

48 guide.

50 - Difference between both?

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

58 Dynamic debug

59 -------------

61 A method to trim down the debug output to your needs.

63 For general advice see the

64 :ref:`process/debugging/userspace_debugging_guide:dynamic debug` guide.

66 Here is one example, that enables all available pr_debug()'s within the file::

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"

76 Ftrace

77 ------

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.

83 For general advice see the

84 :ref:`process/debugging/userspace_debugging_guide:ftrace` guide.

86 DebugFS

87 -------

89 This tool allows you to dump or modify internal values of your driver to files

90 in a custom filesystem.

92 For general advice see the

93 :ref:`process/debugging/driver_development_debugging_guide:debugfs` guide.

95 Perf & alternatives

96 -------------------

98 Tools to measure the various stats on a running system to diagnose issues.

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

181

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

Media subsystem debugging의 출발점

1-19

이 문서는 media subsystem device driver를 kernel 안에서 debug하고 userspace에서 조사할 때 사용할 도구의 출발점이자 찾아보기 문서다. 일반적인 debugging 원칙은 Documentation/process/debugging/index.rst를 먼저 참고한다.

Video device의 dev_debug parameter

21-37

모든 video device는 내부에서 처리되는 IOCTL을 더 자세히 관찰할 수 있는 dev_debug parameter를 제공한다.

# 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

예시는 video3의 이름이 rkvdec인지 확인하고 dev_debug에 0xff를 써 모든 관련 debug bit를 enable한 뒤 dmesg -wH로 v4l2_open과 VIDIOC_QUERYCAP의 driver, card, bus, version, capability를 관찰한다. 전체 설명은 driver-api/media/v4l2-dev의 video device debugging 절을 참고한다.

dev_dbg()와 v4l2_dbg()

39-57

dev_dbg()와 v4l2_dbg()는 각각 일반 device와 V4L2 subsystem에 맞춘 debug print다. 장기적인 조사 가치가 없다면 최종 patch에 임시 debug 출력으로 남기지 않는다.

v4l2_dbg()는 내부에서 v4l2_printk()를 거쳐 printk()를 직접 사용하므로 dynamic debug로 선택할 수 없다.
dev_dbg()는 dynamic debug로 call site를 선택해 enable할 수 있다.
v4l2_dbg()는 media subsystem에 맞춘 더 구체적인 prefix를 사용한다. dev_dbg()는 driver 이름과 log 위치를 중심으로 표시한다.

Dynamic debug로 출력 범위 줄이기

58-75

Dynamic debug는 필요한 call site만 골라 debug 출력을 줄이는 방법이다. 예시는 v4l2-h264.c 안의 모든 pr_debug()를 enable한다.

$ 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, DebugFS, perf, error checker

76-101

Ftrace는 미리 정의된 static event와 function call 등을 trace하는 kernel 내부 tracer다. Kernel을 수정하지 않고 subsystem 동작과 문제를 조사할 때 유용하다.
DebugFS는 driver 내부 값을 custom filesystem의 file로 노출해 dump하거나 수정할 수 있게 한다.
perf와 대안 도구는 running system의 여러 통계를 측정해 문제를 진단한다.
KASAN, UBSAN, lockdep 같은 error checker는 성능 비용을 지불하고 kernel error detection을 강화한다.

각 도구의 일반적인 사용법은 userspace_debugging_guide와 driver_development_debugging_guide의 대응 절을 참고한다.

RK3399 rkvdec 작업의 perf stat 예

103-133

RK3399 SoC의 rkvdec codec driver에서 fluster test suite로 H.264 decoding job을 실행하며 perf stat -d 통계를 수집하는 예다.

perf stat -d python3 fluster.py run -d GStreamer-H.264-V4L2SL-Gst1.0 -ts JVT-AVC_V1 -tv AUD_MW_E -j1

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
711708695 instructions:u           # 0.81 insn per cycle
10581935 branches:u                # 1.358 M/sec
6871144 branch-misses:u            # 64.93% of all branches
281716547 L1-dcache-loads:u         # 36.144 M/sec
9019581 L1-dcache-load-misses:u     # 3.20% of all L1-dcache accesses
<not supported> LLC-loads:u
<not supported> LLC-load-misses:u

11.180830431 seconds time elapsed
1.502318000 seconds user
6.377221000 seconds sys

사용 가능한 event와 metric은 실행하는 hardware와 kernel configuration에 따라 달라진다.

v4l2-compliance로 driver 검증

145-160

V4L2 API 준수 여부는 v4l-utils userspace tool suite의 v4l2-compliance로 검사한다.

# topology detail and validation
v4l2-compliance -M /dev/mediaX --verbose

# full compliance for all devices in topology
v4l2-compliance -m /dev/mediaX

외부 video signal 수신 문제

162-180

Driver에 vidioc_log_status callback을 구현하면 v4l2-ctl --log-status 호출 때 현재 상태를 kernel log로 출력할 수 있다. TV, S-Video, HDMI처럼 외부라 예측하기 어려운 video signal 수신 문제에 특히 유용하다. Driver가 동작을 통제하는 camera sensor input에는 상대적으로 덜 유용하다.

.vidioc_log_status = v4l2_ctrl_log_status,