Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit a0d84a92 authored by Bjorn Helgaas's avatar Bjorn Helgaas Committed by Len Brown
Browse files

ACPI: update debug parameter documentation 



Reformat acpi.debug_layer and acpi.debug_level documentation so it's
more readable, add some clues about how to figure out the mask bits that
enable a specific ACPI_DEBUG_PRINT statement, and include some useful
examples.

Move the list of masks to Documentation/acpi/debug.txt (these are
copies of the authoritative values in acoutput.h and acpi_drivers.h).

Signed-off-by: default avatarBjorn Helgaas <bjorn.helgaas@hp.com>
Signed-off-by: default avatarLen Brown <len.brown@intel.com>
parent 87b58608

Documentation/acpi/debug.txt

0 → 100644
+148 −0
Original line number Diff line number Diff line 
			ACPI Debug Output





The ACPI CA, the Linux ACPI core, and some ACPI drivers can generate debug

output.  This document describes how to use this facility.



Compile-time configuration

--------------------------



ACPI debug output is globally enabled by CONFIG_ACPI_DEBUG.  If this config

option is turned off, 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 driver or 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 and

include/acpi/acpi_drivers.h.  Reading /sys/module/acpi/parameters/debug_layer

shows the supported mask values, currently these:



    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

    ACPI_BUS_COMPONENT              0x00010000

    ACPI_AC_COMPONENT               0x00020000

    ACPI_BATTERY_COMPONENT          0x00040000

    ACPI_BUTTON_COMPONENT           0x00080000

    ACPI_SBS_COMPONENT              0x00100000

    ACPI_FAN_COMPONENT              0x00200000

    ACPI_PCI_COMPONENT              0x00400000

    ACPI_POWER_COMPONENT            0x00800000

    ACPI_CONTAINER_COMPONENT        0x01000000

    ACPI_SYSTEM_COMPONENT           0x02000000

    ACPI_THERMAL_COMPONENT          0x04000000

    ACPI_MEMORY_DEVICE_COMPONENT    0x08000000

    ACPI_VIDEO_COMPONENT            0x10000000

    ACPI_PROCESSOR_COMPONENT        0x20000000



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/bus.c contains this:



    #define _COMPONENT              ACPI_BUS_COMPONENT

    ...

    ACPI_DEBUG_PRINT((ACPI_DB_INFO, "Device insertion detected\n"));



To turn on this message, set the ACPI_BUS_COMPONENT bit in acpi.debug_layer

and the ACPI_LV_INFO bit in acpi.debug_level.  (The ACPI_DEBUG_PRINT

statement uses ACPI_DB_INFO, which is macro based on the ACPI_LV_INFO

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 PCI and PCI interrupt routing debug messages:



    acpi.debug_layer=0x400000 acpi.debug_level=0x4



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

Documentation/kernel-parameters.txt

+23 −52
Original line number Diff line number Diff line
@@ -198,59 +198,30 @@ and is between 256 and 4096 characters. It is defined in the file 
			that require a timer override, but don't have

			HPET



	acpi.debug_layer=	[HW,ACPI]

	acpi.debug_layer=	[HW,ACPI,ACPI_DEBUG]

	acpi.debug_level=	[HW,ACPI,ACPI_DEBUG]

			Format: <int>

			Each bit of the <int> indicates an ACPI debug layer,

			1: enable, 0: disable. It is useful for boot time

			debugging. After system has booted up, it can be set

			via /sys/module/acpi/parameters/debug_layer.

			CONFIG_ACPI_DEBUG must be enabled for this to produce any output.

			Available bits (add the numbers together) to enable debug output

			for specific parts of the ACPI subsystem:

			0x01 utilities 0x02 hardware 0x04 events 0x08 tables

			0x10 namespace 0x20 parser 0x40 dispatcher

			0x80 executer 0x100 resources 0x200 acpica debugger

			0x400 os services 0x800 acpica disassembler.

			The number can be in decimal or prefixed with 0x in hex.

			Warning: Many of these options can produce a lot of

			output and make your system unusable. Be very careful.



	acpi.debug_level=	[HW,ACPI]

			Format: <int>

			Each bit of the <int> indicates an ACPI debug level,

			which corresponds to the level in an ACPI_DEBUG_PRINT

			statement.  After system has booted up, this mask

			can be set via /sys/module/acpi/parameters/debug_level.



			CONFIG_ACPI_DEBUG must be enabled for this to produce

			any output.  The number can be in decimal or prefixed

			with 0x in hex.  Some of these options produce so much

			output that the system is unusable.



			The following global components are defined by the

			ACPI CA:

			       0x01 error

			       0x02 warn

			       0x04 init

			       0x08 debug object

			       0x10 info

			       0x20 init names

			       0x40 parse

			       0x80 load

			      0x100 dispatch

			      0x200 execute

			      0x400 names

			      0x800 operation region

			     0x1000 bfield

			     0x2000 tables

			     0x4000 values

			     0x8000 objects

			    0x10000 resources

			    0x20000 user requests

			    0x40000 package

 			The number can be in decimal or prefixed with 0x in hex.

 			Warning: Many of these options can produce a lot of

 			output and make your system unusable. Be very careful.

			CONFIG_ACPI_DEBUG must be enabled to produce any ACPI

			debug output.  Bits in debug_layer correspond to a

			_COMPONENT in an ACPI source file, e.g.,

			    #define _COMPONENT ACPI_PCI_COMPONENT

			Bits in debug_level correspond to a level in

			ACPI_DEBUG_PRINT statements, e.g.,

			    ACPI_DEBUG_PRINT((ACPI_DB_INFO, ...

			See Documentation/acpi/debug.txt for more information

			about debug layers and levels.



			Enable AML "Debug" output, i.e., stores to the Debug

			object while interpreting AML:

			    acpi.debug_layer=0xffffffff acpi.debug_level=0x2

			Enable PCI/PCI interrupt routing info messages:

			    acpi.debug_layer=0x400000 acpi.debug_level=0x4

			Enable all messages related to ACPI hardware:

			    acpi.debug_layer=0x2 acpi.debug_level=0xffffffff



			Some values produce so much output that the system is

			unusable.  The "log_buf_len" parameter may be useful

			if you need to capture more output.



 	acpi.power_nocheck=	[HW,ACPI]

 			Format: 1/0 enable/disable the check of power state.

drivers/acpi/Kconfig

+7 −3
Original line number Diff line number Diff line
@@ -312,9 +312,13 @@ config ACPI_DEBUG 
	bool "Debug Statements"

	default n

	help

	  The ACPI driver can optionally report errors with a great deal

	  of verbosity. Saying Y enables these statements. This will increase

	  your kernel size by around 50K.

	  The ACPI subsystem can produce debug output.  Saying Y enables this

	  output and increases the kernel size by around 50K.



	  Use the acpi.debug_layer and acpi.debug_level kernel command-line

	  parameters documented in Documentation/acpi/debug.txt and

	  Documentation/kernel-parameters.txt to control the type and

	  amount of debug output.



config ACPI_DEBUG_FUNC_TRACE

	bool "Additionally enable ACPI function tracing"