요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0
====================
ACPI CA Debug Output
====================
The ACPI CA can generate debug output. This document describes how to use this
facility.
Compile-time configuration
==========================
The ACPI CA debug output is globally enabled by CONFIG_ACPI_DEBUG. If this
config option is not set, the debug messages are not even built into the kernel.
Boot- and run-time configuration
================================
When CONFIG_ACPI_DEBUG=y, you can select the component and level of messages
you're interested in. At boot-time, use the acpi.debug_layer and
acpi.debug_level kernel command line options. After boot, you can use the
debug_layer and debug_level files in /sys/module/acpi/parameters/ to control
the debug messages.
debug_layer (component)
=======================
The "debug_layer" is a mask that selects components of interest, e.g., a
specific part of the ACPI interpreter. To build the debug_layer bitmask, look
for the "#define _COMPONENT" in an ACPI source file.
You can set the debug_layer mask at boot-time using the acpi.debug_layer
command line argument, and you can change it after boot by writing values
to /sys/module/acpi/parameters/debug_layer.
The possible components are defined in include/acpi/acoutput.h.
Reading /sys/module/acpi/parameters/debug_layer shows the supported mask values::
ACPI_UTILITIES 0x00000001
ACPI_HARDWARE 0x00000002
ACPI_EVENTS 0x00000004
ACPI_TABLES 0x00000008
ACPI_NAMESPACE 0x00000010
ACPI_PARSER 0x00000020
ACPI_DISPATCHER 0x00000040
ACPI_EXECUTER 0x00000080
ACPI_RESOURCES 0x00000100
ACPI_CA_DEBUGGER 0x00000200
ACPI_OS_SERVICES 0x00000400
ACPI_CA_DISASSEMBLER 0x00000800
ACPI_COMPILER 0x00001000
ACPI_TOOLS 0x00002000
debug_level
===========
The "debug_level" is a mask that selects different types of messages, e.g.,
those related to initialization, method execution, informational messages, etc.
To build debug_level, look at the level specified in an ACPI_DEBUG_PRINT()
statement.
The ACPI interpreter uses several different levels, but the Linux
ACPI core and ACPI drivers generally only use ACPI_LV_INFO.
You can set the debug_level mask at boot-time using the acpi.debug_level
command line argument, and you can change it after boot by writing values
to /sys/module/acpi/parameters/debug_level.
The possible levels are defined in include/acpi/acoutput.h. Reading
/sys/module/acpi/parameters/debug_level shows the supported mask values,
currently these::
ACPI_LV_INIT 0x00000001
ACPI_LV_DEBUG_OBJECT 0x00000002
ACPI_LV_INFO 0x00000004
ACPI_LV_INIT_NAMES 0x00000020
ACPI_LV_PARSE 0x00000040
ACPI_LV_LOAD 0x00000080
ACPI_LV_DISPATCH 0x00000100
ACPI_LV_EXEC 0x00000200
ACPI_LV_NAMES 0x00000400
ACPI_LV_OPREGION 0x00000800
ACPI_LV_BFIELD 0x00001000
ACPI_LV_TABLES 0x00002000
ACPI_LV_VALUES 0x00004000
ACPI_LV_OBJECTS 0x00008000
ACPI_LV_RESOURCES 0x00010000
ACPI_LV_USER_REQUESTS 0x00020000
ACPI_LV_PACKAGE 0x00040000
ACPI_LV_ALLOCATIONS 0x00100000
ACPI_LV_FUNCTIONS 0x00200000
ACPI_LV_OPTIMIZATIONS 0x00400000
ACPI_LV_MUTEX 0x01000000
ACPI_LV_THREADS 0x02000000
ACPI_LV_IO 0x04000000
ACPI_LV_INTERRUPTS 0x08000000
ACPI_LV_AML_DISASSEMBLE 0x10000000
ACPI_LV_VERBOSE_INFO 0x20000000
ACPI_LV_FULL_TABLES 0x40000000
ACPI_LV_EVENTS 0x80000000
Examples
========
For example, drivers/acpi/acpica/evxfevnt.c contains this::
#define _COMPONENT ACPI_EVENTS
...
ACPI_DEBUG_PRINT((ACPI_DB_INIT, "ACPI mode disabled\n"));
To turn on this message, set the ACPI_EVENTS bit in acpi.debug_layer
and the ACPI_LV_INIT bit in acpi.debug_level. (The ACPI_DEBUG_PRINT
statement uses ACPI_DB_INIT, which is a macro based on the ACPI_LV_INIT
definition.)
Enable all AML "Debug" output (stores to the Debug object while interpreting
AML) during boot::
acpi.debug_layer=0xffffffff acpi.debug_level=0x2
Enable all ACPI hardware-related messages::
acpi.debug_layer=0x2 acpi.debug_level=0xffffffff
Enable all ACPI_DB_INFO messages after boot::
# echo 0x4 > /sys/module/acpi/parameters/debug_level
Show all valid component values::
# cat /sys/module/acpi/parameters/debug_layer
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
빌드·부팅·런타임 구성
1-23ACPI CA(ACPI Component Architecture)는 디버그 출력을 생성할 수 있으며, 이 문서는 해당 기능을 활성화하고 원하는 메시지만 선택하는 방법을 설명한다.
전체 디버그 출력 기능은 빌드 시 `CONFIG_ACPI_DEBUG`로 활성화한다. 이 설정을 선택하지 않으면 디버그 메시지 코드 자체가 커널에 빌드되지 않으므로, 부팅 인수나 sysfs 값을 나중에 설정해도 출력을 얻을 수 없다.
`CONFIG_ACPI_DEBUG=y`인 커널에서는 관심 있는 구성요소와 메시지 수준을 각각 마스크로 선택한다. 부팅 시에는 커널 명령행의 `acpi.debug_layer`와 `acpi.debug_level`을 사용하고, 부팅 뒤에는 `/sys/module/acpi/parameters/` 아래의 `debug_layer`와 `debug_level` 파일을 읽거나 써서 제어한다.
빌드 시 포함 여부와 부팅 전후의 선택 인터페이스를 구분한다.
메시지가 실제 출력되려면 빌드 조건과 두 마스크가 모두 충족되어야 한다.
.. SPDX-License-Identifier: GPL-2.0
====================
ACPI CA Debug Output
====================
The ACPI CA can generate debug output. This document describes how to use this
facility.
Compile-time configuration
==========================
The ACPI CA debug output is globally enabled by CONFIG_ACPI_DEBUG. If this
config option is not set, the debug messages are not even built into the kernel.
Boot- and run-time configuration
================================
When CONFIG_ACPI_DEBUG=y, you can select the component and level of messages
you're interested in. At boot-time, use the acpi.debug_layer and
acpi.debug_level kernel command line options. After boot, you can use the
debug_layer and debug_level files in /sys/module/acpi/parameters/ to control
the debug messages.debug_layer 구성요소 마스크
24-54`debug_layer`는 ACPI 인터프리터의 특정 부분처럼 관심 있는 구성요소를 선택하는 비트 마스크다. 어떤 소스 파일의 메시지를 활성화할지 판단하려면 해당 ACPI 소스 파일에서 `#define _COMPONENT`를 찾고 그 값에 대응하는 비트를 마스크에 포함한다.
부팅 시에는 `acpi.debug_layer=<mask>` 커널 명령행 인수로 설정한다. 부팅 후에는 `/sys/module/acpi/parameters/debug_layer`에 값을 기록해 바꿀 수 있으며, 같은 파일을 읽으면 현재 커널이 지원하는 마스크 값 목록이 표시된다.
가능한 구성요소는 `include/acpi/acoutput.h`에 정의된다. 여러 구성요소를 동시에 보고 싶다면 아래 값들을 비트 OR로 결합하며, 특정 파일의 `_COMPONENT`가 선택되지 않으면 그 파일의 디버그 호출은 수준 마스크가 맞더라도 출력되지 않는다.
sysfs에서 확인할 수 있는 14개 구성요소 비트와 원문의 16진수 값을 보존했다.
소스의 구성요소 정의에서 실제 설정값을 만드는 절차다.
debug_layer (component)
=======================
The "debug_layer" is a mask that selects components of interest, e.g., a
specific part of the ACPI interpreter. To build the debug_layer bitmask, look
for the "#define _COMPONENT" in an ACPI source file.
You can set the debug_layer mask at boot-time using the acpi.debug_layer
command line argument, and you can change it after boot by writing values
to /sys/module/acpi/parameters/debug_layer.
The possible components are defined in include/acpi/acoutput.h.
Reading /sys/module/acpi/parameters/debug_layer shows the supported mask values::
ACPI_UTILITIES 0x00000001
ACPI_HARDWARE 0x00000002
ACPI_EVENTS 0x00000004
ACPI_TABLES 0x00000008
ACPI_NAMESPACE 0x00000010
ACPI_PARSER 0x00000020
ACPI_DISPATCHER 0x00000040
ACPI_EXECUTER 0x00000080
ACPI_RESOURCES 0x00000100
ACPI_CA_DEBUGGER 0x00000200
ACPI_OS_SERVICES 0x00000400
ACPI_CA_DISASSEMBLER 0x00000800
ACPI_COMPILER 0x00001000
ACPI_TOOLS 0x00002000
debug_level 메시지 수준
55-72`debug_level`은 초기화, 메서드 실행, 정보 메시지 등 서로 다른 유형의 메시지를 선택하는 비트 마스크다. 특정 `ACPI_DEBUG_PRINT()` 호출을 활성화하려면 호출문에 지정된 수준을 확인하고 그 수준에 대응하는 비트를 마스크에 포함한다.
ACPI 인터프리터는 여러 수준을 폭넓게 사용하지만, Linux ACPI 코어와 ACPI 드라이버는 일반적으로 `ACPI_LV_INFO`만 사용한다. 따라서 드라이버의 일반 정보 메시지를 찾는 경우에는 먼저 `0x00000004` 비트를 확인하는 것이 유용하다.
부팅 시에는 `acpi.debug_level=<mask>` 명령행 인수로 설정하고, 부팅 뒤에는 `/sys/module/acpi/parameters/debug_level`에 값을 써서 변경한다. 가능한 수준은 `include/acpi/acoutput.h`에 정의되며, sysfs 파일을 읽으면 현재 지원되는 값을 확인할 수 있다.
두 마스크는 서로 대체 관계가 아니라 메시지 출력을 함께 제한하는 두 축이다.
관심 있는 디버그 호출에서 수준 마스크를 역으로 찾는다.
debug_level
===========
The "debug_level" is a mask that selects different types of messages, e.g.,
those related to initialization, method execution, informational messages, etc.
To build debug_level, look at the level specified in an ACPI_DEBUG_PRINT()
statement.
The ACPI interpreter uses several different levels, but the Linux
ACPI core and ACPI drivers generally only use ACPI_LV_INFO.
You can set the debug_level mask at boot-time using the acpi.debug_level
command line argument, and you can change it after boot by writing values
to /sys/module/acpi/parameters/debug_level.
The possible levels are defined in include/acpi/acoutput.h. Reading
/sys/module/acpi/parameters/debug_level shows the supported mask values,
currently these::지원되는 debug_level 비트
73-102현재 지원되는 `debug_level` 값은 아래와 같다. 각 항목은 독립 비트이므로 필요한 수준들을 비트 OR로 결합할 수 있다. `ACPI_LV_INIT`, `ACPI_LV_DEBUG_OBJECT`, `ACPI_LV_INFO`는 낮은 비트에 있고, 상세 추적과 이벤트 범주는 상위 비트에 배치된다.
값 사이에는 정의되지 않은 비트 간격이 있으므로 항목의 나열 순서를 단순한 연속 인덱스로 해석해서는 안 된다. 반드시 표의 실제 16진수 마스크를 사용해야 하며, `0xffffffff`는 정의된 수준과 예약 비트를 포함한 모든 비트를 설정하는 진단용 값이다.
초기화부터 객체·리소스 처리까지의 앞쪽 14개 비트다.
리소스 처리부터 상세 이벤트 추적까지의 뒤쪽 14개 비트다.
ACPI_LV_INIT 0x00000001
ACPI_LV_DEBUG_OBJECT 0x00000002
ACPI_LV_INFO 0x00000004
ACPI_LV_INIT_NAMES 0x00000020
ACPI_LV_PARSE 0x00000040
ACPI_LV_LOAD 0x00000080
ACPI_LV_DISPATCH 0x00000100
ACPI_LV_EXEC 0x00000200
ACPI_LV_NAMES 0x00000400
ACPI_LV_OPREGION 0x00000800
ACPI_LV_BFIELD 0x00001000
ACPI_LV_TABLES 0x00002000
ACPI_LV_VALUES 0x00004000
ACPI_LV_OBJECTS 0x00008000
ACPI_LV_RESOURCES 0x00010000
ACPI_LV_USER_REQUESTS 0x00020000
ACPI_LV_PACKAGE 0x00040000
ACPI_LV_ALLOCATIONS 0x00100000
ACPI_LV_FUNCTIONS 0x00200000
ACPI_LV_OPTIMIZATIONS 0x00400000
ACPI_LV_MUTEX 0x01000000
ACPI_LV_THREADS 0x02000000
ACPI_LV_IO 0x04000000
ACPI_LV_INTERRUPTS 0x08000000
ACPI_LV_AML_DISASSEMBLE 0x10000000
ACPI_LV_VERBOSE_INFO 0x20000000
ACPI_LV_FULL_TABLES 0x40000000
ACPI_LV_EVENTS 0x80000000
마스크 조합 예제
103-132예를 들어 `drivers/acpi/acpica/evxfevnt.c`는 `_COMPONENT`를 `ACPI_EVENTS`로 정의하고, `ACPI_DEBUG_PRINT((ACPI_DB_INIT, "ACPI mode disabled\n"))` 호출을 포함한다. 이 메시지를 보려면 구성요소 마스크에서 `ACPI_EVENTS` 비트를, 수준 마스크에서 `ACPI_LV_INIT` 비트를 모두 설정해야 한다.
호출문에는 `ACPI_DB_INIT`가 사용되지만 실제 수준 비트는 그 매크로의 기반 정의인 `ACPI_LV_INIT`이다. 즉 소스에서 보이는 `ACPI_DB_*` 이름과 sysfs가 표시하는 `ACPI_LV_*` 마스크의 대응 관계를 따라가야 한다.
하나의 디버그 호출이 layer와 level 두 조건을 만족하는 과정을 보여준다.
부팅 중 AML `Debug` 객체에 저장되는 모든 출력을 보려면 `acpi.debug_layer=0xffffffff acpi.debug_level=0x2`를 사용한다. 여기서 level `0x2`는 `ACPI_LV_DEBUG_OBJECT`다.
모든 ACPI 하드웨어 관련 메시지를 보려면 `acpi.debug_layer=0x2 acpi.debug_level=0xffffffff`를 사용한다. layer `0x2`는 `ACPI_HARDWARE`이고 level의 모든 비트를 허용한다.
부팅 뒤 모든 `ACPI_DB_INFO` 메시지를 활성화하려면 `echo 0x4 > /sys/module/acpi/parameters/debug_level`을 실행한다. 유효한 구성요소 값을 확인하려면 `cat /sys/module/acpi/parameters/debug_layer`를 실행한다.
원문의 네 가지 목적과 정확한 부팅 인수·런타임 명령을 대응시켰다.
처음에는 필요한 축을 넓게 열고 결과를 보며 구성요소와 수준을 단계적으로 줄인다.
Examples
========
For example, drivers/acpi/acpica/evxfevnt.c contains this::
#define _COMPONENT ACPI_EVENTS
...
ACPI_DEBUG_PRINT((ACPI_DB_INIT, "ACPI mode disabled\n"));
To turn on this message, set the ACPI_EVENTS bit in acpi.debug_layer
and the ACPI_LV_INIT bit in acpi.debug_level. (The ACPI_DEBUG_PRINT
statement uses ACPI_DB_INIT, which is a macro based on the ACPI_LV_INIT
definition.)
Enable all AML "Debug" output (stores to the Debug object while interpreting
AML) during boot::
acpi.debug_layer=0xffffffff acpi.debug_level=0x2
Enable all ACPI hardware-related messages::
acpi.debug_layer=0x2 acpi.debug_level=0xffffffff
Enable all ACPI_DB_INFO messages after boot::
# echo 0x4 > /sys/module/acpi/parameters/debug_level
Show all valid component values::
# cat /sys/module/acpi/parameters/debug_layer
요약·해설
debug.rst:1-132ACPI CA 디버그 출력은 먼저 `CONFIG_ACPI_DEBUG=y`로 커널에 포함해야 하며, 그 뒤 `debug_layer`로 구성요소를, `debug_level`로 메시지 유형을 선택한다. 두 마스크가 모두 일치해야 해당 메시지가 출력된다.
부팅 시에는 `acpi.debug_layer`와 `acpi.debug_level`을 커널 명령행에 지정하고, 부팅 후에는 `/sys/module/acpi/parameters/`의 파일로 조회·변경한다. 구성요소는 소스의 `_COMPONENT`, 수준은 `ACPI_DEBUG_PRINT()`의 `ACPI_DB_*` 인수에서 찾는다.
진단 초기에는 한 축을 `0xffffffff`로 열어 메시지를 찾을 수 있지만, 장기간 사용하려면 실제 비트만 조합해 출력량을 줄이는 편이 좋다. 모든 비트값과 경로는 원문 표기 그대로 사용해야 한다.
빌드부터 최소 마스크 적용까지의 전체 작업 순서다.