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