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 October 26, 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. 115Some newer systems require use of this register, while some only work 116with legacy rebooting support. 117.It Va hw.acpi.lid_switch_state 118Suspend state 119.Pq Li S1 Ns \[en] Ns Li S5 120to enter when the lid switch (i.e., a notebook screen) is closed. 121Default is 122.Dq Li NONE 123(do nothing). 124.It Va hw.acpi.power_button_state 125Suspend state 126.Pq Li S1 Ns \[en] Ns Li S5 127to enter when the power button is pressed. 128Default is 129.Li S5 130(power-off nicely). 131.It Va hw.acpi.reset_video 132Reset the video adapter from real mode during the resume path. 133Some systems need this help, others have display problems if it is enabled. 134Default is 0 (disabled). 135.It Va hw.acpi.s4bios 136Indicate whether the system supports 137.Li S4BIOS . 138This means that the BIOS can handle all the functions of suspending the 139system to disk. 140Otherwise, the OS is responsible for suspending to disk 141.Pq Li S4OS . 142Most current systems do not support 143.Li S4BIOS . 144.It Va hw.acpi.sleep_button_state 145Suspend state 146.Pq Li S1 Ns \[en] Ns Li S5 147to enter when the sleep button is pressed. 148This is usually a special function button on the keyboard. 149Default is 150.Li S3 151(suspend-to-RAM). 152.It Va hw.acpi.sleep_delay 153Wait this number of seconds between preparing the system to suspend and 154actually entering the suspend state. 155Default is 1 second. 156.It Va hw.acpi.supported_sleep_state 157Suspend states 158.Pq Li S1 Ns \[en] Ns Li S5 159supported by the BIOS. 160.Bl -tag -width indent 161.It Li S1 162Quick suspend to RAM. 163The CPU enters a lower power state, but most peripherals are left running. 164.It Li S2 165Lower power state than 166.Li S1 , 167but with the same basic characteristics. 168Not supported by many systems. 169.It Li S3 170Suspend to RAM. 171Most devices are powered off, and the system stops running except for 172memory refresh. 173.It Li S4 174Suspend to disk. 175All devices are powered off, and the system stops running. 176When resuming, the system starts as if from a cold power on. 177Not yet supported by 178.Fx 179unless 180.Li S4BIOS 181is available. 182.It Li S5 183System shuts down cleanly and powers off. 184.El 185.It Va hw.acpi.verbose 186Enable verbose printing from the various ACPI subsystems. 187.El 188.Sh LOADER TUNABLES 189Tunables can be set at the 190.Xr loader 8 191prompt before booting the kernel or stored in 192.Pa /boot/loader.conf . 193Many of these tunables also have a matching 194.Xr sysctl 8 195entry for access after boot. 196.Bl -tag -width indent 197.It Va acpi_dsdt_load 198Enables loading of a custom ACPI DSDT. 199.It Va acpi_dsdt_name 200Name of the DSDT table to load, if loading is enabled. 201.It Va debug.acpi.disabled 202Selectively disables portions of ACPI for debugging purposes. 203.It Va debug.acpi.interpreter_slack 204Enable less strict ACPI implementations. 205Default is 1, ignore common BIOS mistakes. 206.It Va debug.acpi.max_threads 207Specify the number of task threads that are started on boot. 208Limiting this to 1 may help work around various BIOSes that cannot 209handle parallel requests. 210The default value is 3. 211.It Va debug.acpi.quirks 212Override any automatic quirks completely. 213.It Va debug.acpi.resume_beep 214Beep the PC speaker on resume. 215This can help diagnose suspend/resume problems. 216Default is 0 (disabled). 217.It Va hint.acpi.0.disabled 218Set this to 1 to disable all of ACPI. 219If ACPI has been disabled on your system due to a blacklist entry for your 220BIOS, you can set this to 0 to re-enable ACPI for testing. 221.It Va hw.acpi.ec.poll_timeout 222Delay in milliseconds to wait for the EC to respond. 223Try increasing this number if you get the error 224.Qq Li AE_NO_HARDWARE_RESPONSE . 225.It Va hw.acpi.host_mem_start 226Override the assumed memory starting address for PCI host bridges. 227.It Va hw.acpi.install_interface , hw.acpi.remove_interface 228Install or remove OS interface(s) to control return value of 229.Ql _OSI 230query method. When an OS interface is specified in 231.Va hw.acpi.install_interface , 232.Li _OSI 233query for the interface returns it is 234.Em supported . 235Conversely, when an OS interface is specified in 236.Va hw.acpi.remove_interface , 237.Li _OSI 238query returns it is 239.Em not supported . 240Multiple interfaces can be specified in a comma-separated list and 241any leading white spaces will be ignored. For example, 242.Qq Li FreeBSD, Linux 243is a valid list of two interfaces 244.Qq Li FreeBSD 245and 246.Qq Li Linux . 247.It Va hw.acpi.reset_video 248Enables calling the VESA reset BIOS vector on the resume path. 249This can fix some graphics cards that have problems such as LCD white-out 250after resume. 251Default is 0 (disabled). 252.It Va hw.acpi.serialize_methods 253Allow override of whether methods execute in parallel or not. 254Enable this for serial behavior, which fixes 255.Qq Li AE_ALREADY_EXISTS 256errors for 257AML that really cannot handle parallel method execution. 258It is off by default since this breaks recursive methods and some IBMs use 259such code. 260.It Va hw.acpi.verbose 261Turn on verbose debugging information about what ACPI is doing. 262.It Va hw.pci.link.%s.%d.irq 263Override the interrupt to use for this link and index. 264This capability should be used carefully, and only if a device is not 265working with 266.Nm 267enabled. 268.Qq %s 269is the name of the link (e.g., LNKA). 270.Qq %d 271is the resource index when the link supports multiple IRQs. 272Most PCI links only have one IRQ resource, so the below form should be used. 273.It Va hw.pci.link.%s.irq 274Override the interrupt to use. 275This capability should be used carefully, and only if a device is not 276working with 277.Nm 278enabled. 279.Qq %s 280is the name of the link (e.g., LNKA). 281.El 282.Sh DISABLING ACPI 283Since ACPI support on different platforms varies greatly, there are many 284debugging and tuning options available. 285.Pp 286For machines known not to work with 287.Nm 288enabled, there is a BIOS blacklist. 289Currently, the blacklist only controls whether 290.Nm 291should be disabled or not. 292In the future, it will have more granularity to control features (the 293infrastructure for that is already there). 294.Pp 295To enable 296.Nm 297(for debugging purposes, etc.) on machines that are on the blacklist, set the 298kernel environment variable 299.Va hint.acpi.0.disabled 300to 0. 301Before trying this, consider updating your BIOS to a more recent version that 302may be compatible with ACPI. 303.Pp 304To disable the 305.Nm 306driver completely, set the kernel environment variable 307.Va hint.acpi.0.disabled 308to 1. 309.Pp 310Some i386 machines totally fail to operate with some or all of ACPI disabled. 311Other i386 machines fail with ACPI enabled. 312Disabling all or part of ACPI on non-i386 platforms (i.e., platforms where 313ACPI support is mandatory) may result in a non-functional system. 314.Pp 315The 316.Nm 317driver comprises a set of drivers, which may be selectively disabled 318in case of problems. 319To disable a sub-driver, list it in the kernel 320environment variable 321.Va debug.acpi.disabled . 322Multiple entries can be listed, separated by a space. 323.Pp 324ACPI sub-devices and features that can be disabled: 325.Bl -tag -width ".Li sysresource" 326.It Li all 327Disable all ACPI features and devices. 328.It Li acad 329.Pq Vt device 330Supports AC adapter. 331.It Li bus 332.Pq Vt feature 333Probes and attaches subdevices. 334Disabling will avoid scanning the ACPI namespace entirely. 335.It Li children 336.Pq Vt feature 337Attaches standard ACPI sub-drivers and devices enumerated in the 338ACPI namespace. 339Disabling this has a similar effect to disabling 340.Dq Li bus , 341except that the 342ACPI namespace will still be scanned. 343.It Li button 344.Pq Vt device 345Supports ACPI button devices (typically power and sleep buttons). 346.It Li cmbat 347.Pq Vt device 348Control-method batteries device. 349.It Li cpu 350.Pq Vt device 351Supports CPU power-saving and speed-setting functions. 352.It Li ec 353.Pq Vt device 354Supports the ACPI Embedded Controller interface, used to communicate 355with embedded platform controllers. 356.It Li isa 357.Pq Vt device 358Supports an ISA bus bridge defined in the ACPI namespace, 359typically as a child of a PCI bus. 360.It Li lid 361.Pq Vt device 362Supports an ACPI laptop lid switch, which typically puts a 363system to sleep. 364.It Li quirks 365.Pq Vt feature 366Do not honor quirks. 367Quirks automatically disable ACPI functionality based on the XSDT table's 368OEM vendor name and revision date. 369.It Li pci 370.Pq Vt device 371Supports Host to PCI bridges. 372.It Li pci_link 373.Pq Vt feature 374Performs PCI interrupt routing. 375.It Li sysresource 376.Pq Vt device 377Pseudo-devices containing resources which ACPI claims. 378.It Li thermal 379.Pq Vt device 380Supports system cooling and heat management. 381.It Li timer 382.Pq Vt device 383Implements a timecounter using the ACPI fixed-frequency timer. 384.It Li video 385.Pq Vt device 386Supports 387.Xr acpi_video 4 388which may conflict with 389.Xr agp 4 390device. 391.El 392.Pp 393It is also possible to avoid portions of the ACPI namespace which 394may be causing problems, by listing the full path of the root of 395the region to be avoided in the kernel environment variable 396.Va debug.acpi.avoid . 397The object and all of its children will be ignored during the 398bus/children scan of the namespace. 399The ACPI CA code will still know about the avoided region. 400.Sh DEBUGGING OUTPUT 401To enable debugging output, 402.Nm 403must be compiled with 404.Cd "options ACPI_DEBUG" . 405Debugging output is separated between layers and levels, where a layer is 406a component of the ACPI subsystem, and a level is a particular kind 407of debugging output. 408.Pp 409Both layers and levels are specified as a whitespace-separated list of 410tokens, with layers listed in 411.Va debug.acpi.layer 412and levels in 413.Va debug.acpi.level . 414.Pp 415The first set of layers is for ACPI-CA components, and the second is for 416.Fx 417drivers. 418The ACPI-CA layer descriptions include the prefix for the files they 419refer to. 420The supported layers are: 421.Pp 422.Bl -tag -compact -width ".Li ACPI_CA_DISASSEMBLER" 423.It Li ACPI_UTILITIES 424Utility ("ut") functions 425.It Li ACPI_HARDWARE 426Hardware access ("hw") 427.It Li ACPI_EVENTS 428Event and GPE ("ev") 429.It Li ACPI_TABLES 430Table access ("tb") 431.It Li ACPI_NAMESPACE 432Namespace evaluation ("ns") 433.It Li ACPI_PARSER 434AML parser ("ps") 435.It Li ACPI_DISPATCHER 436Internal representation of interpreter state ("ds") 437.It Li ACPI_EXECUTER 438Execute AML methods ("ex") 439.It Li ACPI_RESOURCES 440Resource parsing ("rs") 441.It Li ACPI_CA_DEBUGGER 442Debugger implementation ("db", "dm") 443.It Li ACPI_OS_SERVICES 444Usermode support routines ("os") 445.It Li ACPI_CA_DISASSEMBLER 446Disassembler implementation (unused) 447.It Li ACPI_ALL_COMPONENTS 448All the above ACPI-CA components 449.It Li ACPI_AC_ADAPTER 450AC adapter driver 451.It Li ACPI_BATTERY 452Control-method battery driver 453.It Li ACPI_BUS 454ACPI, ISA, and PCI bus drivers 455.It Li ACPI_BUTTON 456Power and sleep button driver 457.It Li ACPI_EC 458Embedded controller driver 459.It Li ACPI_FAN 460Fan driver 461.It Li ACPI_OEM 462Platform-specific driver for hotkeys, LED, etc. 463.It Li ACPI_POWER 464Power resource driver 465.It Li ACPI_PROCESSOR 466CPU driver 467.It Li ACPI_THERMAL 468Thermal zone driver 469.It Li ACPI_TIMER 470Timer driver 471.It Li ACPI_ALL_DRIVERS 472All the above 473.Fx 474ACPI drivers 475.El 476.Pp 477The supported levels are: 478.Pp 479.Bl -tag -compact -width ".Li ACPI_LV_AML_DISASSEMBLE" 480.It Li ACPI_LV_INIT 481Initialization progress 482.It Li ACPI_LV_DEBUG_OBJECT 483Stores to objects 484.It Li ACPI_LV_INFO 485General information and progress 486.It Li ACPI_LV_ALL_EXCEPTIONS 487All the previous levels 488.It Li ACPI_LV_PARSE 489.It Li ACPI_LV_DISPATCH 490.It Li ACPI_LV_EXEC 491.It Li ACPI_LV_NAMES 492.It Li ACPI_LV_OPREGION 493.It Li ACPI_LV_BFIELD 494.It Li ACPI_LV_TABLES 495.It Li ACPI_LV_VALUES 496.It Li ACPI_LV_OBJECTS 497.It Li ACPI_LV_RESOURCES 498.It Li ACPI_LV_USER_REQUESTS 499.It Li ACPI_LV_PACKAGE 500.It Li ACPI_LV_VERBOSITY1 501All the previous levels 502.It Li ACPI_LV_ALLOCATIONS 503.It Li ACPI_LV_FUNCTIONS 504.It Li ACPI_LV_OPTIMIZATIONS 505.It Li ACPI_LV_VERBOSITY2 506All the previous levels 507.It Li ACPI_LV_ALL 508Synonym for 509.Qq Li ACPI_LV_VERBOSITY2 510.It Li ACPI_LV_MUTEX 511.It Li ACPI_LV_THREADS 512.It Li ACPI_LV_IO 513.It Li ACPI_LV_INTERRUPTS 514.It Li ACPI_LV_VERBOSITY3 515All the previous levels 516.It Li ACPI_LV_AML_DISASSEMBLE 517.It Li ACPI_LV_VERBOSE_INFO 518.It Li ACPI_LV_FULL_TABLES 519.It Li ACPI_LV_EVENTS 520.It Li ACPI_LV_VERBOSE 521All levels after 522.Qq Li ACPI_LV_VERBOSITY3 523.It Li ACPI_LV_INIT_NAMES 524.It Li ACPI_LV_LOAD 525.El 526.Pp 527Selection of the appropriate layer and level values is important 528to avoid massive amounts of debugging output. 529For example, the following configuration is a good way to gather initial 530information. 531It enables debug output for both ACPI-CA and the 532.Nm 533driver, printing basic information about errors, warnings, and progress. 534.Bd -literal -offset indent 535debug.acpi.layer="ACPI_ALL_COMPONENTS ACPI_ALL_DRIVERS" 536debug.acpi.level="ACPI_LV_ALL_EXCEPTIONS" 537.Ed 538.Pp 539Debugging output by the ACPI CA subsystem is prefixed with the 540module name in lowercase, followed by a source line number. 541Output from the 542.Fx Ns -local 543code follows the same format, but 544the module name is uppercased. 545.Sh OVERRIDING YOUR BIOS BYTECODE 546ACPI interprets bytecode named AML 547(ACPI Machine Language) 548provided by the BIOS vendor as a memory image at boot time. 549Sometimes, the AML code contains a bug that does not appear when parsed 550by the Microsoft implementation. 551.Fx 552provides a way to override it with your own AML code to work around 553or debug such problems. 554Note that all AML in your DSDT and any SSDT tables is overridden. 555.Pp 556In order to load your AML code, you must edit 557.Pa /boot/loader.conf 558and include the following lines. 559.Bd -literal -offset indent 560acpi_dsdt_load="YES" 561acpi_dsdt_name="/boot/acpi_dsdt.aml" # You may change this name. 562.Ed 563.Pp 564In order to prepare your AML code, you will need the 565.Xr acpidump 8 566and 567.Xr iasl 8 568utilities and some ACPI knowledge. 569.Sh COMPATIBILITY 570ACPI is only found and supported on i386/ia32, ia64, and amd64. 571.Sh SEE ALSO 572.Xr kenv 1 , 573.Xr acpi_thermal 4 , 574.Xr device.hints 5 , 575.Xr loader.conf 5 , 576.Xr acpiconf 8 , 577.Xr acpidump 8 , 578.Xr config 8 , 579.Xr iasl 8 580.Rs 581.%A "Compaq Computer Corporation" 582.%A "Intel Corporation" 583.%A "Microsoft Corporation" 584.%A "Phoenix Technologies Ltd." 585.%A "Toshiba Corporation" 586.%D August 25, 2003 587.%T "Advanced Configuration and Power Interface Specification" 588.%U http://acpi.info/spec.htm 589.Re 590.Sh AUTHORS 591.An -nosplit 592The ACPI CA subsystem is developed and maintained by 593Intel Architecture Labs. 594.Pp 595The following people made notable contributions to the ACPI subsystem 596in 597.Fx : 598.An Michael Smith , 599.An Takanori Watanabe Aq takawata@jp.FreeBSD.org , 600.An Mitsuru IWASAKI Aq iwasaki@jp.FreeBSD.org , 601.An Munehiro Matsuda , 602.An Nate Lawson , 603the ACPI-jp mailing list at 604.Aq acpi-jp@jp.FreeBSD.org , 605and many other contributors. 606.Pp 607This manual page was written by 608.An Michael Smith Aq msmith@FreeBSD.org . 609.Sh BUGS 610Many BIOS versions have serious bugs that may cause system instability, 611break suspend/resume, or prevent devices from operating properly due to 612IRQ routing problems. 613Upgrade your BIOS to the latest version available from the vendor before 614deciding it is a problem with 615.Nm . 616.Pp 617The 618.Nm 619CPU idle power management drive conflicts with the local APIC (LAPIC) 620timer. 621Disable the local APIC timer with 622.Va hint.apic.0.clock=0 623or do not use the 624.Li C3 625and deeper states if the local APIC timer is enabled. 626