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 November 21, 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.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.allow_method_calls 205If set, the 206.Xr acpicall 8 207utility can be used to directly call ACPI methods for debugging and 208tweaking purposes. 209.It Va debug.acpi.disabled 210Selectively disables portions of ACPI that are enabled by default, for 211debugging purposes. 212.It Va debug.acpi.enabled 213Selectively enables portions of ACPI that are disabled by default, for 214debugging purposes. 215.It Va debug.acpi.facs_addr32 216Favor 32-bit FACS table addresses over the 64-bit addresses. 217.It Va debug.acpi.fadt_addr32 218Favor 32-bit FADT register addresses over the 64-bit addresses. 219.It Va debug.acpi.ignore_xsdt 220Ignore the XSDT, forcing the use of the RSDT. 221.It Va debug.acpi.interpreter_slack 222Enable less strict ACPI implementations. 223Default is 1, ignore common BIOS mistakes. 224.It Va debug.acpi.max_threads 225Specify the number of task threads that are started on boot. 226Limiting this to 1 may help work around various BIOSes that cannot 227handle parallel requests. 228The default value is 3. 229.It Va debug.acpi.quirks 230Override any automatic quirks completely. 231.It Va debug.acpi.resume_beep 232Beep the PC speaker on resume. 233This can help diagnose suspend/resume problems. 234Default is 0 (disabled). 235.It Va hint.acpi.0.disabled 236Set this to 1 to disable all of ACPI. 237If ACPI has been disabled on your system due to a blacklist entry for your 238BIOS, you can set this to 0 to re-enable ACPI for testing. 239.It Va hw.acpi.ec.poll_timeout 240Delay in milliseconds to wait for the EC to respond. 241Try increasing this number if you get the error 242.Qq Li AE_NO_HARDWARE_RESPONSE . 243.It Va hw.acpi.host_mem_start 244Override the assumed memory starting address for PCI host bridges. 245.It Va hw.acpi.install_interface , hw.acpi.remove_interface 246Install or remove OS interface(s) to control the return value of the 247.Ql _OSI 248query method. 249When an OS interface is specified in 250.Va hw.acpi.install_interface , 251the 252.Li _OSI 253query for the interface returns it is 254.Em supported . 255Conversely, when an OS interface is specified in 256.Va hw.acpi.remove_interface , 257the 258.Li _OSI 259query returns it is 260.Em not supported . 261Multiple interfaces can be specified in a comma-separated list and 262any leading white spaces will be ignored. 263For example, 264.Qq Li FreeBSD, Linux 265is a valid list of two interfaces 266.Qq Li FreeBSD 267and 268.Qq Li Linux . 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