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