Re: Documentation - How to debug ACPI Problems

Re: Documentation - How to debug ACPI Problems

[Zhang Rui]

On Wed, 2007-06-06 at 16:26 +0200, Thomas Renninger wrote:
> 
> 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 incompatibilities
> 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 functionality
> there is no reason to panic (e.g. modify the DSDT and override your original
> one, you really should not do that if you do not see any big advantage and even
> 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
3.2. typo

> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
> 
> If you expect the bug in a module in drivers/acpi/*.c code you might have luck
> 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 interpreter.
> 
> 
>    3.2.1 Using ACPI_DEBUG Boot Parameters acpi.debug_level and acpi.debug_layer
> 
>          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 flags,
> 	 but that interface will move to sysfs, not sure whether there still
> 	 will be such a help).
They work in the same way as they do in procfs.
i.e. cat /sys/module/acpi/parameters/debug_{level,layer}
shows you the flags as well.
In fact, I think they can replace the proc I/F right now.

> 
>          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 in
>          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.
> 	 via:
> 	 echo 0x1F >/proc/acpi/debug_level    # before 2.6.22 or
>          echo ?!?  >/sys/?/!/?                # Rui?
echo 0x1F >/sys/module/acpi/parameters/debug_level

And we still support the ACPI debug proc I/F at the current stage.


Thanks,
Rui

Documentation - How to debug ACPI Problems

[Thomas Renninger]

Hi,

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

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
on.

Thanks,

     Thomas


How to debug ACPI Problems
==========================

Thomas Renninger <trenn@suse.de>, 2007
Copyright (C) 2007 SUSE Linux GmbH


1. Introduction
---------------

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

Please refer to the latest ACPI spec for general ACPI information:
http://www.acpi.info/spec.htm

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

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 gets
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 package
is called ACPICA. It includes the code for disassembling DSDT tables,
(re-)compiling them, parsing several ACPI tables and interpreting ACPI Machine
Language (AML, the compiled ASL..). The code is used to provide several
userspace tools, but large parts are also contributed to the linux kernel and
other OSs.
drivers/acpi/*.c currently is Linux code implementing most parts of the ACPI
spec, everything in the directories below, gets synced with the ACPICA Intel
package.


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:
ftp://ftp.kernel.org/pub/linux/kernel/people/lenb/acpi/utils

acpixtract, iasl, acpiexec can be found in the ACPICA sources:
http://developer.intel.com/technology/iapc/acpi/downloads.htm

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 with
alternative tables at early boot time.

In history people used to override their DSDT to workaround BIOS or even kernel
bugs. This is a bad idea, the override functionality is for short
term workarounds and mainly for debugging! Please always report such bugs to
bugzilla.kernel.org or post to linux-acpi@vger.kernel.org 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 distributions
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):
http://gaugusch.at/kernel.shtml


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 incompatibilities
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 functionality
there is no reason to panic (e.g. modify the DSDT and override your original
one, you really should not do that if you do not see any big advantage and even
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 luck
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 interpreter.


   3.2.1 Using ACPI_DEBUG Boot Parameters acpi.debug_level and acpi.debug_layer

         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 flags,
	 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 in
         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.
	 via:
	 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
	 code.

   3.2.4 Using ACPI_DEBUG acpi_dbg_layer and acpi_dbg_level kernel variables

	 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.
	 E.g.
	 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,
http://www.osnews.com/story.php/17689/Bill-Gates-on-Making-ACPI-Not-Work-with-Linux)

Re: Documentation - How to debug ACPI Problems

[Jesper Juhl]

On 06/06/07, Thomas Renninger <trenn@suse.de> wrote:
> Hi,
>
> I made up a little How-To for what I find out is nice to debug ACPI
> problems.
>
Nice :-)

> Any enhancements, corrections, etc. are very much appreciated.
>
See below.

> I'd like to have a final version in the Documentation section.
>
When you send in the patch to add that final version, please also
remember to add an entry to Documentation/00-INDEX

[snip]
>
> How to debug ACPI Problems
> ==========================
>
> Thomas Renninger <trenn@suse.de>, 2007
> Copyright (C) 2007 SUSE Linux GmbH
>
>
> 1. Introduction
> ---------------
>
> 1.1. General Info
> - - - - - - - -
>
Perhaps start out here by telling people what ACPI is. Something like this:

ACPI stands for Advanced Configuration and Power Interface.

> Please refer to the latest ACPI spec for general ACPI information:
> http://www.acpi.info/spec.htm
>
> ACPI is required by most recent x86, x86_64 and IA64 architecture based
> machines.
>
> 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 gets
> interpreted by the OS. The kernel makes use of provided BIOS functions

The word "provided" seems superfluous here.

[snip]
>
> The ACPI tables of your system can be extracted with the acpidump tool:

I think the colon ":" at the end of this line should be removed.

> in the latest pmutils package from here:
> ftp://ftp.kernel.org/pub/linux/kernel/people/lenb/acpi/utils
>
[snip]
>
> In history people used to override their DSDT to workaround BIOS or even kernel

I would replace "In history people used to ..." with "Historically
people used to ...".

[snip]
> If you expect the bug in a module in drivers/acpi/*.c code you might have luck
> and be able to find or narrow down the culprit by simple printks.
>
I would rewrite that bit as :

If you suspect the bug to be in a module in drivers/acpi/*.c code, you
may be able to find or narrow down the culprit simply by adding
printk()'s.

> On more complicated bugs you should make use of the ACPI_DEBUG=y facility.

Maybe just me, but I would say "For" here instead of "On".

[snip]
>          Note: In kernel versions before 2.6.22 the boot parameters are:

should be "...the boot parameters were:" - past tense.

[snip]
>          interface (Documentation/networking/netconsole.txt) to write away
>          syslog messages over network or firescope

"... to write away syslog messages over network ..." sounds a little
clumsy to me. Why not simply write "... to send syslog messages over
network ..." ?

> (patches already exist in
>          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.
>

"without a serial console" ???

>    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.
>          via:
>          echo 0x1F >/proc/acpi/debug_level    # before 2.6.22 or
>          echo ?!?  >/sys/?/!/?                # Rui?

Seems like some bits are missing here ^^^

>          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.
>

s/managable/manageable/


[snip]

-- 
Jesper Juhl <jesper.juhl@gmail.com>
Don't top-post  http://www.catb.org/~esr/jargon/html/T/top-post.html
Plain text mails only, please      http://www.expita.com/nomime.html

Re: Documentation - How to debug ACPI Problems

[Alexey Starikovskiy]

Thomas Renninger wrote:
> Please refer to the latest ACPI spec for general ACPI information:
> http://www.acpi.info/spec.htm
It is worth noting that not all systems are required to implement the latest and greatest version of spec, or all the objects of the chosen version.

Re: Documentation - How to debug ACPI Problems

[Thomas Renninger]

[-- Attachment #1: Type: text/plain, Size: 10082 bytes --]

Thanks a lot for all your input!

Here is an updated version in patch format.
Len, it would be great if you can also add this one to your test tree.

On Wed, 2007-06-06 at 16:59 +0200, Jesper Juhl wrote:
> On 06/06/07, Thomas Renninger <trenn@suse.de> wrote:
> > Hi,
> >
> > (patches already exist in
> >          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.
> >
> 
> "without a serial console" ???
Without a serial device (or serial port?), better?
> 
> >    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.
> >          via:
> >          echo 0x1F >/proc/acpi/debug_level    # before 2.6.22 or
> >          echo ?!?  >/sys/?/!/?                # Rui?
> 
> Seems like some bits are missing here ^^^
Thanks to Rui, updated..

    Thomas

Create Documentation/acpi dir and add first ACPI debug How-To

Signed-off-by: Thomas Renninger <trenn@suse.de>

---
 Documentation/00-INDEX                |    3 
 Documentation/acpi/00-INDEX           |    4 
 Documentation/acpi/acpi_debugging.txt |  181 ++++++++++++++++++++++++++++++++++
 3 files changed, 188 insertions(+)

Index: linux-2.6.22-rc3/Documentation/acpi/acpi_debugging.txt
===================================================================
--- /dev/null
+++ linux-2.6.22-rc3/Documentation/acpi/acpi_debugging.txt
@@ -0,0 +1,181 @@
+How to debug ACPI (Advanced Configuration and Power Interface) Problems
+=======================================================================
+
+Thomas Renninger <trenn@suse.de>, 2007
+Copyright (C) 2007 SUSE Linux GmbH
+
+
+1. Introduction
+---------------
+
+1.1. General Info
+- - - - - - - -
+
+Please refer to the latest ACPI spec for general ACPI information:
+http://www.acpi.info/spec.htm
+
+
+ACPI is required by most recent x86, x86_64 and IA64 architecture based
+machines.
+
+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 gets
+interpreted by the OS. The kernel makes use of 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 package
+is called ACPICA. It includes the code for disassembling DSDT tables,
+(re-)compiling them, parsing several ACPI tables and interpreting ACPI Machine
+Language (AML, the compiled ASL..). The code is used to provide several
+userspace tools, but large parts are also contributed to the linux kernel and
+other OSs.
+drivers/acpi/*.c currently is Linux code implementing most parts of the ACPI
+spec, everything in the directories below, gets synchronized with the ACPICA
+Intel package.
+
+
+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:
+ftp://ftp.kernel.org/pub/linux/kernel/people/lenb/acpi/utils
+
+acpixtract, iasl, acpiexec can be found in the ACPICA sources:
+http://developer.intel.com/technology/iapc/acpi/downloads.htm
+
+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 with
+alternative tables at early boot time.
+
+Historically people used to override their DSDT to workaround BIOS or even
+kernel bugs. This is a bad idea, the override functionality is for short
+term workarounds and mainly for debugging! Please always report such bugs to
+bugzilla.kernel.org or post to linux-acpi@vger.kernel.org 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 distributions
+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):
+http://gaugusch.at/kernel.shtml
+
+
+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 incompatibilities
+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 functionality
+there is no reason to panic (e.g. modify the DSDT and override your original
+one, you really should not do that if you do not see any big advantage and even
+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 suspect the bug to be in a module in drivers/acpi/*.c code, you may be
+able to find or narrow down the culprit simply by adding printk()'s.
+
+For 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 interpreter.
+
+
+   3.2.1 Using ACPI_DEBUG Boot Parameters acpi.debug_level and acpi.debug_layer
+
+         Note: In kernel versions before 2.6.22 the boot parameters were:
+	       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 flags,
+	 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 send syslog
+	 messages over network or firewire to send syslog messages over
+	 firewire.
+	 The latter might be the only way to debug early hangs on laptops
+	 without a serial device 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.
+	 via:
+	 echo 0x1F >/sys/module/acpi/parameters/debug_{level,layer}
+
+	 Be aware that this interface exists since 2.6.22. In older kernels
+	 it is /proc/acpi/debug_{level,layer}, which worked in the same way.
+
+	 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 manageable 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
+	 code.
+
+   3.2.4 Using ACPI_DEBUG acpi_dbg_layer and acpi_dbg_level kernel variables
+
+	 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.
+	 E.g.
+	 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,
+http://www.osnews.com/story.php/17689/Bill-Gates-on-Making-ACPI-Not-Work-with-Linux)
Index: linux-2.6.22-rc3/Documentation/acpi/00-INDEX
===================================================================
--- /dev/null
+++ linux-2.6.22-rc3/Documentation/acpi/00-INDEX
@@ -0,0 +1,4 @@
+00-INDEX
+	- this file
+acpi_debugging.txt
+	- How to debug ACPI problems
\ No newline at end of file
Index: linux-2.6.22-rc3/Documentation/00-INDEX
===================================================================
--- linux-2.6.22-rc3.orig/Documentation/00-INDEX
+++ linux-2.6.22-rc3/Documentation/00-INDEX
@@ -12,6 +12,9 @@ Following translations are available on 
 
 00-INDEX
 	- this file.
+acpi/
+	- general ACPI information
+
 BUG-HUNTING
 	- brute force method of doing binary search of patches to find bug.
 Changes


[-- Attachment #2: acpi_debug_doc.patch --]
[-- Type: text/x-patch, Size: 9114 bytes --]

Create Documentation/acpi dir and add first ACPI debug How-To

Signed-off-by: Thomas Renninger <trenn@suse.de>

---
 Documentation/00-INDEX                |    3 
 Documentation/acpi/00-INDEX           |    4 
 Documentation/acpi/acpi_debugging.txt |  181 ++++++++++++++++++++++++++++++++++
 3 files changed, 188 insertions(+)

Index: linux-2.6.22-rc3/Documentation/acpi/acpi_debugging.txt
===================================================================
--- /dev/null
+++ linux-2.6.22-rc3/Documentation/acpi/acpi_debugging.txt
@@ -0,0 +1,181 @@
+How to debug ACPI (Advanced Configuration and Power Interface) Problems
+=======================================================================
+
+Thomas Renninger <trenn@suse.de>, 2007
+Copyright (C) 2007 SUSE Linux GmbH
+
+
+1. Introduction
+---------------
+
+1.1. General Info
+- - - - - - - -
+
+Please refer to the latest ACPI spec for general ACPI information:
+http://www.acpi.info/spec.htm
+
+
+ACPI is required by most recent x86, x86_64 and IA64 architecture based
+machines.
+
+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 gets
+interpreted by the OS. The kernel makes use of 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 package
+is called ACPICA. It includes the code for disassembling DSDT tables,
+(re-)compiling them, parsing several ACPI tables and interpreting ACPI Machine
+Language (AML, the compiled ASL..). The code is used to provide several
+userspace tools, but large parts are also contributed to the linux kernel and
+other OSs.
+drivers/acpi/*.c currently is Linux code implementing most parts of the ACPI
+spec, everything in the directories below, gets synchronized with the ACPICA
+Intel package.
+
+
+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:
+ftp://ftp.kernel.org/pub/linux/kernel/people/lenb/acpi/utils
+
+acpixtract, iasl, acpiexec can be found in the ACPICA sources:
+http://developer.intel.com/technology/iapc/acpi/downloads.htm
+
+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 with
+alternative tables at early boot time.
+
+Historically people used to override their DSDT to workaround BIOS or even
+kernel bugs. This is a bad idea, the override functionality is for short
+term workarounds and mainly for debugging! Please always report such bugs to
+bugzilla.kernel.org or post to linux-acpi@vger.kernel.org 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 distributions
+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):
+http://gaugusch.at/kernel.shtml
+
+
+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 incompatibilities
+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 functionality
+there is no reason to panic (e.g. modify the DSDT and override your original
+one, you really should not do that if you do not see any big advantage and even
+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 suspect the bug to be in a module in drivers/acpi/*.c code, you may be
+able to find or narrow down the culprit simply by adding printk()'s.
+
+For 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 interpreter.
+
+
+   3.2.1 Using ACPI_DEBUG Boot Parameters acpi.debug_level and acpi.debug_layer
+
+         Note: In kernel versions before 2.6.22 the boot parameters were:
+	       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 flags,
+	 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 send syslog
+	 messages over network or firewire to send syslog messages over
+	 firewire.
+	 The latter might be the only way to debug early hangs on laptops
+	 without a serial device 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.
+	 via:
+	 echo 0x1F >/sys/module/acpi/parameters/debug_{level,layer}
+
+	 Be aware that this interface exists since 2.6.22. In older kernels
+	 it is /proc/acpi/debug_{level,layer}, which worked in the same way.
+
+	 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 manageable 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
+	 code.
+
+   3.2.4 Using ACPI_DEBUG acpi_dbg_layer and acpi_dbg_level kernel variables
+
+	 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.
+	 E.g.
+	 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,
+http://www.osnews.com/story.php/17689/Bill-Gates-on-Making-ACPI-Not-Work-with-Linux)
Index: linux-2.6.22-rc3/Documentation/acpi/00-INDEX
===================================================================
--- /dev/null
+++ linux-2.6.22-rc3/Documentation/acpi/00-INDEX
@@ -0,0 +1,4 @@
+00-INDEX
+	- this file
+acpi_debugging.txt
+	- How to debug ACPI problems
\ No newline at end of file
Index: linux-2.6.22-rc3/Documentation/00-INDEX
===================================================================
--- linux-2.6.22-rc3.orig/Documentation/00-INDEX
+++ linux-2.6.22-rc3/Documentation/00-INDEX
@@ -12,6 +12,9 @@ Following translations are available on 
 
 00-INDEX
 	- this file.
+acpi/
+	- general ACPI information
+
 BUG-HUNTING
 	- brute force method of doing binary search of patches to find bug.
 Changes

Re: Documentation - How to debug ACPI Problems

[Len Brown]

> +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 with
> +alternative tables at early boot time.
> +
> +Historically people used to override their DSDT to workaround BIOS or even
> +kernel bugs. This is a bad idea, the override functionality is for short
> +term workarounds and mainly for debugging! Please always report such bugs to
> +bugzilla.kernel.org or post to linux-acpi@vger.kernel.org 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 distributions
> +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):
> +http://gaugusch.at/kernel.shtml
> +

how to override the DSDT by re-compiling the upstream kernel
is already documented here:

http://ftp.kernel.org/pub/linux/kernel/people/lenb/acpi/patches/README.ACPI

It seems inconsistent to refer to the initrd patch from the in-tree Documentation,
since that patch will always be out-of-tree.

I would think that the in-tree Documentation would refer to specifics relating
to the kernel that is actually checked into the tree with the Documentation.
This assumption can probably clear up some of the wording relating to the
debug flags -- we don't have to describe the old ones -- if somebody is
reading this documentation, they already have the new ones:-)

Asside from those specific things that describe the kernel in the tree,
I'm thinking that acpi.sourceforge.net documentation would be a better
place for a general HOWTO on debugging ACPI issues in general.

-Len

Re: Documentation - How to debug ACPI Problems

[Thomas Renninger]

On Mon, 2007-06-18 at 00:12 -0400, Len Brown wrote:
> > +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 with
> > +alternative tables at early boot time.
> > +
> > +Historically people used to override their DSDT to workaround BIOS or even
> > +kernel bugs. This is a bad idea, the override functionality is for short
> > +term workarounds and mainly for debugging! Please always report such bugs to
> > +bugzilla.kernel.org or post to linux-acpi@vger.kernel.org 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 distributions
> > +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):
> > +http://gaugusch.at/kernel.shtml
> > +
> 
> how to override the DSDT by re-compiling the upstream kernel
> is already documented here:
> 
> http://ftp.kernel.org/pub/linux/kernel/people/lenb/acpi/patches/README.ACPI
Ah yes, a link to this one is quite convenient...

> It seems inconsistent to refer to the initrd patch from the in-tree Documentation,
> since that patch will always be out-of-tree.
It is inconsistent to point to a useful debug patch outside the kernel?

> I would think that the in-tree Documentation would refer to specifics relating
> to the kernel that is actually checked into the tree with the Documentation.
> This assumption can probably clear up some of the wording relating to the
> debug flags -- we don't have to describe the old ones -- if somebody is
> reading this documentation, they already have the new ones:-)
rip out mentioning /proc/acpi/debug_{level,layer}?
Ok.

> Asside from those specific things that describe the kernel in the tree,
> I'm thinking that acpi.sourceforge.net documentation would be a better
> place for a general HOWTO on debugging ACPI issues in general.
Looking at:
http://ftp.kernel.org/pub/linux/kernel/people/lenb/acpi/patches/README.ACPI,
maybe we could just add that one instead to Documentation/acpi/*?
If, splitting would IMO be easier to read, e.g. something like:
  - report_acpi_kernel_bugs.txt
  - sending_ACPI_patches.txt
  - debugging_acpi_kernel_errors.txt

      Thomas

Re: Documentation - How to debug ACPI Problems

[Len Brown]

On Monday 11 June 2007 12:28, Thomas Renninger wrote:
> Thanks a lot for all your input!
> 
> Here is an updated version in patch format.
> Len, it would be great if you can also add this one to your test tree.

Thomas,
Thanks for doing this.
I'll apply it, and then hack on it a bit.

-Len

Re: Documentation - How to debug ACPI Problems

[Len Brown]

On Monday 18 June 2007 07:18, Thomas Renninger wrote:
> On Mon, 2007-06-18 at 00:12 -0400, Len Brown wrote:
> > > +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 with
> > > +alternative tables at early boot time.
> > > +
> > > +Historically people used to override their DSDT to workaround BIOS or even
> > > +kernel bugs. This is a bad idea, the override functionality is for short
> > > +term workarounds and mainly for debugging! Please always report such bugs to
> > > +bugzilla.kernel.org or post to linux-acpi@vger.kernel.org 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 distributions
> > > +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):
> > > +http://gaugusch.at/kernel.shtml
> > > +
> > 
> > how to override the DSDT by re-compiling the upstream kernel
> > is already documented here:
> > 
> > http://ftp.kernel.org/pub/linux/kernel/people/lenb/acpi/patches/README.ACPI
> Ah yes, a link to this one is quite convenient...
> 
> > It seems inconsistent to refer to the initrd patch from the in-tree Documentation,
> > since that patch will always be out-of-tree.
> It is inconsistent to point to a useful debug patch outside the kernel?
> 
> > I would think that the in-tree Documentation would refer to specifics relating
> > to the kernel that is actually checked into the tree with the Documentation.
> > This assumption can probably clear up some of the wording relating to the
> > debug flags -- we don't have to describe the old ones -- if somebody is
> > reading this documentation, they already have the new ones:-)
> rip out mentioning /proc/acpi/debug_{level,layer}?
> Ok.
> 
> > Asside from those specific things that describe the kernel in the tree,
> > I'm thinking that acpi.sourceforge.net documentation would be a better
> > place for a general HOWTO on debugging ACPI issues in general.
> Looking at:
> http://ftp.kernel.org/pub/linux/kernel/people/lenb/acpi/patches/README.ACPI,
> maybe we could just add that one instead to Documentation/acpi/*?
> If, splitting would IMO be easier to read, e.g. something like:
>   - report_acpi_kernel_bugs.txt
>   - sending_ACPI_patches.txt
>   - debugging_acpi_kernel_errors.txt

Okay, good suggestion, I'll do it.

thanks,
-Len

Re: Documentation - How to debug ACPI Problems

[Len Brown]

> +Thomas Renninger <trenn@suse.de>, 2007
> +Copyright (C) 2007 SUSE Linux GmbH

While it seems to be generally customary to identify the authors of Documentation
files, it doesn't seem to be customary for them to assert a copyright.
Is this really necessary?  My concern is that it could discourage contributors
for user or changing the text in any way they see fit.

can anybody offer guidance on this?

thanks,
-Len

Re: Documentation - How to debug ACPI Problems

[Thomas Renninger]

On Tue, 2007-08-14 at 11:40 -0400, Len Brown wrote:
> > +Thomas Renninger <trenn@suse.de>, 2007
> > +Copyright (C) 2007 SUSE Linux GmbH
> 
> While it seems to be generally customary to identify the authors of Documentation
> files, it doesn't seem to be customary for them to assert a copyright.
> Is this really necessary?  My concern is that it could discourage contributors
> for user or changing the text in any way they see fit.
> 
> can anybody offer guidance on this?
> 

I am no license expert, but if you do a:
grep Copyright Documentation/ -r
you see hundreds of Copyrights clauses..., everything in kernel is under
GPL anyway and AFAIK the Copyright is just the explicit statement that
the Author implicitly has anyway...
I don't care that much whether you exactly take this one.
You still might want to take your documentation (I didn't know that you
already set up this one on your ftp account). You still might want to
merge parts of mine if it's appropriate, add a "thanks for input" or
not, at least people have something to read at the end...

Thanks,

   Thomas

Re: Documentation - How to debug ACPI Problems

[Henrique de Moraes Holschuh]

On Tue, 14 Aug 2007, Len Brown wrote:
> > +Thomas Renninger <trenn@suse.de>, 2007
> > +Copyright (C) 2007 SUSE Linux GmbH
> 
> While it seems to be generally customary to identify the authors of Documentation
> files, it doesn't seem to be customary for them to assert a copyright.
> Is this really necessary?  My concern is that it could discourage contributors
> for user or changing the text in any way they see fit.
> 
> can anybody offer guidance on this?

For docs that specify a friendly license explicitly (GPL, BSD, etc), that
should not be a problem.

-- 
  "One disk to rule them all, One disk to find them. One disk to bring
  them all and in the darkness grind them. In the Land of Redmond
  where the shadows lie." -- The Silicon Valley Tarot
  Henrique Holschuh

Re: Documentation - How to debug ACPI Problems

[Alan Cox]

On Tue, 14 Aug 2007 11:40:01 -0400
Len Brown <lenb@kernel.org> wrote:

> 
> > +Thomas Renninger <trenn@suse.de>, 2007
> > +Copyright (C) 2007 SUSE Linux GmbH
> 
> While it seems to be generally customary to identify the authors of Documentation
> files, it doesn't seem to be customary for them to assert a copyright.
> Is this really necessary?  My concern is that it could discourage contributors
> for user or changing the text in any way they see fit.
> 
> can anybody offer guidance on this?

Its under the GPL so I don't see a problem really. I'd do the same for
Red Hat for new documents of substance I was adding to be honest.

Re: Documentation - How to debug ACPI Problems

[Valdis.Kletnieks]

[-- Attachment #1: Type: text/plain, Size: 1093 bytes --]

On Tue, 14 Aug 2007 11:40:01 EDT, Len Brown said:
> 
> > +Thomas Renninger <trenn@suse.de>, 2007
> > +Copyright (C) 2007 SUSE Linux GmbH
> 
> While it seems to be generally customary to identify the authors of Documentation
> files, it doesn't seem to be customary for them to assert a copyright.
> Is this really necessary?  My concern is that it could discourage contributors
> for user or changing the text in any way they see fit.
> 
> can anybody offer guidance on this?

Well, if it's a GPL-friendly license on the document, the contributors should
feel free to change it as needed - that's the point of the GPL.

What it *does* make clear is that the doc was a "work for hire" under
copyright law, and that if there's infringement, it isn't Thomas that's
going to come looking for you, it's Suse Linux GmbH.
> thanks,
> -Len
> 
> -
> To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> Please read the FAQ at  http://www.tux.org/lkml/
> 


[-- Attachment #2: Type: application/pgp-signature, Size: 226 bytes --]