ACPI(4)

ACPI(4) | Device Drivers Manual | ACPI(4)

# 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`
`options ACPI__DIS_IS_BROKEN`

# 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:

`ACPI_DEBUG`
  Enable various debug facilities.
`ACPIVERBOSE`
  Enable verbose debug messages.
`ACPI_ACTIVATE_DEV`
  Determine if the ACPI driver should attempt to activate inactive devices. The default is off.
`ACPI_DSDT_OVERRIDE`
  Force a given Differentiated System Description Table (DSDT) instead of the version supplied by the BIOS. Use `ACPI_DSDT_FILE` to specify a DSDT.
`ACPI_DSDT_FILE="filename"`
  If `ACPI_DSDT_FILE` is not specified, default to “dsdt.hex” in the build directory.
`ACPI_BLACKLIST_YEAR=2000`
  Do not use ACPI with any BIOS made on or before the specified year.
`ACPI__DIS_IS_BROKEN`
  Do not call the ACPI "_DIS" method to disable interrupt links. This may be required on specific “nForce4” chipset systems, which hard hang when this method is called instead of having it fail gracefully.

# SYSCTL SUPPORT

The following sysctl(8) variables are provided by the `acpi` driver:

`hw.acpi.root`
  The address of the ACPI root pointer in system memory.
`hw.acpi.sleep.state`
  The system sleep state.
`hw.acpi.sleep.states`
  A list of system sleep states that the machine supports. The possible values are:

  S0
    fully running
  S1
    power on suspend (CPU and hard disks are off)
  S2
    similar to S3, usually not implemented
  S3
    suspend-to-RAM
  S4
    suspend-to-disk (not supported on NetBSD)
  S5
    power off
`hw.acpi.sleep.beep`
  A boolean variable that controls whether the PC speaker beeps upon resume. Only available on i386 and amd64 architectures.
`hw.acpi.sleep.vbios`
  Defines the handling of the graphics card on i386 and amd64 architectures. The supported values are:
  0
    No attempt to reset the VGA controller will be made.
  1
    Call the VGA BIOS when still in real mode. This can result in direct reboots. In that case, use ‘2’ or `vbetool post` from the pkgsrc/sysutils/vbetool package.
  2
    Call the VGA BIOS using the in-kernel x86 emulator.

  If the system has problems in resuming from the S3 state, experimenting with different values may provide a solution.

`hw.acpi.stat.gpe`
  The number of dispatched General Purpose Events (GPEs).
`hw.acpi.stat.sci`
  The number of System Control Interrupts (SCIs). See acpiec(4) for a brief description of both GPEs and SCIs.
`hw.acpi.stat.fixed`
  The number of “fixed events”.
`hw.acpi.stat.method`
  The number of AML methods executed by the interpreter.
`hw.acpi.power`
  This read-only node describes the ACPI power state of devices. The values range from D0 (“on”) to D3 (“off”).
`hw.acpi.wake`
  This node represents devices that can wake the system from the S3 or S4 sleep state. By default, acpibut(4), acpilid(4), and pckbd(4) are allowed to wake the system, provided that the devices are present and the firmware supports wake-up capabilities for the devices.

# SUPPORTED DEVICES

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

## Machine-independent devices

acpiacad(4)
  ACPI AC adapters.
acpibat(4)
  ACPI batteries.
acpibut(4)
  ACPI power and sleep buttons.
acpicpu(4)
  ACPI processors.
acpidalb(4)
  ACPI direction application launch buttons.
acpiec(4)
  ACPI embedded controllers.
acpiecdt(4)
  ACPI Embedded Controller Boot Resource Table (ECDT).
acpifan(4)
  ACPI fans.
acpilid(4)
  ACPI lid switches.
acpipmtr(4)
  ACPI power meters.
acpismbus(4)
  ACPI SMBus via control method interface (CMI).
acpitz(4)
  ACPI thermal zones.
acpivga(4)
  ACPI display adapter and output devices.
acpiwmi(4)
  ACPI support for Windows Management Instrumentation.
acpiwdrt(4)
  ACPI watchdogs.
aibs(4)
  ASUSTeK voltage, temperature and fan sensors.
asus(4)
  ASUS laptop hotkeys.
attimer(4)
  AT Timer.
com(4)
  NS8250-, NS16450-, and NS16550-based serial ports.
fdc(4)
  Floppy disk controllers.
fujbp(4)
  Fujitsu brightness and pointer.
fujhk(4)
  Fujitsu hotkeys.
hpacel(4)
  HP 3D DriveGuard accelerometer.
hpet(4)
  High Precision Event Timer (HPET).
hpqlb(4)
  HP Quick Launch Buttons.
joy(4)
  Joystick/Game port interface.
lpt(4)
  Standard ISA parallel port interface.
mpu(4)
  Roland MPU-401 (compatible) MIDI UART.
pcppi(4)
  AT-style speaker sound.
sdhc(4)
  SD Host Controller.
thinkpad(4)
  IBM/Lenovo ThinkPad laptop device driver.
ug(4)
  Abit uGuru Hardware monitor.
vald(4)
  Toshiba Libretto device.
valz(4)
  Toshiba Dynabook device.
wb(4)
  Winbond W83L518D Integrated Media Reader.
wss(4)
  Windows Sound System-compatible sound cards
ym(4)
  Yamaha OPL3-SA2 and OPL3-SA3 audio device driver.

## i386-dependent devices

pckbc(4)
  PC keyboard controllers.
sony(4)
  Sony Miscellaneous Controller
spic(4)
  Sony programmable I/O controller.

# 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:

1. Dump the raw DSDT with acpidump(8).
2. Disassemble the table with iasl(8).
3. Modify the disassembled table.
4. Compile the table with iasl(8) using the option `-tc`.
5. 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.

6. 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`
`ACPI_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.

# FILES

/dev/acpi

# SEE ALSO

ioapic(4), acpidump(8), amldb(8), iasl(8)

Hewlett-Packard Corporation, Intel Corporation, Microsoft Corporation, Phoenix Technologies Ltd., and Toshiba Corporation, Advanced Configuration and Power Interface Specification, Revision 4.0, http://www.acpi.info/spec.htm, June 16, 2009.

Intel Corporation, ACPI Component Architecture,, Programmer Reference,, OS-Independent Subsystem, Debugger, and Utilities, Revision 1.27, http://www.acpica.org/download/acpica-reference.pdf, January 20, 2010.

Len Brown, ACPI in Linux - Myths vs. Reality, http://www.linuxsymposium.org/archives/OLS/Reprints-2007/brown_1-Reprint.pdf, 65-74, June 27-30, 2007, Proceedings of the Linux Symposium.

Joerg Sonnenberger and Jared D. McNeill, Sleeping Beauty - NetBSD on Modern Laptops, https://2008.asiabsdcon.org/papers/P9A-paper.pdf, 127-134, February 3, 2008, Proceedings of AsiaBSDCon 2008.

Takanori Watanabe, ACPI Implementation on FreeBSD, Proceedings of the FREENIX Track: 2002 USENIX Annual Technical Conference, USENIX Association, https://www.usenix.org/legacy/event/usenix02/tech/freenix/full_papers/watanabe/watanabe.pdf, 121-131, June 10-15, 2002.

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

The `ACPI__DIS_IS_BROKEN` option should not be necessary.

December 5, 2020 | NetBSD 11.0