The AML Debugger | Linux 6.18.37

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

1. 요약·해설

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

요약·해설

aml-debugger.rst:1-75

AML debugger는 kernel ACPICA debugger와 `acpi_dbg` module, debugfs, userspace `acpidbg` client로 구성된다. 두 CONFIG option을 켜고 `make acpi`로 tool을 만든 뒤 정해진 순서로 runtime을 시작한다.

Interactive session은 `help`와 ACPICA Chapter 12를 참고하고 client를 먼저 종료한 뒤 module을 unload한다. `-b` batch mode는 namespace dump 같은 진단을 test automation에 넣을 때 사용한다.

AML debugger 작업 수명

Kernel CONFIG와 tool builddebugfs mount와 module loadInteractive command 실행Client 종료 후 module unload필요하면 batch mode로 자동화

Build·start·inspect·stop·automation의 전체 순서다.

2. 영어 원문 전체

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

원문 전체 펼치기

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

2 .. include:: <isonum.txt>

4 ================

5 The AML Debugger

6 ================

8 :Copyright: |copy| 2016, Intel Corporation

9 :Author: Lv Zheng <[email protected]>

12 This document describes the usage of the AML debugger embedded in the Linux

13 kernel.

15 1. Build the debugger

16 =====================

18 The following kernel configuration items are required to enable the AML

19 debugger interface from the Linux kernel::

21 CONFIG_ACPI_DEBUGGER=y

22 CONFIG_ACPI_DEBUGGER_USER=m

24 The userspace utilities can be built from the kernel source tree using

25 the following commands::

27 $ cd tools

28 $ make acpi

30 The resultant userspace tool binary is then located at::

32 tools/power/acpi/acpidbg

34 It can be installed to system directories by running "make install" (as a

35 sufficiently privileged user).

37 2. Start the userspace debugger interface

38 =========================================

40 After booting the kernel with the debugger built-in, the debugger can be

41 started by using the following commands::

43 # mount -t debugfs none /sys/kernel/debug

44 # modprobe acpi_dbg

45 # tools/power/acpi/acpidbg

47 That spawns the interactive AML debugger environment where you can execute

48 debugger commands.

50 The commands are documented in the "ACPICA Overview and Programmer Reference"

51 that can be downloaded from

53 https://acpica.org/documentation

55 The detailed debugger commands reference is located in Chapter 12 "ACPICA

56 Debugger Reference". The "help" command can be used for a quick reference.

58 3. Stop the userspace debugger interface

59 ========================================

61 The interactive debugger interface can be closed by pressing Ctrl+C or using

62 the "quit" or "exit" commands. When finished, unload the module with::

64 # rmmod acpi_dbg

66 The module unloading may fail if there is an acpidbg instance running.

68 4. Run the debugger in a script

69 ===============================

71 It may be useful to run the AML debugger in a test script. "acpidbg" supports

72 this in a special "batch" mode. For example, the following command outputs

73 the entire ACPI namespace::

75 # acpidbg -b "namespace"

3. 한국어 전문 번역

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

Kernel 내장 AML debugger

1-13

이 문서는 Linux kernel에 내장된 AML debugger의 사용법을 설명한다. AML(ACPI Machine Language) method와 namespace를 interactive하게 조사하여 ACPI table 동작, control method evaluation과 firmware 문제를 진단하는 도구다.

Debugger는 kernel-side interface와 userspace `acpidbg` client로 나뉜다. Build configuration, debugfs mount, module load, interactive command, 종료와 batch mode를 순서대로 준비해야 한다.

이 도구는 firmware image 자체를 고치는 편집기가 아니다. 실행 중인 kernel의 ACPICA 환경에서 namespace를 조사하고 AML method를 평가하므로, hardware state를 바꿀 수 있는 method를 시험할 때는 해당 method의 side effect를 먼저 확인해야 한다.

AML debugger 구성

Kernel ACPI debugger 기능`acpi_dbg` userspace interface moduledebugfs transport`tools/power/acpi/acpidbg` clientAML namespace·method debug command

Kernel debugger와 userspace client가 interactive environment를 만든다.

.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>

================
The AML Debugger
================

:Copyright: |copy| 2016, Intel Corporation
:Author: Lv Zheng <[email protected]>


This document describes the usage of the AML debugger embedded in the Linux
kernel.

Kernel 설정과 userspace tool build

14-32

AML debugger interface를 활성화하려면 kernel configuration에 `CONFIG_ACPI_DEBUGGER=y`와 `CONFIG_ACPI_DEBUGGER_USER=m`이 필요하다. 전자는 ACPICA debugger core를 kernel에 포함하고 후자는 userspace interface를 module로 build한다.

Userspace utility는 kernel source tree의 `tools` directory에서 `make acpi`로 build한다. 결과 binary는 `tools/power/acpi/acpidbg`에 생성된다.

충분한 권한을 가진 user가 `make install`을 실행하면 system directory에 설치할 수 있다. 설치하지 않은 경우 이후 예제처럼 source tree 안의 binary path를 직접 실행한다.

CONFIG_ACPI_DEBUGGER=y
CONFIG_ACPI_DEBUGGER_USER=m

$ cd tools
$ make acpi

# result: tools/power/acpi/acpidbg

AML debugger build 항목

항목값·command결과

Debugger core`CONFIG_ACPI_DEBUGGER=y`Kernel에 AML debugger 포함

Userspace interface`CONFIG_ACPI_DEBUGGER_USER=m``acpi_dbg` module 생성

