.\" $NetBSD: acpi.4,v 1.88 2022/02/13 23:28:58 andvar Exp $
.\"
.\" Copyright (c) 2002, 2004, 2010 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd December 5, 2020
.Dt ACPI 4
.Os
.Sh NAME
.Nm acpi
.Nd Advanced Configuration and Power Interface
.Sh SYNOPSIS
.Cd acpi0	at mainbus0
.Pp
.Cd options	ACPI_DEBUG
.Cd options	ACPIVERBOSE
.Cd options	ACPI_ACTIVATE_DEV
.Cd options	ACPI_DSDT_OVERRIDE
.Cd options	ACPI_DSDT_FILE=""
.Cd options	ACPI_BLACKLIST_YEAR=2000
.Cd options	ACPI__DIS_IS_BROKEN
.Sh DESCRIPTION
.Nx
provides machine-independent bus support for
Advanced Configuration and Power Interface (ACPI)
devices and includes several ACPI device drivers.
.Pp
The
.Nx
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.
.Pp
Options:
.Bl -tag -width ACPI_DSDT_FILE__filename_XX -offset 3n
.It Dv ACPI_DEBUG
Enable various debug facilities.
.It Dv ACPIVERBOSE
Enable verbose debug messages.
.It Dv ACPI_ACTIVATE_DEV
Determine if the ACPI driver should attempt to activate inactive devices.
The default is off.
.It Dv ACPI_DSDT_OVERRIDE
Force a given Differentiated System Description Table (DSDT)
instead of the version supplied by the BIOS.
Use
.Dv ACPI_DSDT_FILE
to specify a DSDT.
.It Dv ACPI_DSDT_FILE="filename"
If
.Dv ACPI_DSDT_FILE
is not specified, default to
.Dq dsdt.hex
in the build directory.
.It Dv ACPI_BLACKLIST_YEAR=2000
Do not use ACPI with any BIOS made on or before the specified year.
.It Dv ACPI__DIS_IS_BROKEN
Do not call the ACPI "_DIS" method to disable interrupt links.
This may be required on specific
.Dq nForce4
chipset systems, which hard hang when this method is called instead of
having it fail gracefully.
.El
.Sh SYSCTL SUPPORT
The following
.Xr sysctl 8
variables are provided by the
.Nm
driver:
.Bl -tag -width "123456" -offset indent
.It Ic hw.acpi.root
The address of the ACPI root pointer in system memory.
.It Ic hw.acpi.sleep.state
The system sleep state.
.It Ic hw.acpi.sleep.states
A list of system sleep states that the machine supports.
The possible values are:
.Pp
.Bl -tag -width XS1X -offset indent -compact
.It S0
fully running
.It S1
power on suspend (CPU and hard disks are off)
.It S2
similar to S3, usually not implemented
.It S3
suspend-to-RAM
.It S4
suspend-to-disk (not supported on
.Nx )
.It S5
power off
.El
.It Ic hw.acpi.sleep.beep
A boolean variable that controls whether the PC
speaker beeps upon resume.
Only available on i386 and amd64 architectures.
.It Ic hw.acpi.sleep.vbios
Defines the handling of the graphics card on i386 and amd64 architectures.
The supported values are:
.Bl -tag -width '2' -offset 2n
.It 0
No attempt to reset the VGA controller will be made.
.It 1
Call the VGA BIOS when still in real mode.
This can result in direct reboots.
In that case, use
.Sq 2
or
.Ic vbetool post
from the
.Pa pkgsrc/sysutils/vbetool
package.
.It 2
Call the VGA BIOS using the in-kernel x86 emulator.
.El
.Pp
If the system has problems in resuming from the S3
state, experimenting with different values may provide a solution.
.It Ic hw.acpi.stat.gpe
The number of dispatched General Purpose Events (GPEs).
.It Ic hw.acpi.stat.sci
The number of System Control Interrupts (SCIs).
See
.Xr acpiec 4
for a brief description of both GPEs and SCIs.
.It Ic hw.acpi.stat.fixed
The number of
.Dq fixed events .
.It Ic hw.acpi.stat.method
The number of AML methods executed by the interpreter.
.It Ic hw.acpi.power
This read-only node describes the ACPI power state of devices.
The values range from D0
.Pq Dq on
to D3
.Pq Dq off .
.It Ic hw.acpi.wake
This node represents devices that can wake the system from the S3 or
S4 sleep state.
By default,
.Xr acpibut 4 ,
.Xr acpilid 4 ,
and
.Xr pckbd 4
are allowed to wake the system, provided that the devices are present and
the firmware supports wake-up capabilities for the devices.
.El
.Sh SUPPORTED DEVICES
.Nx
ACPI supports several machine-dependent and machine-independent devices,
some specific to ACPI and some configured via it.
.Ss Machine-independent devices
.Bl -tag -width "thinkpad(4) " -offset indent -compact
.It Xr acpiacad 4
ACPI AC adapters.
.It Xr acpibat 4
ACPI batteries.
.It Xr acpibut 4
ACPI power and sleep buttons.
.It Xr acpicpu 4
ACPI processors.
.It Xr acpidalb 4
ACPI direction application launch buttons.
.It Xr acpiec 4
ACPI embedded controllers.
.It Xr acpiecdt 4
ACPI Embedded Controller Boot Resource Table (ECDT).
.It Xr acpifan 4
ACPI fans.
.It Xr acpilid 4
ACPI lid switches.
.It Xr acpipmtr 4
ACPI power meters.
.It Xr acpismbus 4
ACPI SMBus via control method interface (CMI).
.It Xr acpitz 4
ACPI thermal zones.
.It Xr acpivga 4
ACPI display adapter and output devices.
.It Xr acpiwmi 4
ACPI support for Windows Management Instrumentation.
.It Xr acpiwdrt 4
ACPI watchdogs.
.It Xr aibs 4
ASUSTeK voltage, temperature and fan sensors.
.It Xr asus 4
ASUS laptop hotkeys.
.It Xr attimer 4
AT Timer.
.It Xr com 4
NS8250-, NS16450-, and NS16550-based serial ports.
.It Xr fdc 4
Floppy disk controllers.
.It Xr fujbp 4
Fujitsu brightness and pointer.
.It Xr fujhk 4
Fujitsu hotkeys.
.It Xr hpacel 4
HP 3D DriveGuard accelerometer.
.It Xr hpet 4
High Precision Event Timer (HPET).
.It Xr hpqlb 4
HP Quick Launch Buttons.
.It Xr joy 4
Joystick/Game port interface.
.It Xr lpt 4
Standard ISA parallel port interface.
.It Xr mpu 4
Roland MPU-401 (compatible) MIDI UART.
.It Xr pcppi 4
AT-style speaker sound.
.It Xr sdhc 4
SD Host Controller.
.It Xr thinkpad 4
IBM/Lenovo ThinkPad laptop device driver.
.It Xr ug 4
Abit uGuru Hardware monitor.
.It Xr vald 4
Toshiba Libretto device.
.It Xr valz 4
Toshiba Dynabook device.
.It Xr wb 4
Winbond W83L518D Integrated Media Reader.
.It Xr wss 4
Windows Sound System-compatible sound cards
.It Xr ym 4
Yamaha OPL3-SA2 and OPL3-SA3 audio device driver.
.El
.Ss i386-dependent devices
.Bl -tag -width "thinkpad(4) " -offset indent -compact
.It Xr pckbc 4
PC keyboard controllers.
.It Xr sony 4
Sony Miscellaneous Controller
.It Xr spic 4
Sony programmable I/O controller.
.El
.Sh 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.
.Pp
To ease the task of diagnosing and fixing different problems, the
ACPICA reference implementation provides a rich
facility of different debugging methods.
In
.Nx
these are generally only available if the kernel has been compiled with the
.Dv ACPI_DEBUG
option.
.Ss Verbose messages
The
.Dv ACPIVERBOSE
compile time option enables some verbose
debug messages printed during the system startup.
In a
.Dv MODULAR
(see
.Xr options 4 )
system, the information can be printed also at runtime,
regardless of the presence of
.Dv ACPIVERBOSE .
To print the messages,
.Xr modload 8
the
.Ic acpiverbose
module using the option
.Fl b Cm dump=true .
.Ss 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
.Nm
is implemented in the so-called
Differentiated System Descriptor Table (DSDT).
.Nx
provides support for overriding the default DSDT supplied by the BIOS.
.Pp
The following steps can be used to override the DSDT:
.Bl -enum -offset indent
.It
Dump the raw DSDT with
.Xr acpidump 8 .
.It
Disassemble the table with
.Xr iasl 8 .
.It
Modify the disassembled table.
.It
Compile the table with
.Xr iasl 8
using the option
.Fl tc .
.It
Either copy the
.Pq Pa *.hex
file to
.Bd -literal -offset indent
src/sys/dev/acpi/acpica/Osd/custom_dsdt.hex
.Ed
.Pp
or use the option
.Bd -literal -offset indent
ACPI_DSDT_FILE="/some/directory/custom_dsdt.hex"
.Ed
.Pp
in the kernel configuration file.
.It
Define
.Dv ACPI_DSDT_OVERRIDE
in the kernel configuration file and rebuild.
.El
.Ss 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
.Nx
this is integrated to the in-kernel
.Xr ddb 4 .
In order to enter the ACPICA debugger from
.Xr ddb 4 ,
use the command
.Ic call
with the argument
.Ic acpi_osd_debugger .
.Ss Debug Output
.Nx
provides three
.Xr sysctl 8
variables that control the debug output at runtime.
The
.Ic hw.acpi.debug.layer
variable limits the output to a specific ACPI layer and the
.Ic hw.acpi.debug.level
variable controls the debug level.
Both
.Xr sysctl 8
variables are string literals.
The third variable is
.Ic hw.acpi.debug.object .
This is a boolean that controls whether debug messages internal to the
AML are enabled.
.Pp
For the first two variables, the possible values are:
.Bl -column -offset indent \
"ACPI_RESOURCE_COMPONENT     " "ACPI_RESOURCE_COMPONENT     "
.It Sy LAYER Ta Sy LEVEL
.It Dv ACPI_DEBUG_NONE Ta Dv ACPI_DEBUG_NONE
.It Ta
.It Dv ACPI_UTILITIES Ta Dv ACPI_LV_INIT
.It Dv ACPI_HARDWARE Ta Dv ACPI_LV_DEBUG_OBJECT
.It Dv ACPI_EVENTS Ta Dv ACPI_LV_INFO
.It Dv ACPI_TABLES Ta Dv ACPI_LV_ALL_EXCEPTIONS No *
.It Dv ACPI_NAMESPACE Ta
.It Dv ACPI_PARSER Ta Dv ACPI_LV_INIT_NAMES
.It Dv ACPI_DISPATCHER Ta Dv ACPI_LV_PARSE
.It Dv ACPI_EXECUTER Ta Dv ACPI_LV_LOAD
.It Dv ACPI_RESOURCES Ta Dv ACPI_LV_DISPATCH
.It Dv ACPI_CA_DEBUGGER Ta Dv ACPI_LV_EXEC
.It Dv ACPI_OS_SERVICES Ta Dv ACPI_LV_NAMES
.It Dv ACPI_CA_DISASSEMBLER Ta Dv ACPI_LV_OPREGION
.It Dv ACPI_COMPILER Ta Dv ACPI_LV_BFIELD
.It Dv ACPI_TOOLS Ta Dv ACPI_LV_TABLES
.It Dv ACPI_EXAMPLE Ta Dv ACPI_LV_VALUES
.It Dv ACPI_DRIVER Ta Dv ACPI_LV_OBJECTS
.It Dv ACPI_ALL_COMPONENTS No * Ta Dv ACPI_LV_RESOURCES
.It Ta Dv ACPI_LV_USER_REQUESTS
.It Dv ACPI_BUS_COMPONENT Ta Dv ACPI_LV_PACKAGE
.It Dv ACPI_ACAD_COMPONENT Ta Dv ACPI_LV_VERBOSITY1 No *
.It Dv ACPI_BAT_COMPONENT Ta
.It Dv ACPI_BUTTON_COMPONENT Ta Dv ACPI_LV_ALLOCATIONS
.It Dv ACPI_EC_COMPONENT Ta Dv ACPI_LV_FUNCTIONS
.It Dv ACPI_LID_COMPONENT Ta Dv ACPI_LV_OPTIMIZATIONS
.It Dv ACPI_RESOURCE_COMPONENT Ta Dv ACPI_LV_VERBOSITY2 No *
.It Dv ACPI_TZ_COMPONENT Ta
.It Dv ACPI_DISPLAY_COMPONENT Ta
.It Dv ACPI_ALL_DRIVERS No * Ta Dv ACPI_LV_MUTEX
.It Ta Dv ACPI_LV_THREADS
.It Ta Dv ACPI_LV_IO
.It Ta Dv ACPI_LV_AML_INTERRUPTS
.It "* This is a compound" Ta Dv ACPI_LV_VERBOSITY3 No *
.It "  constant, including" Ta
.It "  all previous elements." Ta Dv ACPI_LV_AML_DISASSEMBLE
.It Ta Dv ACPI_LV_VERBOSE_INFO
.It Ta Dv ACPI_LV_FULL_TABLES
.It Ta Dv ACPI_LV_EVENTS
.It Ta Dv ACPI_LV_VERBOSE No *
.El
.Pp
In addition, there is
.Dv ACPI_DEBUG_DEFAULT
that is used by ACPICA as the default debug level.
It includes
.Dv ACPI_LV_INIT
and
.Dv ACPI_LV_DEBUG_OBJECT .
.Pp
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
.Nx .
The constant
.Dv ACPI_ALL_DRIVERS
includes all
.Nx
specific parts.
.Pp
The ACPICA interpreter uses several debug levels internally,
but the
.Nx
specific parts are typically limited to
.Dv ACPI_LV_DEBUG_OBJECT
and
.Dv ACPI_LV_INFO .
The debug output can be stopped by setting
.Ic hw.acpi.debug.level
to
.Dv ACPI_DEBUG_NONE .
.Ss Example
As an example, a driver may have defined the component it belongs to and
the name of the module:
.Bd -literal -offset indent
#define _COMPONENT	ACPI_BUS_COMPONENT
ACPI_MODULE_NAME	("acpi_example")
.Ed
.Pp
The driver may also utilize the debug facility:
.Bd -literal -offset indent
ACPI_DEBUG_PRINT((ACPI_DB_INFO, "Failed to evaluate _STA\\n"));
.Ed
.Pp
With these options the debug message from the
.Dv ACPI_DEBUG_PRINT
macro is only visible when
.Ic hw.acpi.debug.layer
is either
.Dv ACPI_BUS_COMPONENT
or a compound constant including it, and
.Ic hw.acpi.debug.level
is
.Dv ACPI_LV_INFO
or some constant that includes it.
Finally, it can be noted that the ACPI implementation uses the prefix
.Dv ACPI_DB ,
whereas the debug level
.Xr sysctl 8
variable is always specified with the prefix
.Dv ACPI_LV .
.Pp
Another example can be mentioned for the use of
.Ic hw.acpi.debug.object .
The following could appear in an ASL code:
.Bd -literal -offset indent
Method(_Q19, 0, NotSerialized)
{
	Store("_Q19 invoked", Debug)
	Notify(ACAD, 0x80)
}
.Ed
.Pp
When
.Ic 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.
.Sh FILES
.Bl -tag -width /dev/acpi
.It Pa /dev/acpi
.El
.Sh SEE ALSO
.Xr ioapic 4 ,
.Xr acpidump 8 ,
.Xr amldb 8 ,
.Xr iasl 8
.Rs
.%A Hewlett-Packard Corporation
.%A Intel Corporation
.%A Microsoft Corporation
.%A Phoenix Technologies Ltd.
.%A Toshiba Corporation
.%T Advanced Configuration and Power Interface Specification
.%N Revision 4.0
.%D June 16, 2009
.%U http://www.acpi.info/spec.htm
.Re
.Rs
.%A Intel Corporation
.%T ACPI Component Architecture,
.%T Programmer Reference,
.%T OS-Independent Subsystem, Debugger, and Utilities
.%N Revision 1.27
.%D January 20, 2010
.%U http://www.acpica.org/download/acpica-reference.pdf
.Re
.Rs
.%A Len Brown
.%T ACPI in Linux - Myths vs. Reality
.%D June 27-30, 2007
.%O Proceedings of the Linux Symposium
.%P 65-74
.%U http://www.linuxsymposium.org/archives/OLS/Reprints-2007/brown_1-Reprint.pdf
.Re
.Rs
.%A Joerg Sonnenberger
.%A Jared D. McNeill
.%T Sleeping Beauty - NetBSD on Modern Laptops
.%D February 3, 2008
.%O Proceedings of AsiaBSDCon 2008
.%P 127-134
.%U http://2008.asiabsdcon.org/papers/P9A-paper.pdf
.Re
.Rs
.%A Takanori Watanabe
.%T ACPI Implementation on FreeBSD
.%I USENIX Association
.%B Proceedings of the FREENIX Track: 2002 USENIX Annual Technical Conference
.%P 121-131
.%D June 10-15, 2002
.%U http://www.usenix.org/event/usenix02/tech/freenix/full_papers/watanabe/watanabe.pdf
.Re
.Sh HISTORY
The
.Nm
driver
appeared in
.Nx 1.6 .
.Sh AUTHORS
.An -nosplit
Authors of the
.Nm
subsystem include
.An Charles M. Hannum ,
.An Frank van der Linden ,
.An Jared D. McNeill ,
.An Jason R. Thorpe ,
.An Joerg Sonnenberger ,
and
.An Jukka Ruohonen ,
among others.
.Sh BUGS
Most of the ACPI power management functionalities are not implemented.
.Pp
The
.Dv ACPI__DIS_IS_BROKEN
option should not be necessary.