1.\" $NetBSD: acpi.4,v 1.78 2014/09/14 19:54:05 mrg 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 September 8, 2014 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 thinkpad 4 305IBM/Lenovo ThinkPad laptop device driver. 306.It Xr ug 4 307Abit uGuru Hardware monitor. 308.It Xr vald 4 309Toshiba Libretto device. 310.It Xr wb 4 311Winbond W83L518D Integrated Media Reader. 312.It Xr wss 4 313Windows Sound System-compatible sound cards 314.It Xr ym 4 315Yamaha OPL3-SA2 and OPL3-SA3 audio device driver. 316.El 317.Ss i386-dependent devices 318.Bl -tag -width "thinkpad(4) " -offset indent -compact 319.It Xr npx 4 320i386 numeric processing extension coprocessor. 321.It Xr pckbc 4 322PC keyboard controllers. 323.It Xr sony 4 324Sony Miscellaneous Controller 325.It Xr spic 4 326Sony programmable I/O controller. 327.El 328.Sh DEBUGGING 329Although the situation has become better over the years, 330.Tn ACPI 331is typically prone to various errors, 332ranging from blatant flaws in the firmware to bugs in the implementation. 333Before anything else, it is a good practice to upgrade the 334.Tn BIOS 335to the latest version available from the vendor. 336.Pp 337To ease the task of diagnosing and fixing different problems, the 338.Tn ACPICA 339reference implementation provides a rich 340facility of different debugging methods. 341In 342.Nx 343these are generally only available if the kernel has been compiled with the 344.Tn ACPI_DEBUG 345option. 346.Ss Verbose messages 347The 348.Tn ACPIVERBOSE 349compile time option enables some verbose 350debug messages printed during the system startup. 351In a 352.Tn MODULAR 353(see 354.Xr options 4 ) 355system, the information can be printed also at runtime, 356regardless of the presence of 357.Tn ACPIVERBOSE . 358To print the messages, 359.Xr modload 8 360the 361.Ic acpiverbose 362module using the option 363.Ar -b dump=true . 364.Ss Custom DSDT 365.Tn ACPI 366interprets bytecode known as 367.Tn ACPI 368Machine Language 369.Pq Tn AML , 370provided by the 371.Tn BIOS 372as a memory image during the system bootstrap. 373Most of the 374.Tn AML 375relevant to 376.Nm 377is implemented in the so-called 378Differentiated System Descriptor Table 379.Pq Tn DSDT . 380.Nx 381provides support for overriding the default 382.Tn DSDT 383supplied by the 384.Tn BIOS . 385.Pp 386The following steps can be used to override the 387.Tn DSDT : 388.Bl -enum -offset indent 389.It 390Dump the raw 391.Tn DSDT 392with 393.Xr acpidump 8 . 394.It 395Disassemble the table with 396.Xr iasl 8 . 397.It 398Modify the disassembled table. 399.It 400Compile the table with 401.Xr iasl 8 402using the option 403.Ar \-tc . 404.It 405Either copy the 406.Pq Pa *.hex 407file to 408.Bd -literal -offset indent 409src/sys/dev/acpi/acpica/Osd/custom_dsdt.hex 410.Ed 411.Pp 412or use the option 413.Bd -literal -offset indent 414ACPI_DSDT_FILE="/some/directory/custom_dsdt.hex" 415.Ed 416.Pp 417in the kernel configuration file. 418.It 419Define 420.Tn ACPI_DSDT_OVERRIDE 421in the kernel configuration file and rebuild. 422.El 423.Ss Debugger 424The 425.Tn ACPICA 426interpreter provides its own debugger for low-level debugging. 427It can be used to display internal data structures and namespace objects, 428and to debug the execution of control methods. 429Single step and breakpoint functionality are available. 430In 431.Nx 432this is integrated to the in-kernel 433.Xr ddb 4 . 434In order to enter the 435.Tn ACPICA 436debugger from 437.Xr ddb 4 , 438use the command 439.Ic call 440with the argument 441.Ic acpi_osd_debugger . 442.Ss Debug Output 443.Nx 444provides three 445.Xr sysctl 8 446variables that control the debug output at runtime. 447The 448.Ic hw.acpi.debug.layer 449variable limits the output to a specific 450.Tn ACPI 451layer and the 452.Ic hw.acpi.debug.level 453variable controls the debug level. 454Both 455.Xr sysctl 8 456variables are string literals. 457The third variable is 458.Ic hw.acpi.debug.object . 459This is a boolean that controls whether debug messages internal to the 460.Tn AML 461are enabled. 462.Pp 463For the first two variables, the possible values are: 464.Bl -column -offset indent \ 465"ACPI_RESOURCE_COMPONENT " "ACPI_RESOURCE_COMPONENT " 466.It Sy LAYER Ta Sy LEVEL 467.It Li ACPI_DEBUG_NONE Ta ACPI_DEBUG_NONE 468.It Ta 469.It Li ACPI_UTILITIES Ta ACPI_LV_INIT 470.It Li ACPI_HARDWARE Ta ACPI_LV_DEBUG_OBJECT 471.It Li ACPI_EVENTS Ta ACPI_LV_INFO 472.It Li ACPI_TABLES Ta ACPI_LV_ALL_EXCEPTIONS * 473.It Li ACPI_NAMESPACE Ta 474.It Li ACPI_PARSER Ta ACPI_LV_INIT_NAMES 475.It Li ACPI_DISPATCHER Ta ACPI_LV_PARSE 476.It Li ACPI_EXECUTER Ta ACPI_LV_LOAD 477.It Li ACPI_RESOURCES Ta ACPI_LV_DISPATCH 478.It Li ACPI_CA_DEBUGGER Ta ACPI_LV_EXEC 479.It Li ACPI_OS_SERVICES Ta ACPI_LV_NAMES 480.It Li ACPI_CA_DISASSEMBLER Ta ACPI_LV_OPREGION 481.It Li ACPI_COMPILER Ta ACPI_LV_BFIELD 482.It Li ACPI_TOOLS Ta ACPI_LV_TABLES 483.It Li ACPI_EXAMPLE Ta ACPI_LV_VALUES 484.It Li ACPI_DRIVER Ta ACPI_LV_OBJECTS 485.It Li ACPI_ALL_COMPONENTS * Ta ACPI_LV_RESOURCES 486.It Ta ACPI_LV_USER_REQUESTS 487.It Li ACPI_BUS_COMPONENT Ta ACPI_LV_PACKAGE 488.It Li ACPI_ACAD_COMPONENT Ta ACPI_LV_VERBOSITY1 * 489.It Li ACPI_BAT_COMPONENT Ta 490.It Li ACPI_BUTTON_COMPONENT Ta ACPI_LV_ALLOCATIONS 491.It Li APCI_EC_COMPONENT Ta ACPI_LV_FUNCTIONS 492.It Li ACPI_LID_COMPONENT Ta ACPI_LV_OPTIMIZATIONS 493.It Li ACPI_RESOURCE_COMPONENT Ta ACPI_LV_VERBOSITY2 * 494.It Li ACPI_TZ_COMPONENT Ta 495.It Li ACPI_DISPLAY_COMPONENT Ta 496.It Li ACPI_ALL_DRIVERS * Ta ACPI_LV_MUTEX 497.It Ta ACPI_LV_THREADS 498.It Ta ACPI_LV_IO 499.It Ta ACPI_LV_AML_INTERRUPTS 500.It Li "* This is a compound" Ta ACPI_LV_VERBOSITY3 * 501.It Li " constant, including" Ta 502.It Li " all previous elements." Ta ACPI_LV_AML_DISASSEMBLE 503.It Ta ACPI_LV_VERBOSE_INFO 504.It Ta ACPI_LV_FULL_TABLES 505.It Ta ACPI_LV_EVENTS 506.It Ta ACPI_LV_VERBOSE * 507.El 508.Pp 509In addition, there is 510.Dv ACPI_DEBUG_DEFAULT 511that is used by 512.Tn ACPICA 513as the default debug level. 514It includes 515.Dv ACPI_LV_INIT 516and 517.Dv ACPI_LV_DEBUG_OBJECT . 518.Pp 519The debug layer can be divided into two groups: 520the first one is specific to the 521.Tn ACPICA 522interpreter and the second one contains the internal 523.Tn ACPI 524components of 525.Nx . 526The constant 527.Dv ACPI_ALL_DRIVERS 528includes all 529.Nx 530specific parts. 531.Pp 532The 533.Tn ACPICA 534interpreter uses several debug levels internally, 535but the 536.Nx 537specific parts are typically limited to 538.Dv ACPI_LV_DEBUG_OBJECT 539and 540.Dv ACPI_LV_INFO . 541The debug output can be stopped by setting 542.Ic hw.acpi.debug.level 543to 544.Dv ACPI_DEBUG_NONE . 545.Ss Example 546As an example, a driver may have defined the component it belongs to and 547the name of the module: 548.Bd -literal -offset indent 549#define _COMPONENT ACPI_BUS_COMPONENT 550ACPI_MODULE_NAME ("acpi_example") 551.Ed 552.Pp 553The driver may also utilize the debug facility: 554.Bd -literal -offset indent 555ACPI_DEBUG_PRINT((ACPI_DB_INFO, "Failed to evaluate _STA\\n")); 556.Ed 557.Pp 558With these options the debug message from the 559.Dv ACPI_DEBUG_PRINT 560macro is only visible when 561.Ic hw.acpi.debug.layer 562is either 563.Dv ACPI_BUS_COMPONENT 564or a compound constant including it, and 565.Ic hw.acpi.debug.level 566is 567.Dv ACPI_LV_INFO 568or some constant that includes it. 569Finally, it can be noted that the 570.Tn ACPI 571implementation uses the prefix 572.Dv ACPI_DB , 573whereas the debug level 574.Xr sysctl 8 575variable is always specified with the prefix 576.Dv ACPI_LV . 577.Pp 578Another example can be mentioned for the use of 579.Ic hw.acpi.debug.object . 580The following could appear in an 581.Tn ASL 582code: 583.Bd -literal -offset indent 584Method(_Q19, 0, NotSerialized) 585{ 586 Store("_Q19 invoked", Debug) 587 Notify(ACAD, 0x80) 588} 589.Ed 590.Pp 591When 592.Ic hw.acpi.debug.object 593is set to 1, the message stored to the debug object 594is printed every time the method is called by the interpreter. 595.Sh SEE ALSO 596.Xr ioapic 4 , 597.Xr acpidump 8 , 598.Xr amldb 8 , 599.Xr iasl 8 600.Rs 601.%A Hewlett-Packard Corporation 602.%A Intel Corporation 603.%A Microsoft Corporation 604.%A Phoenix Technologies Ltd. 605.%A Toshiba Corporation 606.%T Advanced Configuration and Power Interface Specification 607.%N Revision 4.0 608.%D June 16, 2009 609.%U http://www.acpi.info/spec.htm 610.Re 611.Rs 612.%A Intel Corporation 613.%T ACPI Component Architecture, 614.%T Programmer Reference, 615.%T OS-Independent Subsystem, Debugger, and Utilities 616.%N Revision 1.27 617.%D January 20, 2010 618.%U http://www.acpica.org/download/acpica-reference.pdf 619.Re 620.Rs 621.%A Len Brown 622.%T ACPI in Linux - Myths vs. Reality 623.%D June 27-30, 2007 624.%O Proceedings of the Linux Symposium 625.%P 65-74 626.%U http://www.linuxsymposium.org/archives/OLS/Reprints-2007/brown_1-Reprint.pdf 627.Re 628.Rs 629.%A Joerg Sonnenberger 630.%A Jared D. McNeill 631.%T Sleeping Beauty - NetBSD on Modern Laptops 632.%D February 3, 2008 633.%O Proceedings of AsiaBSDCon 2008 634.%P 127-134 635.%U http://2008.asiabsdcon.org/papers/P9A-paper.pdf 636.Re 637.Rs 638.%A Takanori Watanabe 639.%T ACPI Implementation on FreeBSD 640.%I USENIX Association 641.%B Proceedings of the FREENIX Track: 2002 USENIX Annual Technical Conference 642.%P 121-131 643.%D June 10-15, 2002 644.%U http://www.usenix.org/event/usenix02/tech/freenix/full_papers/watanabe/watanabe.pdf 645.Re 646.Sh HISTORY 647The 648.Nm 649driver 650appeared in 651.Nx 1.6 . 652.Sh AUTHORS 653.An -nosplit 654Authors of the 655.Nm 656subsystem include 657.An Charles M. Hannum , 658.An Frank van der Linden , 659.An Jared D. McNeill , 660.An Jason R. Thorpe , 661.An Joerg Sonnenberger , 662and 663.An Jukka Ruohonen , 664among others. 665.Sh BUGS 666Most of the 667.Tn ACPI 668power management functionalities are not implemented. 669.Pp 670The 671.Dv ACPI__DIS_IS_BROKEN 672option should not be necessary. 673