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