NAME

acpi — Advanced Configuration and Power Interface

SYNOPSIS

acpi0 at mainbus0

options ACPI_DEBUG
options ACPIVERBOSE
options ACPI_ACTIVATE_DEV
options ACPI_DSDT_OVERRIDE
options ACPI_DSDT_FILE=""
options ACPI_BLACKLIST_YEAR=2000

DESCRIPTION

NetBSD provides machine-independent bus support for Advanced Configuration and Power Interface (ACPI) devices and includes several ACPI device drivers.

The NetBSD implementation of ACPI integrates Intel's ACPI Component Architecture (ACPI-CA) for the OS-independent part. The ACPI-CA provides OS-neutral ACPI functionalities such as ACPI BIOS table support, an ACPI event framework and an ACPI Machine Language (AML) interpreter.

Options:

SYSCTL SUPPORT

Few sysctl(8) variables are directly relevant for ACPI.

SUPPORTED DEVICES

NetBSD ACPI supports several machine-dependent and machine-independent devices, some specific to ACPI and some configured via it.

Machine-independent devices

i386-dependent devices

DEBUGGING

Although the situation has become better over the years, ACPI is typically prone to various errors, ranging from blatant flaws in the firmware to bugs in the implementation. Before anything else, it is a good practice to upgrade the BIOS to the latest version available from the vendor.

To ease the task of diagnosing and fixing different problems, the ACPICA reference implementation provides a rich facility of different debugging methods. In NetBSD these are generally only available if the kernel has been compiled with the ACPI_DEBUG option.

Verbose messages

The ACPIVERBOSE compile time option enables some verbose debug messages printed during the system startup. In a MODULAR (see options(4)) system, the information can be printed also at runtime, regardless of the presence of ACPIVERBOSE. To print the messages, modload(8) the acpiverbose module using the option -b dump=true.

Custom DSDT

ACPI interprets bytecode known as ACPI Machine Language (AML), provided by the BIOS as a memory image during the system bootstrap. Most of the AML relevant to acpi is implemented in the so-called Differentiated System Descriptor Table (DSDT). NetBSD provides support for overriding the default DSDT supplied by the BIOS.

The following steps can be used to override the DSDT:

Dump the raw DSDT with acpidump(8).
Disassemble the table with iasl(8).
Modify the disassembled table.
Compile the table with iasl(8) using the option -tc.

Either copy the (*.hex) file to

src/sys/dev/acpi/acpica/Osd/custom_dsdt.hex

or use the option

ACPI_DSDT_FILE="/some/directory/custom_dsdt.hex"

in the kernel configuration file.

Define ACPI_DSDT_OVERRIDE in the kernel configuration file and rebuild.

Debugger

The ACPICA interpreter provides its own debugger for low-level debugging. It can be used to display internal data structures and namespace objects, and to debug the execution of control methods. Single step and breakpoint functionality are available. In NetBSD this is integrated to the in-kernel ddb(4). In order to enter the ACPICA debugger from ddb(4), use the command call with the argument acpi_osd_debugger.

Debug Output

NetBSD provides three sysctl(8) variables that control the debug output at runtime. The hw.acpi.debug.layer variable limits the output to a specific ACPI layer and the hw.acpi.debug.level variable controls the debug level. Both sysctl(8) variables are string literals. The third variable is hw.acpi.debug.object. This is a boolean that controls whether debug messages internal to the AML are enabled.

For the first two variables, the possible values are:

LAYER	LEVEL
`ACPI_DEBUG_NONE`	ACPI_DEBUG_NONE

