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