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