1.\" 2.\" Copyright (c) 2001 Michael Smith 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd June 2, 2010 29.Dt ACPI 4 30.Os 31.Sh NAME 32.Nm acpi 33.Nd Advanced Configuration and Power Management support 34.Sh SYNOPSIS 35.Cd "device acpi" 36.Pp 37.Cd "options ACPI_DEBUG" 38.Cd "options DDB" 39.Sh DESCRIPTION 40The 41.Nm 42driver provides support for the Intel/Microsoft/Compaq/Toshiba ACPI 43standard. 44This support includes platform hardware discovery (superseding the 45PnP and PCI BIOS), as well as power management (superseding APM) and 46other features. 47ACPI core support is provided by the ACPI CA reference implementation 48from Intel. 49.Pp 50Note that the 51.Nm 52driver is automatically loaded by the 53.Xr loader 8 , 54and should only be 55compiled into the kernel on platforms where ACPI is mandatory. 56.Sh SYSCTL VARIABLES 57The 58.Nm 59driver is intended to provide power management without user intervention. 60If the default settings are not optimal, the following sysctls can be 61used to modify or monitor 62.Nm 63behavior. 64.Bl -tag -width indent 65.It Va debug.acpi.enable_debug_objects 66Enable dumping Debug objects without 67.Cd "options ACPI_DEBUG" . 68Default is 0, ignore Debug objects. 69.It Va hw.acpi.acline 70AC line state (1 means online, 0 means on battery power). 71.It Va hw.acpi.cpu.cx_usage 72Debugging information listing the percent of total usage for each sleep state. 73The values are reset when 74.Va hw.acpi.cpu.cx_lowest 75is modified. 76.It Va hw.acpi.cpu.cx_lowest 77Lowest Cx state to use for idling the CPU. 78A scheduling algorithm will select states between 79.Li C1 80and this setting 81as system load dictates. 82To enable ACPI CPU idling control, 83.Va machdep.cpu_idle_hlt 84must be set to 1. 85.It Va hw.acpi.cpu.cx_supported 86List of supported CPU idle states and their transition latency 87in microseconds. 88Each state has a type (e.g., 89.Li C2 ) . 90.Li C1 91is equivalent to the ia32 92.Li HLT 93instruction, 94.Li C2 95provides a deeper 96sleep with the same semantics, and 97.Li C3 98provides the deepest sleep 99but additionally requires bus mastering to be disabled. 100States greater than 101.Li C3 102provide even more power savings with the same 103semantics as the 104.Li C3 105state. 106Deeper sleeps provide more power savings but increased transition 107latency when an interrupt occurs. 108.It Va hw.acpi.disable_on_reboot 109Disable ACPI during the reboot process. 110Most systems reboot fine with ACPI still enabled, but some require 111exiting to legacy mode first. 112Default is 0, leave ACPI enabled. 113.It Va hw.acpi.handle_reboot 114Use the ACPI Reset Register capability to reboot the system. 115Default is 0, use legacy reboot support. 116Some newer systems require use of this register, while some only work 117with legacy rebooting support. 118.It Va hw.acpi.lid_switch_state 119Suspend state 120.Pq Li S1 Ns \[en] Ns Li S5 121to enter when the lid switch (i.e., a notebook screen) is closed. 122Default is 123.Dq Li NONE 124(do nothing). 125.It Va hw.acpi.power_button_state 126Suspend state 127.Pq Li S1 Ns \[en] Ns Li S5 128to enter when the power button is pressed. 129Default is 130.Li S5 131(power-off nicely). 132.It Va hw.acpi.reset_video 133Reset the video adapter from real mode during the resume path. 134Some systems need this help, others have display problems if it is enabled. 135Default is 0 (disabled). 136.It Va hw.acpi.s4bios 137Indicate whether the system supports 138.Li S4BIOS . 139This means that the BIOS can handle all the functions of suspending the 140system to disk. 141Otherwise, the OS is responsible for suspending to disk 142.Pq Li S4OS . 143Most current systems do not support 144.Li S4BIOS . 145.It Va hw.acpi.sleep_button_state 146Suspend state 147.Pq Li S1 Ns \[en] Ns Li S5 148to enter when the sleep button is pressed. 149This is usually a special function button on the keyboard. 150Default is 151.Li S3 152(suspend-to-RAM). 153.It Va hw.acpi.sleep_delay 154Wait this number of seconds between preparing the system to suspend and 155actually entering the suspend state. 156Default is 1 second. 157.It Va hw.acpi.supported_sleep_state 158Suspend states 159.Pq Li S1 Ns \[en] Ns Li S5 160supported by the BIOS. 161.Bl -tag -width indent 162.It Li S1 163Quick suspend to RAM. 164The CPU enters a lower power state, but most peripherals are left running. 165.It Li S2 166Lower power state than 167.Li S1 , 168but with the same basic characteristics. 169Not supported by many systems. 170.It Li S3 171Suspend to RAM. 172Most devices are powered off, and the system stops running except for 173memory refresh. 174.It Li S4 175Suspend to disk. 176All devices are powered off, and the system stops running. 177When resuming, the system starts as if from a cold power on. 178Not yet supported by 179.Fx 180unless 181.Li S4BIOS 182is available. 183.It Li S5 184System shuts down cleanly and powers off. 185.El 186.It Va hw.acpi.verbose 187Enable verbose printing from the various ACPI subsystems. 188.El 189.Sh LOADER TUNABLES 190Tunables can be set at the 191.Xr loader 8 192prompt before booting the kernel or stored in 193.Pa /boot/loader.conf . 194Many of these tunables also have a matching 195.Xr sysctl 8 196entry for access after boot. 197.Bl -tag -width indent 198.It Va acpi_dsdt_load 199Enables loading of a custom ACPI DSDT. 200.It Va acpi_dsdt_name 201Name of the DSDT table to load, if loading is enabled. 202.It Va debug.acpi.disabled 203Selectively disables portions of ACPI for debugging purposes. 204.It Va debug.acpi.interpreter_slack 205Enable less strict ACPI implementations. 206Default is 1, ignore common BIOS mistakes. 207.It Va debug.acpi.max_threads 208Specify the number of task threads that are started on boot. 209Limiting this to 1 may help work around various BIOSes that cannot 210handle parallel requests. 211The default value is 3. 212.It Va debug.acpi.quirks 213Override any automatic quirks completely. 214.It Va debug.acpi.resume_beep 215Beep the PC speaker on resume. 216This can help diagnose suspend/resume problems. 217Default is 0 (disabled). 218.It Va hint.acpi.0.disabled 219Set this to 1 to disable all of ACPI. 220If ACPI has been disabled on your system due to a blacklist entry for your 221BIOS, you can set this to 0 to re-enable ACPI for testing. 222.It Va hw.acpi.ec.poll_timeout 223Delay in milliseconds to wait for the EC to respond. 224Try increasing this number if you get the error 225.Qq Li AE_NO_HARDWARE_RESPONSE . 226.It Va hw.acpi.host_mem_start 227Override the assumed memory starting address for PCI host bridges. 228.It Va hw.acpi.reset_video 229Enables calling the VESA reset BIOS vector on the resume path. 230This can fix some graphics cards that have problems such as LCD white-out 231after resume. 232Default is 0 (disabled). 233.It Va hw.acpi.serialize_methods 234Allow override of whether methods execute in parallel or not. 235Enable this for serial behavior, which fixes 236.Qq Li AE_ALREADY_EXISTS 237errors for 238AML that really cannot handle parallel method execution. 239It is off by default since this breaks recursive methods and some IBMs use 240such code. 241.It Va hw.acpi.verbose 242Turn on verbose debugging information about what ACPI is doing. 243.It Va hw.pci.link.%s.%d.irq 244Override the interrupt to use for this link and index. 245This capability should be used carefully, and only if a device is not 246working with 247.Nm 248enabled. 249.Qq %s 250is the name of the link (e.g., LNKA). 251.Qq %d 252is the resource index when the link supports multiple IRQs. 253Most PCI links only have one IRQ resource, so the below form should be used. 254.It Va hw.pci.link.%s.irq 255Override the interrupt to use. 256This capability should be used carefully, and only if a device is not 257working with 258.Nm 259enabled. 260.Qq %s 261is the name of the link (e.g., LNKA). 262.El 263.Sh DISABLING ACPI 264Since ACPI support on different platforms varies greatly, there are many 265debugging and tuning options available. 266.Pp 267For machines known not to work with 268.Nm 269enabled, there is a BIOS blacklist. 270Currently, the blacklist only controls whether 271.Nm 272should be disabled or not. 273In the future, it will have more granularity to control features (the 274infrastructure for that is already there). 275.Pp 276To enable 277.Nm 278(for debugging purposes, etc.) on machines that are on the blacklist, set the 279kernel environment variable 280.Va hint.acpi.0.disabled 281to 0. 282Before trying this, consider updating your BIOS to a more recent version that 283may be compatible with ACPI. 284.Pp 285To disable the 286.Nm 287driver completely, set the kernel environment variable 288.Va hint.acpi.0.disabled 289to 1. 290.Pp 291Some i386 machines totally fail to operate with some or all of ACPI disabled. 292Other i386 machines fail with ACPI enabled. 293Disabling all or part of ACPI on non-i386 platforms (i.e., platforms where 294ACPI support is mandatory) may result in a non-functional system. 295.Pp 296The 297.Nm 298driver comprises a set of drivers, which may be selectively disabled 299in case of problems. 300To disable a sub-driver, list it in the kernel 301environment variable 302.Va debug.acpi.disabled . 303Multiple entries can be listed, separated by a space. 304.Pp 305ACPI sub-devices and features that can be disabled: 306.Bl -tag -width ".Li sysresource" 307.It Li all 308Disable all ACPI features and devices. 309.It Li acad 310.Pq Vt device 311Supports AC adapter. 312.It Li bus 313.Pq Vt feature 314Probes and attaches subdevices. 315Disabling will avoid scanning the ACPI namespace entirely. 316.It Li children 317.Pq Vt feature 318Attaches standard ACPI sub-drivers and devices enumerated in the 319ACPI namespace. 320Disabling this has a similar effect to disabling 321.Dq Li bus , 322except that the 323ACPI namespace will still be scanned. 324.It Li button 325.Pq Vt device 326Supports ACPI button devices (typically power and sleep buttons). 327.It Li cmbat 328.Pq Vt device 329Control-method batteries device. 330.It Li cpu 331.Pq Vt device 332Supports CPU power-saving and speed-setting functions. 333.It Li ec 334.Pq Vt device 335Supports the ACPI Embedded Controller interface, used to communicate 336with embedded platform controllers. 337.It Li isa 338.Pq Vt device 339Supports an ISA bus bridge defined in the ACPI namespace, 340typically as a child of a PCI bus. 341.It Li lid 342.Pq Vt device 343Supports an ACPI laptop lid switch, which typically puts a 344system to sleep. 345.It Li quirks 346.Pq Vt feature 347Do not honor quirks. 348Quirks automatically disable ACPI functionality based on the XSDT table's 349OEM vendor name and revision date. 350.It Li pci 351.Pq Vt device 352Supports Host to PCI bridges. 353.It Li pci_link 354.Pq Vt feature 355Performs PCI interrupt routing. 356.It Li sysresource 357.Pq Vt device 358Pseudo-devices containing resources which ACPI claims. 359.It Li thermal 360.Pq Vt device 361Supports system cooling and heat management. 362.It Li timer 363.Pq Vt device 364Implements a timecounter using the ACPI fixed-frequency timer. 365.It Li video 366.Pq Vt device 367Supports 368.Xr acpi_video 4 369which may conflict with 370.Xr agp 4 371device. 372.El 373.Pp 374It is also possible to avoid portions of the ACPI namespace which 375may be causing problems, by listing the full path of the root of 376the region to be avoided in the kernel environment variable 377.Va debug.acpi.avoid . 378The object and all of its children will be ignored during the 379bus/children scan of the namespace. 380The ACPI CA code will still know about the avoided region. 381.Sh DEBUGGING OUTPUT 382To enable debugging output, 383.Nm 384must be compiled with 385.Cd "options ACPI_DEBUG" . 386Debugging output is separated between layers and levels, where a layer is 387a component of the ACPI subsystem, and a level is a particular kind 388of debugging output. 389.Pp 390Both layers and levels are specified as a whitespace-separated list of 391tokens, with layers listed in 392.Va debug.acpi.layer 393and levels in 394.Va debug.acpi.level . 395.Pp 396The first set of layers is for ACPI-CA components, and the second is for 397.Fx 398drivers. 399The ACPI-CA layer descriptions include the prefix for the files they 400refer to. 401The supported layers are: 402.Pp 403.Bl -tag -compact -width ".Li ACPI_CA_DISASSEMBLER" 404.It Li ACPI_UTILITIES 405Utility ("ut") functions 406.It Li ACPI_HARDWARE 407Hardware access ("hw") 408.It Li ACPI_EVENTS 409Event and GPE ("ev") 410.It Li ACPI_TABLES 411Table access ("tb") 412.It Li ACPI_NAMESPACE 413Namespace evaluation ("ns") 414.It Li ACPI_PARSER 415AML parser ("ps") 416.It Li ACPI_DISPATCHER 417Internal representation of interpreter state ("ds") 418.It Li ACPI_EXECUTER 419Execute AML methods ("ex") 420.It Li ACPI_RESOURCES 421Resource parsing ("rs") 422.It Li ACPI_CA_DEBUGGER 423Debugger implementation ("db", "dm") 424.It Li ACPI_OS_SERVICES 425Usermode support routines ("os") 426.It Li ACPI_CA_DISASSEMBLER 427Disassembler implementation (unused) 428.It Li ACPI_ALL_COMPONENTS 429All the above ACPI-CA components 430.It Li ACPI_AC_ADAPTER 431AC adapter driver 432.It Li ACPI_BATTERY 433Control-method battery driver 434.It Li ACPI_BUS 435ACPI, ISA, and PCI bus drivers 436.It Li ACPI_BUTTON 437Power and sleep button driver 438.It Li ACPI_EC 439Embedded controller driver 440.It Li ACPI_FAN 441Fan driver 442.It Li ACPI_OEM 443Platform-specific driver for hotkeys, LED, etc. 444.It Li ACPI_POWER 445Power resource driver 446.It Li ACPI_PROCESSOR 447CPU driver 448.It Li ACPI_THERMAL 449Thermal zone driver 450.It Li ACPI_TIMER 451Timer driver 452.It Li ACPI_ALL_DRIVERS 453All the above 454.Fx 455ACPI drivers 456.El 457.Pp 458The supported levels are: 459.Pp 460.Bl -tag -compact -width ".Li ACPI_LV_AML_DISASSEMBLE" 461.It Li ACPI_LV_INIT 462Initialization progress 463.It Li ACPI_LV_DEBUG_OBJECT 464Stores to objects 465.It Li ACPI_LV_INFO 466General information and progress 467.It Li ACPI_LV_ALL_EXCEPTIONS 468All the previous levels 469.It Li ACPI_LV_PARSE 470.It Li ACPI_LV_DISPATCH 471.It Li ACPI_LV_EXEC 472.It Li ACPI_LV_NAMES 473.It Li ACPI_LV_OPREGION 474.It Li ACPI_LV_BFIELD 475.It Li ACPI_LV_TABLES 476.It Li ACPI_LV_VALUES 477.It Li ACPI_LV_OBJECTS 478.It Li ACPI_LV_RESOURCES 479.It Li ACPI_LV_USER_REQUESTS 480.It Li ACPI_LV_PACKAGE 481.It Li ACPI_LV_VERBOSITY1 482All the previous levels 483.It Li ACPI_LV_ALLOCATIONS 484.It Li ACPI_LV_FUNCTIONS 485.It Li ACPI_LV_OPTIMIZATIONS 486.It Li ACPI_LV_VERBOSITY2 487All the previous levels 488.It Li ACPI_LV_ALL 489Synonym for 490.Qq Li ACPI_LV_VERBOSITY2 491.It Li ACPI_LV_MUTEX 492.It Li ACPI_LV_THREADS 493.It Li ACPI_LV_IO 494.It Li ACPI_LV_INTERRUPTS 495.It Li ACPI_LV_VERBOSITY3 496All the previous levels 497.It Li ACPI_LV_AML_DISASSEMBLE 498.It Li ACPI_LV_VERBOSE_INFO 499.It Li ACPI_LV_FULL_TABLES 500.It Li ACPI_LV_EVENTS 501.It Li ACPI_LV_VERBOSE 502All levels after 503.Qq Li ACPI_LV_VERBOSITY3 504.It Li ACPI_LV_INIT_NAMES 505.It Li ACPI_LV_LOAD 506.El 507.Pp 508Selection of the appropriate layer and level values is important 509to avoid massive amounts of debugging output. 510For example, the following configuration is a good way to gather initial 511information. 512It enables debug output for both ACPI-CA and the 513.Nm 514driver, printing basic information about errors, warnings, and progress. 515.Bd -literal -offset indent 516debug.acpi.layer="ACPI_ALL_COMPONENTS ACPI_ALL_DRIVERS" 517debug.acpi.level="ACPI_LV_ALL_EXCEPTIONS" 518.Ed 519.Pp 520Debugging output by the ACPI CA subsystem is prefixed with the 521module name in lowercase, followed by a source line number. 522Output from the 523.Fx Ns -local 524code follows the same format, but 525the module name is uppercased. 526.Sh OVERRIDING YOUR BIOS BYTECODE 527ACPI interprets bytecode named AML 528(ACPI Machine Language) 529provided by the BIOS vendor as a memory image at boot time. 530Sometimes, the AML code contains a bug that does not appear when parsed 531by the Microsoft implementation. 532.Fx 533provides a way to override it with your own AML code to work around 534or debug such problems. 535Note that all AML in your DSDT and any SSDT tables is overridden. 536.Pp 537In order to load your AML code, you must edit 538.Pa /boot/loader.conf 539and include the following lines. 540.Bd -literal -offset indent 541acpi_dsdt_load="YES" 542acpi_dsdt_name="/boot/acpi_dsdt.aml" # You may change this name. 543.Ed 544.Pp 545In order to prepare your AML code, you will need the 546.Xr acpidump 8 547and 548.Xr iasl 8 549utilities and some ACPI knowledge. 550.Sh COMPATIBILITY 551ACPI is only found and supported on i386/ia32, ia64, and amd64. 552.Sh SEE ALSO 553.Xr kenv 1 , 554.Xr acpi_thermal 4 , 555.Xr device.hints 5 , 556.Xr loader.conf 5 , 557.Xr acpiconf 8 , 558.Xr acpidump 8 , 559.Xr config 8 , 560.Xr iasl 8 561.Rs 562.%A "Compaq Computer Corporation" 563.%A "Intel Corporation" 564.%A "Microsoft Corporation" 565.%A "Phoenix Technologies Ltd." 566.%A "Toshiba Corporation" 567.%D August 25, 2003 568.%T "Advanced Configuration and Power Interface Specification" 569.%U http://acpi.info/spec.htm 570.Re 571.Sh AUTHORS 572.An -nosplit 573The ACPI CA subsystem is developed and maintained by 574Intel Architecture Labs. 575.Pp 576The following people made notable contributions to the ACPI subsystem 577in 578.Fx : 579.An Michael Smith , 580.An Takanori Watanabe Aq takawata@jp.FreeBSD.org , 581.An Mitsuru IWASAKI Aq iwasaki@jp.FreeBSD.org , 582.An Munehiro Matsuda , 583.An Nate Lawson , 584the ACPI-jp mailing list at 585.Aq acpi-jp@jp.FreeBSD.org , 586and many other contributors. 587.Pp 588This manual page was written by 589.An Michael Smith Aq msmith@FreeBSD.org . 590.Sh BUGS 591Many BIOS versions have serious bugs that may cause system instability, 592break suspend/resume, or prevent devices from operating properly due to 593IRQ routing problems. 594Upgrade your BIOS to the latest version available from the vendor before 595deciding it is a problem with 596.Nm . 597.Pp 598The 599.Nm 600CPU idle power management drive conflicts with the local APIC (LAPIC) 601timer. 602Disable the local APIC timer with 603.Va hint.apic.0.clock=0 604or do not use the 605.Li C3 606and deeper states if the local APIC timer is enabled. 607