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