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