1.. SPDX-License-Identifier: GPL-2.0
2.. include:: <isonum.txt>
3
4================
5The AML Debugger
6================
7
8:Copyright: |copy| 2016, Intel Corporation
9:Author: Lv Zheng <lv.zheng@intel.com>
10
11
12This document describes the usage of the AML debugger embedded in the Linux
13kernel.
14
151. Build the debugger
16=====================
17
18The following kernel configuration items are required to enable the AML
19debugger interface from the Linux kernel::
20
21   CONFIG_ACPI_DEBUGGER=y
22   CONFIG_ACPI_DEBUGGER_USER=m
23
24The userspace utilities can be built from the kernel source tree using
25the following commands::
26
27   $ cd tools
28   $ make acpi
29
30The resultant userspace tool binary is then located at::
31
32   tools/power/acpi/acpidbg
33
34It can be installed to system directories by running "make install" (as a
35sufficiently privileged user).
36
372. Start the userspace debugger interface
38=========================================
39
40After booting the kernel with the debugger built-in, the debugger can be
41started by using the following commands::
42
43   # mount -t debugfs none /sys/kernel/debug
44   # modprobe acpi_dbg
45   # tools/power/acpi/acpidbg
46
47That spawns the interactive AML debugger environment where you can execute
48debugger commands.
49
50The commands are documented in the "ACPICA Overview and Programmer Reference"
51that can be downloaded from
52
53https://acpica.org/documentation
54
55The detailed debugger commands reference is located in Chapter 12 "ACPICA
56Debugger Reference".  The "help" command can be used for a quick reference.
57
583. Stop the userspace debugger interface
59========================================
60
61The interactive debugger interface can be closed by pressing Ctrl+C or using
62the "quit" or "exit" commands.  When finished, unload the module with::
63
64   # rmmod acpi_dbg
65
66The module unloading may fail if there is an acpidbg instance running.
67
684. Run the debugger in a script
69===============================
70
71It may be useful to run the AML debugger in a test script. "acpidbg" supports
72this in a special "batch" mode.  For example, the following command outputs
73the entire ACPI namespace::
74
75   # acpidbg -b "namespace"
76