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