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