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