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