Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


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, http://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,
     http://www.usenix.org/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.

NetBSD 10.99                   December 5, 2020                   NetBSD 10.99