Tool build`cd tools && make acpi``tools/power/acpi/acpidbg` 생성

Install`make install`System directory에 utility 설치

Kernel과 userspace component를 각각 활성화·생성한다.

Build 순서

두 CONFIG option 설정Kernel과 module buildKernel source의 `tools`로 이동`make acpi` 실행`acpidbg` binary 확인

Kernel configuration부터 client binary 생성까지의 흐름이다.


1. Build the debugger
=====================

The following kernel configuration items are required to enable the AML
debugger interface from the Linux kernel::

   CONFIG_ACPI_DEBUGGER=y
   CONFIG_ACPI_DEBUGGER_USER=m

The userspace utilities can be built from the kernel source tree using
the following commands::

   $ cd tools
   $ make acpi

The resultant userspace tool binary is then located at::

   tools/power/acpi/acpidbg

debugfs·module·interactive session 시작

33-53

Debugger가 포함된 kernel로 boot한 뒤 debugfs를 `/sys/kernel/debug`에 mount하고 `acpi_dbg` module을 load한 다음 `acpidbg`를 실행한다. 세 단계가 모두 준비되어야 userspace client와 kernel debugger가 통신할 수 있다.

# mount -t debugfs none /sys/kernel/debug
# modprobe acpi_dbg
# tools/power/acpi/acpidbg

실행하면 debugger command를 입력할 수 있는 interactive AML debugger environment가 열린다. Command의 공식 설명은 `https://acpica.org/documentation`에서 받을 수 있는 ACPICA Overview and Programmer Reference에 있다.

상세 command reference는 Chapter 12 `ACPICA Debugger Reference`이며, session 안에서 `help` command를 사용하면 빠른 참고 목록을 볼 수 있다.

Interactive session 시작

Debugger-enabled kernel로 bootdebugfs를 `/sys/kernel/debug`에 mount`modprobe acpi_dbg``acpidbg` 실행Interactive debugger command 입력

Runtime interface를 순서대로 열어 debugger prompt에 도달한다.

Command reference

Reference위치·command

ACPICA documentationhttps://acpica.org/documentation

상세 chapterChapter 12 `ACPICA Debugger Reference`

Quick reference`help` command

상세 문서와 session 내 quick help의 위치다.


It can be installed to system directories by running "make install" (as a
sufficiently privileged user).

2. Start the userspace debugger interface
=========================================

After booting the kernel with the debugger built-in, the debugger can be
started by using the following commands::

   # mount -t debugfs none /sys/kernel/debug
   # modprobe acpi_dbg
   # tools/power/acpi/acpidbg

That spawns the interactive AML debugger environment where you can execute
debugger commands.

The commands are documented in the "ACPICA Overview and Programmer Reference"
that can be downloaded from

https://acpica.org/documentation

Session 종료와 module unload

54-64

Interactive interface는 `Ctrl+C`를 누르거나 `quit`, `exit` command를 실행해 닫을 수 있다. Client process가 완전히 끝난 뒤 `rmmod acpi_dbg`로 userspace interface module을 unload한다.

실행 중인 `acpidbg` instance가 남아 있으면 module unload가 실패할 수 있다. 여러 terminal이나 test process에서 client가 실행 중인지 확인하고 모든 session을 먼저 종료해야 한다.

Debugger 종료 순서

`Ctrl+C`, `quit` 또는 `exit``acpidbg` process 종료 확인다른 running instance 확인`rmmod acpi_dbg`Unload 실패 시 남은 client 재확인

Client reference를 해제한 뒤 module을 내리는 안전한 순서다.

종료 방법

대상방법주의

Current session`Ctrl+C`Terminal interrupt

Current session`quit` 또는 `exit`Debugger command

Kernel module`rmmod acpi_dbg`Running client가 없어야 함

Interactive session과 kernel module의 종료 command를 구분한다.


The detailed debugger commands reference is located in Chapter 12 "ACPICA
Debugger Reference".  The "help" command can be used for a quick reference.

3. Stop the userspace debugger interface
========================================

The interactive debugger interface can be closed by pressing Ctrl+C or using
the "quit" or "exit" commands.  When finished, unload the module with::

   # rmmod acpi_dbg

Script용 batch mode

65-75

자동 test script에서 AML debugger를 사용하려면 `acpidbg`의 special batch mode를 이용한다. `-b` 뒤의 문자열을 debugger command로 실행하고 interactive input 없이 결과를 standard output으로 내보낼 수 있다.

예제 `acpidbg -b "namespace"`는 전체 ACPI namespace를 출력한다. Script는 exit status와 output을 함께 저장해 firmware revision 간 namespace 차이 또는 regression을 비교할 수 있다.

Batch mode도 kernel debugger, debugfs와 `acpi_dbg` module이 준비되어 있어야 한다. 병렬 test가 module unload나 shared debugger state와 충돌하지 않도록 session 수명과 cleanup을 관리해야 한다.

# acpidbg -b "namespace"

Batch namespace dump

Debugger runtime 준비Script가 `acpidbg -b "namespace"` 실행Kernel debugger가 namespace 열거Output과 exit status 수집Baseline 또는 firmware revision과 비교

Script가 debugger command를 비대화식으로 실행하는 경로다.


The module unloading may fail if there is an acpidbg instance running.

4. Run the debugger in a script
===============================

It may be useful to run the AML debugger in a test script. "acpidbg" supports
this in a special "batch" mode.  For example, the following command outputs
the entire ACPI namespace::

   # acpidbg -b "namespace"