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