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 May 1, 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. 60Thus, some of these sysctls are controlled automatically by the 61.Pa power_profile 62.Xr rc 8 63script, which can be configured via 64.Xr rc.conf 5 . 65If values are specified manually, they may be overridden. 66.Bl -tag -width indent 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 C1 and this setting 75as system load dictates. 76To enable ACPI CPU idling control, 77.Va machdep.cpu_idle_hlt 78must be set to 1. 79.It Va hw.acpi.cpu.cx_supported 80List of supported CPU idle states and their transition latency 81in microseconds. 82Each state has a type (e.g., C2). 83C1 is equivalent to the ia32 HLT instruction, C2 provides a deeper 84sleep with the same semantics, and C3 provides the deepest sleep 85but additionally requires bus mastering to be disabled. 86States greater than C3 provide even more power savings with the same 87semantics as the C3 state. 88Deeper sleeps provide more power savings but increased transition 89latency when an interrupt occurs. 90.El 91.Sh LOADER TUNABLES 92Tunables can be set at the 93.Xr loader 8 94prompt before booting the kernel or stored in 95.Pa /boot/loader.conf . 96Many of these tunables also have a matching 97.Xr sysctl 8 98entry for access after boot. 99.Bl -tag -width indent 100.It Va acpi_dsdt_load 101Enables loading of a custom ACPI DSDT. 102.It Va acpi_dsdt_name 103Name of the DSDT table to load, if loading is enabled. 104.It Va debug.acpi.disabled 105Selectively disables portions of ACPI for debugging purposes. 106.It Va debug.acpi.max_threads 107Specify the number of task threads that are started on boot. 108Limiting this to 1 may help work around various BIOSes that cannot 109handle parallel requests. 110The default value is 3. 111.It Va debug.acpi.quirks 112Override any automatic quirks completely. 113.It Va debug.acpi.resume_beep 114Beep the PC speaker on resume. 115This can help diagnose suspend/resume problems. 116Default is 0 (disabled). 117.It Va hint.acpi.0.disabled 118Set this to 1 to disable all of ACPI. 119If ACPI has been disabled on your system due to a blacklist entry for your 120BIOS, you can set this to 0 to re-enable ACPI for testing. 121.It Va hw.acpi.ec.poll_timeout 122Delay in milliseconds to wait for the EC to respond. 123Try increasing this number if you get the error 124.Qq Li AE_NO_HARDWARE_RESPONSE . 125.It Va hw.acpi.host_mem_start 126Override the assumed memory starting address for PCI host bridges. 127.It Va hw.acpi.reset_video 128Enables calling the VESA reset BIOS vector on the resume path. 129This can fix some graphics cards that have problems such as LCD white-out 130after resume. 131Default is 0 (disabled). 132.It Va hw.acpi.serialize_methods 133Allow override of whether methods execute in parallel or not. 134Enable this for serial behavior, which fixes 135.Qq Li AE_ALREADY_EXISTS 136errors for 137AML that really cannot handle parallel method execution. 138It is off by default since this breaks recursive methods and some IBMs use 139such code. 140.It Va hw.acpi.verbose 141Turn on verbose debugging information about what ACPI is doing. 142.It Va hw.pci.link.%s.%d.irq 143Override the interrupt to use. 144.It Va hw.pci.link.%s.irq 145Override the interrupt to use. 146.El 147.Sh DISABLING ACPI 148Since ACPI support on different platforms varies greatly, there are many 149debugging and tuning options available. 150.Pp 151For machines known not to work with 152.Nm 153enabled, there is a BIOS blacklist. 154Currently, the blacklist only controls whether 155.Nm 156should be disabled or not. 157In the future, it will have more granularity to control features (the 158infrastructure for that is already there). 159.Pp 160To enable 161.Nm 162(for debugging purposes, etc.) on machines that are on the blacklist, set the 163kernel environment variable 164.Va hint.acpi.0.disabled 165to 0. 166Before trying this, consider updating your BIOS to a more recent version that 167may be compatible with ACPI. 168.Pp 169To disable the 170.Nm 171driver completely, set the kernel environment variable 172.Va hint.acpi.0.disabled 173to 1. 174.Pp 175Some i386 machines totally fail to operate with some or all of ACPI disabled. 176Other i386 machines fail with ACPI enabled. 177Disabling all or part of ACPI on non-i386 platforms (i.e., platforms where 178ACPI support is mandatory) may result in a non-functional system. 179.Pp 180The 181.Nm 182driver comprises a set of drivers, which may be selectively disabled 183in case of problems. 184To disable a sub-driver, list it in the kernel 185environment variable 186.Va debug.acpi.disabled . 187Multiple entries can be listed, separated by a space. 188.Pp 189ACPI sub-devices and features that can be disabled: 190.Bl -tag -width ".Li sysresource" 191.It Li all 192Disable all ACPI features and devices. 193.It Li acad 194.Pq Vt device 195Supports AC adapter. 196.It Li bus 197.Pq Vt feature 198Probes and attaches subdevices. 199Disabling will avoid scanning the ACPI namespace entirely. 200.It Li children 201.Pq Vt feature 202Attaches standard ACPI sub-drivers and devices enumerated in the 203ACPI namespace. 204Disabling this has a similar effect to disabling 205.Dq Li bus , 206except that the 207ACPI namespace will still be scanned. 208.It Li button 209.Pq Vt device 210Supports ACPI button devices (typically power and sleep buttons). 211.It Li cmbat 212.Pq Vt device 213Control-method batteries device. 214.It Li cpu 215.Pq Vt device 216Supports CPU power-saving and speed-setting functions. 217.It Li ec 218.Pq Vt device 219Supports the ACPI Embedded Controller interface, used to communicate 220with embedded platform controllers. 221.It Li isa 222.Pq Vt device 223Supports an ISA bus bridge defined in the ACPI namespace, 224typically as a child of a PCI bus. 225.It Li lid 226.Pq Vt device 227Supports an ACPI laptop lid switch, which typically puts a 228system to sleep. 229.It Li quirks 230.Pq Vt feature 231Do not honor quirks. 232Quirks automatically disable ACPI functionality based on the XSDT table's 233OEM vendor name and revision date. 234.It Li pci 235.Pq Vt device 236Supports Host to PCI bridges. 237.It Li pci_link 238.Pq Vt feature 239Performs PCI interrupt routing. 240.It Li sysresource 241.Pq Vt device 242Pseudo-devices containing resources which ACPI claims. 243.It Li thermal 244.Pq Vt device 245Supports system cooling and heat management. 246.It Li timer 247.Pq Vt device 248Implements a timecounter using the ACPI fixed-frequency timer. 249.It Li video 250.Pq Vt device 251Supports 252.Xr acpi_video 4 253which may conflict with 254.Xr agp 4 255device. 256.El 257.Pp 258It is also possible to avoid portions of the ACPI namespace which 259may be causing problems, by listing the full path of the root of 260the region to be avoided in the kernel environment variable 261.Va debug.acpi.avoid . 262The object and all of its children will be ignored during the 263bus/children scan of the namespace. 264The ACPI CA code will still know about the avoided region. 265.Sh DEBUGGING OUTPUT 266To enable debugging output, 267.Nm 268must be compiled with 269.Cd "options ACPI_DEBUG" . 270Debugging output is separated between layers and levels, where a layer is 271a component of the ACPI subsystem, and a level is a particular kind 272of debugging output. 273.Pp 274Both layers and levels are specified as a whitespace-separated list of 275tokens, with layers listed in 276.Va debug.acpi.layer 277and levels in 278.Va debug.acpi.level . 279.Pp 280The first set of layers is for ACPI-CA components, and the second is for 281.Fx 282drivers. 283The ACPI-CA layer descriptions include the prefix for the files they 284refer to. 285The supported layers are: 286.Pp 287.Bl -tag -compact -width ".Li ACPI_CA_DISASSEMBLER" 288.It Li ACPI_UTILITIES 289Utility ("ut") functions 290.It Li ACPI_HARDWARE 291Hardware access ("hw") 292.It Li ACPI_EVENTS 293Event and GPE ("ev") 294.It Li ACPI_TABLES 295Table access ("tb") 296.It Li ACPI_NAMESPACE 297Namespace evaluation ("ns") 298.It Li ACPI_PARSER 299AML parser ("ps") 300.It Li ACPI_DISPATCHER 301Internal representation of interpreter state ("ds") 302.It Li ACPI_EXECUTER 303Execute AML methods ("ex") 304.It Li ACPI_RESOURCES 305Resource parsing ("rs") 306.It Li ACPI_CA_DEBUGGER 307Debugger implementation ("db", "dm") 308.It Li ACPI_OS_SERVICES 309Usermode support routines ("os") 310.It Li ACPI_CA_DISASSEMBLER 311Disassembler implementation (unused) 312.It Li ACPI_ALL_COMPONENTS 313All the above ACPI-CA components 314.It Li ACPI_AC_ADAPTER 315AC adapter driver 316.It Li ACPI_BATTERY 317Control-method battery driver 318.It Li ACPI_BUS 319ACPI, ISA, and PCI bus drivers 320.It Li ACPI_BUTTON 321Power and sleep button driver 322.It Li ACPI_EC 323Embedded controller driver 324.It Li ACPI_FAN 325Fan driver 326.It Li ACPI_OEM 327Platform-specific driver for hotkeys, LED, etc. 328.It Li ACPI_POWER 329Power resource driver 330.It Li ACPI_PROCESSOR 331CPU driver 332.It Li ACPI_THERMAL 333Thermal zone driver 334.It Li ACPI_TIMER 335Timer driver 336.It Li ACPI_ALL_DRIVERS 337All the above 338.Fx 339ACPI drivers 340.El 341.Pp 342The supported levels are: 343.Pp 344.Bl -tag -compact -width ".Li ACPI_LV_AML_DISASSEMBLE" 345.It Li ACPI_LV_ERROR 346Fatal error conditions 347.It Li ACPI_LV_WARN 348Warnings and potential problems 349.It Li ACPI_LV_INIT 350Initialization progress 351.It Li ACPI_LV_DEBUG_OBJECT 352Stores to objects 353.It Li ACPI_LV_INFO 354General information and progress 355.It Li ACPI_LV_ALL_EXCEPTIONS 356All the previous levels 357.It Li ACPI_LV_INIT_NAMES 358.It Li ACPI_LV_PARSE 359.It Li ACPI_LV_LOAD 360.It Li ACPI_LV_DISPATCH 361.It Li ACPI_LV_EXEC 362.It Li ACPI_LV_NAMES 363.It Li ACPI_LV_OPREGION 364.It Li ACPI_LV_BFIELD 365.It Li ACPI_LV_TABLES 366.It Li ACPI_LV_VALUES 367.It Li ACPI_LV_OBJECTS 368.It Li ACPI_LV_RESOURCES 369.It Li ACPI_LV_USER_REQUESTS 370.It Li ACPI_LV_PACKAGE 371.It Li ACPI_LV_VERBOSITY1 372All the previous levels 373.It Li ACPI_LV_ALLOCATIONS 374.It Li ACPI_LV_FUNCTIONS 375.It Li ACPI_LV_OPTIMIZATIONS 376.It Li ACPI_LV_VERBOSITY2 377.It Li ACPI_LV_ALL 378.It Li ACPI_LV_MUTEX 379.It Li ACPI_LV_THREADS 380.It Li ACPI_LV_IO 381.It Li ACPI_LV_INTERRUPTS 382.It Li ACPI_LV_VERBOSITY3 383All the previous levels 384.It Li ACPI_LV_AML_DISASSEMBLE 385.It Li ACPI_LV_VERBOSE_INFO 386.It Li ACPI_LV_FULL_TABLES 387.It Li ACPI_LV_EVENTS 388.It Li ACPI_LV_VERBOSE 389All levels after 390.Qq Li ACPI_LV_VERBOSITY3 391.El 392.Pp 393Selection of the appropriate layer and level values is important 394to avoid massive amounts of debugging output. 395For example, the following configuration is a good way to gather initial 396information. 397It enables debug output for both ACPI-CA and the 398.Nm 399driver, printing basic information about errors, warnings, and progress. 400.Bd -literal -offset indent 401debug.acpi.layer="ACPI_ALL_COMPONENTS ACPI_ALL_DRIVERS" 402debug.acpi.level="ACPI_LV_ALL_EXCEPTIONS" 403.Ed 404.Pp 405Debugging output by the ACPI CA subsystem is prefixed with the 406module name in lowercase, followed by a source line number. 407Output from the 408.Fx Ns -local 409code follows the same format, but 410the module name is uppercased. 411.Sh OVERRIDING YOUR BIOS BYTECODE 412ACPI interprets bytecode named AML 413(ACPI Machine Language) 414provided by the BIOS vendor as a memory image at boot time. 415Sometimes, the AML code contains a bug that does not appear when parsed 416by the Microsoft implementation. 417.Fx 418provides a way to override it with your own AML code to work around 419or debug such problems. 420Note that all AML in your DSDT and any SSDT tables is overridden. 421.Pp 422In order to load your AML code, you must edit 423.Pa /boot/loader.conf 424and include the following lines. 425.Bd -literal -offset indent 426acpi_dsdt_load="YES" 427acpi_dsdt_name="/boot/acpi_dsdt.aml" # You may change this name. 428.Ed 429.Pp 430In order to prepare your AML code, you will need the 431.Xr acpidump 8 432and 433.Xr iasl 8 434utilities and some ACPI knowledge. 435.Sh COMPATIBILITY 436ACPI is only found and supported on i386/ia32, ia64, and amd64. 437.Sh SEE ALSO 438.Xr kenv 1 , 439.Xr acpi_thermal 4 , 440.Xr device.hints 5 , 441.Xr loader.conf 5 , 442.Xr acpiconf 8 , 443.Xr acpidump 8 , 444.Xr config 8 , 445.Xr iasl 8 446.Rs 447.%A "Compaq Computer Corporation" 448.%A "Intel Corporation" 449.%A "Microsoft Corporation" 450.%A "Phoenix Technologies Ltd." 451.%A "Toshiba Corporation" 452.%D August 25, 2003 453.%T "Advanced Configuration and Power Interface Specification" 454.%O http://acpi.info/spec.htm 455.Re 456.Sh AUTHORS 457.An -nosplit 458The ACPI CA subsystem is developed and maintained by 459Intel Architecture Labs. 460.Pp 461The following people made notable contributions to the ACPI subsystem 462in 463.Fx : 464.An Michael Smith , 465.An Takanori Watanabe Aq takawata@jp.FreeBSD.org , 466.An Mitsuru IWASAKI Aq iwasaki@jp.FreeBSD.org , 467.An Munehiro Matsuda , 468.An Nate Lawson , 469the ACPI-jp mailing list at 470.Aq acpi-jp@jp.FreeBSD.org , 471and many other contributors. 472.Pp 473This manual page was written by 474.An Michael Smith Aq msmith@FreeBSD.org . 475.Sh BUGS 476If the 477.Nm 478driver is loaded as a module when it is already linked as part of the 479kernel, odd things may happen. 480