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