1.\" $NetBSD: acpi.4,v 1.89 2024/09/07 20:33:53 rillig Exp $ 2.\" 3.\" Copyright (c) 2002, 2004, 2010 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 18.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd December 5, 2020 28.Dt ACPI 4 29.Os 30.Sh NAME 31.Nm acpi 32.Nd Advanced Configuration and Power Interface 33.Sh SYNOPSIS 34.Cd acpi0 at mainbus0 35.Pp 36.Cd options ACPI_DEBUG 37.Cd options ACPIVERBOSE 38.Cd options ACPI_ACTIVATE_DEV 39.Cd options ACPI_DSDT_OVERRIDE 40.Cd options ACPI_DSDT_FILE="" 41.Cd options ACPI_BLACKLIST_YEAR=2000 42.Cd options ACPI__DIS_IS_BROKEN 43.Sh DESCRIPTION 44.Nx 45provides machine-independent bus support for 46Advanced Configuration and Power Interface (ACPI) 47devices and includes several ACPI device drivers. 48.Pp 49The 50.Nx 51implementation of ACPI integrates Intel's ACPI Component Architecture 52(ACPI-CA) for the OS-independent part. 53The ACPI-CA provides OS-neutral ACPI functionalities such as ACPI BIOS 54table support, 55an ACPI event framework and an ACPI Machine Language (AML) interpreter. 56.Pp 57Options: 58.Bl -tag -width ACPI_DSDT_FILE__filename_XX -offset 3n 59.It Dv ACPI_DEBUG 60Enable various debug facilities. 61.It Dv ACPIVERBOSE 62Enable verbose debug messages. 63.It Dv ACPI_ACTIVATE_DEV 64Determine if the ACPI driver should attempt to activate inactive devices. 65The default is off. 66.It Dv ACPI_DSDT_OVERRIDE 67Force a given Differentiated System Description Table (DSDT) 68instead of the version supplied by the BIOS. 69Use 70.Dv ACPI_DSDT_FILE 71to specify a DSDT. 72.It Dv ACPI_DSDT_FILE="filename" 73If 74.Dv ACPI_DSDT_FILE 75is not specified, default to 76.Dq dsdt.hex 77in the build directory. 78.It Dv ACPI_BLACKLIST_YEAR=2000 79Do not use ACPI with any BIOS made on or before the specified year. 80.It Dv ACPI__DIS_IS_BROKEN 81Do not call the ACPI "_DIS" method to disable interrupt links. 82This may be required on specific 83.Dq nForce4 84chipset systems, which hard hang when this method is called instead of 85having it fail gracefully. 86.El 87.Sh SYSCTL SUPPORT 88The following 89.Xr sysctl 8 90variables are provided by the 91.Nm 92driver: 93.Bl -tag -width "123456" -offset indent 94.It Ic hw.acpi.root 95The address of the ACPI root pointer in system memory. 96.It Ic hw.acpi.sleep.state 97The system sleep state. 98.It Ic hw.acpi.sleep.states 99A list of system sleep states that the machine supports. 100The possible values are: 101.Pp 102.Bl -tag -width XS1X -offset indent -compact 103.It S0 104fully running 105.It S1 106power on suspend (CPU and hard disks are off) 107.It S2 108similar to S3, usually not implemented 109.It S3 110suspend-to-RAM 111.It S4 112suspend-to-disk (not supported on 113.Nx ) 114.It S5 115power off 116.El 117.It Ic hw.acpi.sleep.beep 118A boolean variable that controls whether the PC 119speaker beeps upon resume. 120Only available on i386 and amd64 architectures. 121.It Ic hw.acpi.sleep.vbios 122Defines the handling of the graphics card on i386 and amd64 architectures. 123The supported values are: 124.Bl -tag -width '2' -offset 2n 125.It 0 126No attempt to reset the VGA controller will be made. 127.It 1 128Call the VGA BIOS when still in real mode. 129This can result in direct reboots. 130In that case, use 131.Sq 2 132or 133.Ic vbetool post 134from the 135.Pa pkgsrc/sysutils/vbetool 136package. 137.It 2 138Call the VGA BIOS using the in-kernel x86 emulator. 139.El 140.Pp 141If the system has problems in resuming from the S3 142state, experimenting with different values may provide a solution. 143.It Ic hw.acpi.stat.gpe 144The number of dispatched General Purpose Events (GPEs). 145.It Ic hw.acpi.stat.sci 146The number of System Control Interrupts (SCIs). 147See 148.Xr acpiec 4 149for a brief description of both GPEs and SCIs. 150.It Ic hw.acpi.stat.fixed 151The number of 152.Dq fixed events . 153.It Ic hw.acpi.stat.method 154The number of AML methods executed by the interpreter. 155.It Ic hw.acpi.power 156This read-only node describes the ACPI power state of devices. 157The values range from D0 158.Pq Dq on 159to D3 160.Pq Dq off . 161.It Ic hw.acpi.wake 162This node represents devices that can wake the system from the S3 or 163S4 sleep state. 164By default, 165.Xr acpibut 4 , 166.Xr acpilid 4 , 167and 168.Xr pckbd 4 169are allowed to wake the system, provided that the devices are present and 170the firmware supports wake-up capabilities for the devices. 171.El 172.Sh SUPPORTED DEVICES 173.Nx 174ACPI supports several machine-dependent and machine-independent devices, 175some specific to ACPI and some configured via it. 176.Ss Machine-independent devices 177.Bl -tag -width "thinkpad(4) " -offset indent -compact 178.It Xr acpiacad 4 179ACPI AC adapters. 180.It Xr acpibat 4 181ACPI batteries. 182.It Xr acpibut 4 183ACPI power and sleep buttons. 184.It Xr acpicpu 4 185ACPI processors. 186.It Xr acpidalb 4 187ACPI direction application launch buttons. 188.It Xr acpiec 4 189ACPI embedded controllers. 190.It Xr acpiecdt 4 191ACPI Embedded Controller Boot Resource Table (ECDT). 192.It Xr acpifan 4 193ACPI fans. 194.It Xr acpilid 4 195ACPI lid switches. 196.It Xr acpipmtr 4 197ACPI power meters. 198.It Xr acpismbus 4 199ACPI SMBus via control method interface (CMI). 200.It Xr acpitz 4 201ACPI thermal zones. 202.It Xr acpivga 4 203ACPI display adapter and output devices. 204.It Xr acpiwmi 4 205ACPI support for Windows Management Instrumentation. 206.It Xr acpiwdrt 4 207ACPI watchdogs. 208.It Xr aibs 4 209ASUSTeK voltage, temperature and fan sensors. 210.It Xr asus 4 211ASUS laptop hotkeys. 212.It Xr attimer 4 213AT Timer. 214.It Xr com 4 215NS8250-, NS16450-, and NS16550-based serial ports. 216.It Xr fdc 4 217Floppy disk controllers. 218.It Xr fujbp 4 219Fujitsu brightness and pointer. 220.It Xr fujhk 4 221Fujitsu hotkeys. 222.It Xr hpacel 4 223HP 3D DriveGuard accelerometer. 224.It Xr hpet 4 225High Precision Event Timer (HPET). 226.It Xr hpqlb 4 227HP Quick Launch Buttons. 228.It Xr joy 4 229Joystick/Game port interface. 230.It Xr lpt 4 231Standard ISA parallel port interface. 232.It Xr mpu 4 233Roland MPU-401 (compatible) MIDI UART. 234.It Xr pcppi 4 235AT-style speaker sound. 236.It Xr sdhc 4 237SD Host Controller. 238.It Xr thinkpad 4 239IBM/Lenovo ThinkPad laptop device driver. 240.It Xr ug 4 241Abit uGuru Hardware monitor. 242.It Xr vald 4 243Toshiba Libretto device. 244.It Xr valz 4 245Toshiba Dynabook device. 246.It Xr wb 4 247Winbond W83L518D Integrated Media Reader. 248.It Xr wss 4 249Windows Sound System-compatible sound cards 250.It Xr ym 4 251Yamaha OPL3-SA2 and OPL3-SA3 audio device driver. 252.El 253.Ss i386-dependent devices 254.Bl -tag -width "thinkpad(4) " -offset indent -compact 255.It Xr pckbc 4 256PC keyboard controllers. 257.It Xr sony 4 258Sony Miscellaneous Controller 259.It Xr spic 4 260Sony programmable I/O controller. 261.El 262.Sh DEBUGGING 263Although the situation has become better over the years, 264ACPI is typically prone to various errors, 265ranging from blatant flaws in the firmware to bugs in the implementation. 266Before anything else, it is a good practice to upgrade the BIOS 267to the latest version available from the vendor. 268.Pp 269To ease the task of diagnosing and fixing different problems, the 270ACPICA reference implementation provides a rich 271facility of different debugging methods. 272In 273.Nx 274these are generally only available if the kernel has been compiled with the 275.Dv ACPI_DEBUG 276option. 277.Ss Verbose messages 278The 279.Dv ACPIVERBOSE 280compile time option enables some verbose 281debug messages printed during the system startup. 282In a 283.Dv MODULAR 284(see 285.Xr options 4 ) 286system, the information can be printed also at runtime, 287regardless of the presence of 288.Dv ACPIVERBOSE . 289To print the messages, 290.Xr modload 8 291the 292.Ic acpiverbose 293module using the option 294.Fl b Cm dump=true . 295.Ss Custom DSDT 296ACPI interprets bytecode known as ACPI Machine Language (AML), 297provided by the BIOS as a memory image during the system bootstrap. 298Most of the AML relevant to 299.Nm 300is implemented in the so-called 301Differentiated System Descriptor Table (DSDT). 302.Nx 303provides support for overriding the default DSDT supplied by the BIOS. 304.Pp 305The following steps can be used to override the DSDT: 306.Bl -enum -offset indent 307.It 308Dump the raw DSDT with 309.Xr acpidump 8 . 310.It 311Disassemble the table with 312.Xr iasl 8 . 313.It 314Modify the disassembled table. 315.It 316Compile the table with 317.Xr iasl 8 318using the option 319.Fl tc . 320.It 321Either copy the 322.Pq Pa *.hex 323file to 324.Bd -literal -offset indent 325src/sys/dev/acpi/acpica/Osd/custom_dsdt.hex 326.Ed 327.Pp 328or use the option 329.Bd -literal -offset indent 330ACPI_DSDT_FILE="/some/directory/custom_dsdt.hex" 331.Ed 332.Pp 333in the kernel configuration file. 334.It 335Define 336.Dv ACPI_DSDT_OVERRIDE 337in the kernel configuration file and rebuild. 338.El 339.Ss Debugger 340The ACPICA interpreter provides its own debugger for low-level debugging. 341It can be used to display internal data structures and namespace objects, 342and to debug the execution of control methods. 343Single step and breakpoint functionality are available. 344In 345.Nx 346this is integrated to the in-kernel 347.Xr ddb 4 . 348In order to enter the ACPICA debugger from 349.Xr ddb 4 , 350use the command 351.Ic call 352with the argument 353.Ic acpi_osd_debugger . 354.Ss Debug Output 355.Nx 356provides three 357.Xr sysctl 8 358variables that control the debug output at runtime. 359The 360.Ic hw.acpi.debug.layer 361variable limits the output to a specific ACPI layer and the 362.Ic hw.acpi.debug.level 363variable controls the debug level. 364Both 365.Xr sysctl 8 366variables are string literals. 367The third variable is 368.Ic hw.acpi.debug.object . 369This is a boolean that controls whether debug messages internal to the 370AML are enabled. 371.Pp 372For the first two variables, the possible values are: 373.Bl -column -offset indent \ 374"ACPI_RESOURCE_COMPONENT " "ACPI_RESOURCE_COMPONENT " 375.It Sy LAYER Ta Sy LEVEL 376.It Dv ACPI_DEBUG_NONE Ta Dv ACPI_DEBUG_NONE 377.It Ta 378.It Dv ACPI_UTILITIES Ta Dv ACPI_LV_INIT 379.It Dv ACPI_HARDWARE Ta Dv ACPI_LV_DEBUG_OBJECT 380.It Dv ACPI_EVENTS Ta Dv ACPI_LV_INFO 381.It Dv ACPI_TABLES Ta Dv ACPI_LV_ALL_EXCEPTIONS No * 382.It Dv ACPI_NAMESPACE Ta 383.It Dv ACPI_PARSER Ta Dv ACPI_LV_INIT_NAMES 384.It Dv ACPI_DISPATCHER Ta Dv ACPI_LV_PARSE 385.It Dv ACPI_EXECUTER Ta Dv ACPI_LV_LOAD 386.It Dv ACPI_RESOURCES Ta Dv ACPI_LV_DISPATCH 387.It Dv ACPI_CA_DEBUGGER Ta Dv ACPI_LV_EXEC 388.It Dv ACPI_OS_SERVICES Ta Dv ACPI_LV_NAMES 389.It Dv ACPI_CA_DISASSEMBLER Ta Dv ACPI_LV_OPREGION 390.It Dv ACPI_COMPILER Ta Dv ACPI_LV_BFIELD 391.It Dv ACPI_TOOLS Ta Dv ACPI_LV_TABLES 392.It Dv ACPI_EXAMPLE Ta Dv ACPI_LV_VALUES 393.It Dv ACPI_DRIVER Ta Dv ACPI_LV_OBJECTS 394.It Dv ACPI_ALL_COMPONENTS No * Ta Dv ACPI_LV_RESOURCES 395.It Ta Dv ACPI_LV_USER_REQUESTS 396.It Dv ACPI_BUS_COMPONENT Ta Dv ACPI_LV_PACKAGE 397.It Dv ACPI_ACAD_COMPONENT Ta Dv ACPI_LV_VERBOSITY1 No * 398.It Dv ACPI_BAT_COMPONENT Ta 399.It Dv ACPI_BUTTON_COMPONENT Ta Dv ACPI_LV_ALLOCATIONS 400.It Dv ACPI_EC_COMPONENT Ta Dv ACPI_LV_FUNCTIONS 401.It Dv ACPI_LID_COMPONENT Ta Dv ACPI_LV_OPTIMIZATIONS 402.It Dv ACPI_RESOURCE_COMPONENT Ta Dv ACPI_LV_VERBOSITY2 No * 403.It Dv ACPI_TZ_COMPONENT Ta 404.It Dv ACPI_DISPLAY_COMPONENT Ta 405.It Dv ACPI_ALL_DRIVERS No * Ta Dv ACPI_LV_MUTEX 406.It Ta Dv ACPI_LV_THREADS 407.It Ta Dv ACPI_LV_IO 408.It Ta Dv ACPI_LV_AML_INTERRUPTS 409.It "* This is a compound" Ta Dv ACPI_LV_VERBOSITY3 No * 410.It " constant, including" Ta 411.It " all previous elements." Ta Dv ACPI_LV_AML_DISASSEMBLE 412.It Ta Dv ACPI_LV_VERBOSE_INFO 413.It Ta Dv ACPI_LV_FULL_TABLES 414.It Ta Dv ACPI_LV_EVENTS 415.It Ta Dv ACPI_LV_VERBOSE No * 416.El 417.Pp 418In addition, there is 419.Dv ACPI_DEBUG_DEFAULT 420that is used by ACPICA as the default debug level. 421It includes 422.Dv ACPI_LV_INIT 423and 424.Dv ACPI_LV_DEBUG_OBJECT . 425.Pp 426The debug layer can be divided into two groups: 427the first one is specific to the ACPICA 428interpreter and the second one contains the internal ACPI 429components of 430.Nx . 431The constant 432.Dv ACPI_ALL_DRIVERS 433includes all 434.Nx 435specific parts. 436.Pp 437The ACPICA interpreter uses several debug levels internally, 438but the 439.Nx 440specific parts are typically limited to 441.Dv ACPI_LV_DEBUG_OBJECT 442and 443.Dv ACPI_LV_INFO . 444The debug output can be stopped by setting 445.Ic hw.acpi.debug.level 446to 447.Dv ACPI_DEBUG_NONE . 448.Ss Example 449As an example, a driver may have defined the component it belongs to and 450the name of the module: 451.Bd -literal -offset indent 452#define _COMPONENT ACPI_BUS_COMPONENT 453ACPI_MODULE_NAME ("acpi_example") 454.Ed 455.Pp 456The driver may also utilize the debug facility: 457.Bd -literal -offset indent 458ACPI_DEBUG_PRINT((ACPI_DB_INFO, "Failed to evaluate _STA\\n")); 459.Ed 460.Pp 461With these options the debug message from the 462.Dv ACPI_DEBUG_PRINT 463macro is only visible when 464.Ic hw.acpi.debug.layer 465is either 466.Dv ACPI_BUS_COMPONENT 467or a compound constant including it, and 468.Ic hw.acpi.debug.level 469is 470.Dv ACPI_LV_INFO 471or some constant that includes it. 472Finally, it can be noted that the ACPI implementation uses the prefix 473.Dv ACPI_DB , 474whereas the debug level 475.Xr sysctl 8 476variable is always specified with the prefix 477.Dv ACPI_LV . 478.Pp 479Another example can be mentioned for the use of 480.Ic hw.acpi.debug.object . 481The following could appear in an ASL code: 482.Bd -literal -offset indent 483Method(_Q19, 0, NotSerialized) 484{ 485 Store("_Q19 invoked", Debug) 486 Notify(ACAD, 0x80) 487} 488.Ed 489.Pp 490When 491.Ic hw.acpi.debug.object 492is set to 1, the message stored to the debug object 493is printed every time the method is called by the interpreter. 494.Sh FILES 495.Bl -tag -width /dev/acpi 496.It Pa /dev/acpi 497.El 498.Sh SEE ALSO 499.Xr ioapic 4 , 500.Xr acpidump 8 , 501.Xr amldb 8 , 502.Xr iasl 8 503.Rs 504.%A Hewlett-Packard Corporation 505.%A Intel Corporation 506.%A Microsoft Corporation 507.%A Phoenix Technologies Ltd. 508.%A Toshiba Corporation 509.%T Advanced Configuration and Power Interface Specification 510.%N Revision 4.0 511.%D June 16, 2009 512.%U http://www.acpi.info/spec.htm 513.Re 514.Rs 515.%A Intel Corporation 516.%T ACPI Component Architecture, 517.%T Programmer Reference, 518.%T OS-Independent Subsystem, Debugger, and Utilities 519.%N Revision 1.27 520.%D January 20, 2010 521.%U http://www.acpica.org/download/acpica-reference.pdf 522.Re 523.Rs 524.%A Len Brown 525.%T ACPI in Linux - Myths vs. Reality 526.%D June 27-30, 2007 527.%O Proceedings of the Linux Symposium 528.%P 65-74 529.%U http://www.linuxsymposium.org/archives/OLS/Reprints-2007/brown_1-Reprint.pdf 530.Re 531.Rs 532.%A Joerg Sonnenberger 533.%A Jared D. McNeill 534.%T Sleeping Beauty - NetBSD on Modern Laptops 535.%D February 3, 2008 536.%O Proceedings of AsiaBSDCon 2008 537.%P 127-134 538.%U https://2008.asiabsdcon.org/papers/P9A-paper.pdf 539.Re 540.Rs 541.%A Takanori Watanabe 542.%T ACPI Implementation on FreeBSD 543.%I USENIX Association 544.%B Proceedings of the FREENIX Track: 2002 USENIX Annual Technical Conference 545.%P 121-131 546.%D June 10-15, 2002 547.%U https://www.usenix.org/legacy/event/usenix02/tech/freenix/full_papers/watanabe/watanabe.pdf 548.Re 549.Sh HISTORY 550The 551.Nm 552driver 553appeared in 554.Nx 1.6 . 555.Sh AUTHORS 556.An -nosplit 557Authors of the 558.Nm 559subsystem include 560.An Charles M. Hannum , 561.An Frank van der Linden , 562.An Jared D. McNeill , 563.An Jason R. Thorpe , 564.An Joerg Sonnenberger , 565and 566.An Jukka Ruohonen , 567among others. 568.Sh BUGS 569Most of the ACPI power management functionalities are not implemented. 570.Pp 571The 572.Dv ACPI__DIS_IS_BROKEN 573option should not be necessary. 574