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