Linux kernel debugging 안내 | Linux 6.18.37

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

1. 요약·해설

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

General guide와 subsystem guide

index.rst:4-34

일반 guide는 driver 개발 중 instrumentation, userspace에서 사용할 tracing, GDB·KGDB를 다룬다. Subsystem-specific guide는 media처럼 자체 debug parameter, compliance tool과 tracepoint를 가진 영역의 절차를 추가한다.

관찰 조건부터 정한다

index.rst:35-80

Target에 제한적으로만 접근할 수 있으면 persistent log, netconsole, pstore와 remote tracing을 검토한다.
Root 권한이 없으면 ftrace control, perf_event_paranoid, debugfs mount와 symbol 접근이 제한될 수 있다.
Timing-sensitive race는 printk가 재현을 없애거나 바꿀 수 있으므로 low-overhead tracepoint, ftrace와 hardware tracing을 우선한다.
Crash 전에 system이 멈추면 KGDB·KDB, crash dump와 sanitizer report를 함께 사용한다.

도구를 먼저 고르는 대신 재현성, 관찰 가능한 state, 성능 교란 허용 범위와 target access를 적은 뒤 가장 적은 영향을 주는 수단부터 적용한다.

2. 영어 원문 전체

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

원문 전체 펼치기

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

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

4 Debugging advice for Linux Kernel developers

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

7 general guides

8 --------------

10 .. toctree::

11 :maxdepth: 1

13 driver_development_debugging_guide

14 gdb-kernel-debugging

15 kgdb

16 userspace_debugging_guide

18 .. only:: subproject and html

20 subsystem specific guides

21 -------------------------

23 .. toctree::

24 :maxdepth: 1

26 media_specific_debugging_guide

28 .. only:: subproject and html

30 Indices

31 =======

33 * :ref:`genindex`

35 General debugging advice

36 ========================

38 Depending on the issue, a different set of tools is available to track down the

39 problem or even to realize whether there is one in the first place.

41 As a first step you have to figure out what kind of issue you want to debug.

42 Depending on the answer, your methodology and choice of tools may vary.

44 Do I need to debug with limited access?

45 ---------------------------------------

47 Do you have limited access to the machine or are you unable to stop the running

48 execution?

50 In this case your debugging capability depends on built-in debugging support of

51 provided distribution kernel.

52 The :doc:`/process/debugging/userspace_debugging_guide` provides a brief

53 overview over a range of possible debugging tools in that situation. You can

54 check the capability of your kernel, in most cases, by looking into config file

55 within the /boot directory.

57 Do I have root access to the system?

58 ------------------------------------

60 Are you easily able to replace the module in question or to install a new

61 kernel?

63 In that case your range of available tools is a lot bigger, you can find the

64 tools in the :doc:`/process/debugging/driver_development_debugging_guide`.

66 Is timing a factor?

67 -------------------

69 It is important to understand if the problem you want to debug manifests itself

70 consistently (i.e. given a set of inputs you always get the same, incorrect

71 output), or inconsistently. If it manifests itself inconsistently, some timing

72 factor might be at play. If inserting delays into the code does change the

73 behavior, then quite likely timing is a factor.

75 When timing does alter the outcome of the code execution using a simple

76 printk() for debugging purposes may not work, a similar alternative is to use

77 trace_printk() , which logs the debug messages to the trace file instead of the

78 kernel log.

3. 한국어 전문 번역

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

Linux kernel 개발자를 위한 debugging 조언

1-31

일반 debugging 안내에는 driver 개발 debugging guide, GDB kernel debugging, KGDB, userspace debugging guide가 포함된다. Subsystem별 안내에는 media debugging guide가 포함되며 HTML 문서에서는 전체 색인도 제공한다.

일반적인 debugging 접근

33-43

문제의 종류에 따라 문제를 추적하거나 애초에 문제가 존재하는지 확인하는 데 사용할 수 있는 tool 집합이 달라진다. 첫 단계는 debugging할 문제의 종류를 결정하는 것이다. 답에 따라 방법론과 tool 선택이 달라진다.

접근 권한에 따른 tool 선택

45-63

Machine 접근이 제한되어 있거나 실행 중인 system을 멈출 수 없다면 debugging 가능 범위는 distribution kernel에 built-in된 debugging 지원에 달려 있다. /process/debugging/userspace_debugging_guide는 이 상황에서 사용할 수 있는 tool을 간략히 설명한다. 대부분 /boot directory의 config file을 보면 현재 kernel의 기능을 확인할 수 있다.

Root access가 있고 문제의 module을 쉽게 교체하거나 새 kernel을 설치할 수 있다면 사용할 수 있는 tool 범위가 훨씬 넓어진다. 해당 tool은 /process/debugging/driver_development_debugging_guide에서 확인한다.

Timing이 문제에 영향을 주는가

65-80

문제가 같은 입력에서 항상 같은 잘못된 출력을 내며 일관되게 나타나는지, 아니면 불규칙하게 나타나는지를 구분해야 한다. 불규칙하다면 timing 요소가 개입했을 수 있다. Code에 delay를 넣었을 때 동작이 바뀐다면 timing 문제일 가능성이 높다.

Timing이 실행 결과를 바꾸는 경우에는 단순한 printk() debugging이 동작하지 않을 수 있다. 비슷한 대안으로 trace_printk()를 사용할 수 있으며, debug message를 kernel log 대신 trace file에 기록한다.