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