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