`ACPI_UTILITIES`	ACPI_LV_INIT
`ACPI_HARDWARE`	ACPI_LV_DEBUG_OBJECT
`ACPI_EVENTS`	ACPI_LV_INFO
`ACPI_TABLES`	ACPI_LV_ALL_EXCEPTIONS *
`ACPI_NAMESPACE`
`ACPI_PARSER`	ACPI_LV_INIT_NAMES
`ACPI_DISPATCHER`	ACPI_LV_PARSE
`ACPI_EXECUTER`	ACPI_LV_LOAD
`ACPI_RESOURCES`	ACPI_LV_DISPATCH
`ACPI_CA_DEBUGGER`	ACPI_LV_EXEC
`ACPI_OS_SERVICES`	ACPI_LV_NAMES
`ACPI_CA_DISASSEMBLER`	ACPI_LV_OPREGION
`ACPI_COMPILER`	ACPI_LV_BFIELD
`ACPI_TOOLS`	ACPI_LV_TABLES
`ACPI_EXAMPLE`	ACPI_LV_VALUES
`ACPI_DRIVER`	ACPI_LV_OBJECTS
`ACPI_ALL_COMPONENTS *`	ACPI_LV_RESOURCES
	ACPI_LV_USER_REQUESTS
`ACPI_BUS_COMPONENT`	ACPI_LV_PACKAGE
`ACPI_ACAD_COMPONENT`	ACPI_LV_VERBOSITY1 *
`ACPI_BAT_COMPONENT`
`ACPI_BUTTON_COMPONENT`	ACPI_LV_ALLOCATIONS
`APCI_EC_COMPONENT`	ACPI_LV_FUNCTIONS
`ACPI_LID_COMPONENT`	ACPI_LV_OPTIMIZATIONS
`ACPI_RESOURCE_COMPONENT`	ACPI_LV_VERBOSITY2 *
`ACPI_TZ_COMPONENT`
`ACPI_DISPLAY_COMPONENT`
`ACPI_ALL_DRIVERS *`	ACPI_LV_MUTEX
	ACPI_LV_THREADS
	ACPI_LV_IO
	ACPI_LV_AML_INTERRUPTS
`* This is a compound`	ACPI_LV_VERBOSITY3 *
`constant, including`
`all previous elements.`	ACPI_LV_AML_DISASSEMBLE
	ACPI_LV_VERBOSE_INFO
	ACPI_LV_FULL_TABLES
	ACPI_LV_EVENTS
	ACPI_LV_VERBOSE *

In addition, there is ACPI_DEBUG_DEFAULT that is used by ACPICA as the default debug level. It includes ACPI_LV_INIT and ACPI_LV_DEBUG_OBJECT.

The debug layer can be divided into two groups: the first one is specific to the ACPICA interpreter and the second one contains the internal ACPI components of NetBSD. The constant ACPI_ALL_DRIVERS includes all NetBSD specific parts.

The ACPICA interpreter uses several debug levels internally, but the NetBSD specific parts are typically limited to ACPI_LV_DEBUG_OBJECT and ACPI_LV_INFO. The debug output can be stopped by setting hw.acpi.debug.level to ACPI_DEBUG_NONE.

Example

As an example, a driver may have defined the component it belongs to and the name of the module:

#define _COMPONENT	ACPI_BUS_COMPONENT 
ACPI_MODULE_NAME	("acpi_example")

The driver may also utilize the debug facility:

ACPI_DEBUG_PRINT((ACPI_DB_INFO, "Failed to evaluate _STA\n"));

With these options the debug message from the ACPI_DEBUG_PRINT macro is only visible when hw.acpi.debug.layer is either ACPI_BUS_COMPONENT or a compound constant including it, and hw.acpi.debug.level is ACPI_LV_INFO or some constant that includes it. Finally, it can be noted that the ACPI implementation uses the prefix ACPI_DB, whereas the debug level sysctl(8) variable is always specified with the prefix ACPI_LV.

Another example can be mentioned for the use of hw.acpi.debug.object. The following could appear in an ASL code:

Method(_Q19, 0, NotSerialized) 
{ 
	Store("_Q19 invoked", Debug) 
	Notify(ACAD, 0x80) 
}

When hw.acpi.debug.object is set to 1, the message stored to the debug object is printed every time the method is called by the interpreter.

HISTORY

The acpi driver appeared in NetBSD 1.6.

AUTHORS

Authors of the acpi subsystem include Charles M. Hannum, Frank van der Linden, Jared D. McNeill, Jason R. Thorpe, Joerg Sonnenberger, and Jukka Ruohonen, among others.

BUGS

Most of the ACPI power management functionalities are not implemented.