Features Download
From: Thomas Renninger <trenn <at> suse.de>
Subject: Documentation - How to debug ACPI Problems
Newsgroups: gmane.linux.acpi.devel
Date: Wednesday 6th June 2007 14:26:48 UTC (over 10 years ago)

I made up a little How-To for what I find out is nice to debug ACPI

Any enhancements, corrections, etc. are very much appreciated.

I'd like to have a final version in the Documentation section.

IMO the size and complexity of ACPI justifies to start an own
Documentation/acpi directory.
Not sure whether thinkpad-acpi.txt (are there other related How-Tos?)
should be added there as it got split out of drivers/acpi recently.

Not sure whether it's necessary to send a patch at all for a new
Documentation file, for now the plain file is easier to read and comment



How to debug ACPI Problems

Thomas Renninger , 2007
Copyright (C) 2007 SUSE Linux GmbH

1. Introduction

1.1. General Info
- - - - - - - -

Please refer to the latest ACPI spec for general ACPI information:

ACPI is required by most recent x86, x86_64 and IA64 architecture based

In general ACPI tables provide information from the BIOS to the OS.
There are ACPI tables (DSDT and SSDTs), written in the ACPI Source
Language (ASL) which include byte code (similar to Java byte code) that
interpreted by the OS. The kernel makes use of provided BIOS functions
declared and described there by interpreting them to setup and access
different hardware.

There exist two compilers/interpreters for ASL code, one from Microsoft and
one from Intel. The Intel code has an Open Source license. The software
is called ACPICA. It includes the code for disassembling DSDT tables,
(re-)compiling them, parsing several ACPI tables and interpreting ACPI
Language (AML, the compiled ASL..). The code is used to provide several
userspace tools, but large parts are also contributed to the linux kernel
other OSs.
drivers/acpi/*.c currently is Linux code implementing most parts of the
spec, everything in the directories below, gets synced with the ACPICA

1.2. Useful Userspace Tools for Table Playing
- - - - - - - - - - - - - - - - - - - - - - -

The ACPI tables of your system can be extracted with the acpidump tool:
in the latest pmutils package from here:

acpixtract, iasl, acpiexec can be found in the ACPICA sources:

You can now:
acpidump >acpidump       # cp your ACPI tables from memory to disk
acpixtract -a acpidump   # extract them into raw, single tables
iasl -d TABLE.dat        # disassemble/parse a specific table
iasl -sa DSDT.dsl        # e.g. recompile a modified, disassembled DSDT for
                           initramfs inclusion (see later)
acpiexec DSDT.dat        # parse, interpret and load a DSDT in userspace

The latter can sometimes be very useful to debug buggy DSDTs in userspace.
It provides a debug shell which e.g. offers execution of specific ACPI
functions, increase of debug output and more.

2. Overriding DSDT

The DSDT (there is a patch also for SSDTs) can be overridden by the user.
The tables get copied to RAM when booting and the kernel can override them
alternative tables at early boot time.

In history people used to override their DSDT to workaround BIOS or even
bugs. This is a bad idea, the override functionality is for short
term workarounds and mainly for debugging! Please always report such bugs
bugzilla.kernel.org or post to [email protected] if unsure.

There are two possibilities to override the DSDT:

  - via CONFIG_ACPI_CUSTOM_DSDT (and _FILE) compile option(s)
  - via adding a customized DSDT into initramfs

The second approach does not need kernel recompilation and some
provide the patch, which is not included in mainline, in their kernels.

The patch and more information can be found here (many thanks to Markus
Gaugusch and Eric Piel):

3. Problem Analysis and Solving

3.1. I see Warnings or Errors when disassembling or compiling my DSDT
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Some might be sever ACPICA or BIOS bugs, some might just be
with the Microsoft compiler. We want to fix both, therefore a bug should be
filed at bugzilla.kernel.org
In general you should watch your system, if you don't miss any
there is no reason to panic (e.g. modify the DSDT and override your
one, you really should not do that if you do not see any big advantage and
then, better try to get a real fix or at least a kernel workaround like a
boot or module parameter).

You should be able to debug this with userspace tools (See:
"1.2. Useful Userspace Tools for Table Playing")

3.2) Hardware accessed by ACPI is not working correctly - Using ACPI_DEBUG
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

If you expect the bug in a module in drivers/acpi/*.c code you might have
and be able to find or narrow down the culprit by simple printks.

On more complicated bugs you should make use of the ACPI_DEBUG=y facility.
This allows you to fine grain enable specific output in the ACPI

   3.2.1 Using ACPI_DEBUG Boot Parameters acpi.debug_level and

         Note: In kernel versions before 2.6.22 the boot parameters are:
	       acpi_dbg_level and acpi_dbg_layer

         ACPI can produce tons of debug output if these debug masks are
         switched to full on.
	 include/acpi/acoutput.h shows which flags can be enabled for level and
         layer (cat /proc/acpi/debug_{level,layer} also shows you the
	 but that interface will move to sysfs, not sure whether there still
	 will be such a help).

         Therefore, switch on debug flags carefully. You also might want to
	 increase the kernel ring buffer by passing:
	 log_buf_len=XY in bytes and later use dmesg -s XY to get more than
	 16k kernel log output.
	 Instead of serial console logging you might want to use the netconsole
	 interface (Documentation/networking/netconsole.txt) to write away
         syslog messages over network or firescope (patches already exist
         2.6.22-rcX-mm?) to send syslog messages over firewire.
	 The latter might be the only way to debug early hangs on laptops
	 without serial console anyway.

   3.2.2 Using ACPI_DEBUG Boot Parameters via /sysfs and /proc

	 The same as 3.2.1., you can also pass the parameters at runtime e.g.
	 echo 0x1F >/proc/acpi/debug_level    # before 2.6.22 or
         echo ?!?  >/sys/?/!/?                # Rui?
	 Wrapping such statements around loading and unloading a bug affected
	 ACPI module might give you the possibility to increase debug_level,
	 but still only give you a managable amount of debug output.

   3.2.3 Using ACPI_DEBUG ASL debug object

	 You can also add a kind of printk to DSDT code(see 2. Overriding DSDT)
	 Store (XY, debug), will print the value of the ACPI XY variable into
	 syslog. Be aware that you need to have the
	 #define ACPI_LV_DEBUG_OBJECT        0x00000008
	 value defined in the debug_level mask to see any output.
	 This may only be useful if you get too much output with 3.2.[12] and
	 you think it is convenient to debug a very specific part of the ACPI

   3.2.4 Using ACPI_DEBUG acpi_dbg_layer and acpi_dbg_level kernel

	 Similar, but more powerful than 3.2.3 is to modify the global kernel
	 variables for level and layer conditionally in the kernel code for
	 your needs.
	 acpi_debug_level=0xFFFFFFFF /* increase debug output to max */
	 status = acpi_ut_evaluate_object(...) /* by kernel invoked ACPI method
						  that should get debugged with
						  very high debug output*/
 	 acpi_debug_level=0x3        /* lower debug output again */

"It seems unfortunate if we do this work and get our
partners to do the work and the result is that Linux works great without
having to do the work" (Bill Gates on Making ACPI Not Work with Linux,

To unsubscribe from this list: send the line "unsubscribe linux-acpi" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
CD: 3ms