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