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