Documentation/firmware-guide/acpi/aml-debugger.rst

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