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