xref: /freebsd/share/man/man4/acpi.4 (revision 7773002178c8dbc52b44e4d705f07706409af8e4) 
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 July 2, 2001
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 bootloader, and should not normally
52be compiled into the kernel.
53.Sh ENVIRONMENT
54This support is still experimental, and thus there are many debugging
55and tuning options which are managed via the kernel environment
56space, and set in the
57.Xr loader 8
58before booting the kernel.
59.Pp
60Debugging is separated between layers and levels, where a layer is
61a portion of the ACPI subsystem, and a level is a particular kind
62of debugging output.
63.Pp
64Both layers and levels are specified as a whitespace-separated list of
65tokens, with layers listed in
66.Va debug.acpi.layer
67and levels in
68.Va debug.acpi.level .
69The supported layers are:
70.Pp
71.Bl -item -offset indent -compact
72.It
73.Li ACPI_UTILITIES
74.It
75.Li ACPI_HARDWARE
76.It
77.Li ACPI_EVENTS
78.It
79.Li ACPI_TABLES
80.It
81.Li ACPI_NAMESPACE
82.It
83.Li ACPI_PARSER
84.It
85.Li ACPI_DISPATCHER
86.It
87.Li ACPI_EXECUTER
88.It
89.Li ACPI_RESOURCES
90.It
91.Li ACPI_CA_DEBUGGER
92.It
93.Li ACPI_OS_SERVICES
94.It
95.Li ACPI_CA_DISASSEMBLER
96.It
97.Li ACPI_ALL_COMPONENTS
98.It
99.Li ACPI_BUS
100.It
101.Li ACPI_SYSTEM
102.It
103.Li ACPI_POWER
104.It
105.Li ACPI_EC
106.It
107.Li ACPI_AC_ADAPTER
108.It
109.Li ACPI_BATTERY
110.It
111.Li ACPI_BUTTON
112.It
113.Li ACPI_PROCESSOR
114.It
115.Li ACPI_THERMAL
116.It
117.Li ACPI_FAN
118.It
119.Li ACPI_ALL_DRIVERS
120.El
121.Pp
122The supported levels are:
123.Pp
124.Bl -item -offset indent -compact
125.It
126.Li ACPI_LV_ERROR
127.It
128.Li ACPI_LV_WARN
129.It
130.Li ACPI_LV_INIT
131.It
132.Li ACPI_LV_DEBUG_OBJECT
133.It
134.Li ACPI_LV_INFO
135.It
136.Li ACPI_LV_ALL_EXCEPTIONS
137.It
138.Li ACPI_LV_INIT_NAMES
139.It
140.Li ACPI_LV_PARSE
141.It
142.Li ACPI_LV_LOAD
143.It
144.Li ACPI_LV_DISPATCH
145.It
146.Li ACPI_LV_EXEC
147.It
148.Li ACPI_LV_NAMES
149.It
150.Li ACPI_LV_OPREGION
151.It
152.Li ACPI_LV_BFIELD
153.It
154.Li ACPI_LV_TABLES
155.It
156.Li ACPI_LV_VALUES
157.It
158.Li ACPI_LV_OBJECTS
159.It
160.Li ACPI_LV_RESOURCES
161.It
162.Li ACPI_LV_USER_REQUESTS
163.It
164.Li ACPI_LV_PACKAGE
165.It
166.Li ACPI_LV_VERBOSITY1
167.It
168.Li ACPI_LV_ALLOCATIONS
169.It
170.Li ACPI_LV_FUNCTIONS
171.It
172.Li ACPI_LV_OPTIMIZATIONS
173.It
174.Li ACPI_LV_VERBOSITY2
175.It
176.Li ACPI_LV_ALL
177.It
178.Li ACPI_LV_MUTEX
179.It
180.Li ACPI_LV_THREADS
181.It
182.Li ACPI_LV_IO
183.It
184.Li ACPI_LV_INTERRUPTS
185.It
186.Li ACPI_LV_VERBOSITY3
187.It
188.Li ACPI_LV_AML_DISASSEMBLE
189.It
190.Li ACPI_LV_VERBOSE_INFO
191.It
192.Li ACPI_LV_FULL_TABLES
193.It
194.Li ACPI_LV_EVENTS
195.It
196.Li ACPI_LV_VERBOSE
197.El
198.Pp
199Selection of the appropriate layer and level values is important
200to avoid massive amounts of debugging output.
201Check the code to see which you need.
202.Pp
203Debugging output by the ACPI CA subsystem is prefixed with the
204module name in lowercase, followed by a source line number.
205Output from the
206.Fx Ns -local
207code follows the same format, but
208the module name is uppercased.
209.Pp
210To disable the
211.Nm
212driver completely, set the kernel environment variable
213.Va hint.acpi.0.disabled
214to 1.
215Some i386 machines totally fail to operate with some or all of ACPI disabled.
216Other i386 machines fail with ACPI enabled.
217Non-i386 platforms do not support operating systems which do not use ACPI.
218Disabling all or part of ACPI on non-i386 platforms may result in a
219non-functional system.
220.Pp
221The
222.Nm
223driver comprises a set of drivers, which may be selectively disabled
224in case of problems.
225To disable a sub-driver, list it in the kernel
226environment variable
227.Va debug.acpi.disable .
228.Pp
229ACPI sub-devices and features that can be disabled:
230.Bl -tag -width children
231.It Li bus
232.Pq Vt feature
233Probes and attaches subdevices.
234Disabling will avoid scanning the ACPI namespace entirely.
235.It Li children
236.Pq Vt feature
237Attaches standard ACPI sub-drivers and devices enumerated in the
238ACPI namespace.
239Disabling this has a similar effect to disabling
240.Dq Li bus ,
241except that the
242ACPI namespace will still be scanned.
243.It Li button
244.Pq Vt device
245Supports ACPI button devices (typically power and sleep buttons).
246.It Li ec
247.Pq Vt device
248Supports the ACPI Embedded Controller interface, used to
249communicate with embedded platform controllers.
250.It Li isa
251.Pq Vt device
252Supports an ISA bus bridge defined in the ACPI namespace,
253typically as a child of a PCI bus.
254.It Li lid
255.Pq Vt device
256Supports an ACPI laptop lid switch, which typically puts a
257system to sleep.
258.It Li pci
259.Pq Vt device
260Supports Host to PCI bridges.
261.It Li cpu
262.Pq Vt device
263Supports CPU power-saving and speed-setting functions.
264.It Li thermal
265.Pq Vt device
266Supports system cooling and heat management.
267.It Li timer
268.Pq Vt device
269Implements a timecounter using the ACPI fixed-frequency timer.
270.El
271.Pp
272It is also possible to avoid portions of the ACPI namespace which
273may be causing problems, by listing the full path of the root of
274the region to be avoided in the kernel environment variable
275.Va debug.acpi.avoid .
276The object and all of its children will be ignored during the
277bus/children scan of the namespace.
278The ACPI CA code will still
279know about the avoided region.
280.Sh OVERRIDING YOUR BIOS BYTECODE
281ACPI interprets bytecode named AML, ACPI Machine Language, provided by the BIOS
282vendor as a memory image at boot time.
283Sometimes, the AML code contains
284a problem that does not appear in the Microsoft implementation.
285So we provide a way to override it with your own AML code.
286.Pp
287In order to load your AML code,
288you must edit
289.Pa /boot/loader.conf
290and
291include the following lines.
292.Bd -literal -offset indent
293acpi_dsdt_load="YES"
294acpi_dsdt_name="/boot/acpi_dsdt.aml" #You may change the name.
295.Ed
296.Pp
297In order to prepare your AML code, you will need the
298.Xr acpidump 8
299and
300.Xr iasl 1
301utilities and some ACPI knowledge.
302.Sh TUNABLES
303.Bl -tag -width indent
304.It Va acpi_dsdt_load
305Enables loading of a custom ACPI DSDT.
306.It Va acpi_dsdt_name
307Name of the DSDT table to load, if loading is enabled.
308.It Va debug.acpi.disable
309Selectively disables portions of ACPI for debugging purposes.
310.It Va hint.acpi.0.disabled
311Disables all of ACPI.
312.It Va hw.acpi.cpu.performance_speed
313Sets the speed of the CPU, if it supports multiple speeds, while in
314the performance power profile.
315.It Va hw.acpi.cpu.economy_speed
316Sets the speed of the CPU, if it supports multiple speeds, while in
317the economy power profile.
318.It Va hw.acpi.ec.poll_timeout
319Delay in milliseconds to wait for the EC to respond.  Try increasing this
320number if you get the error
321.Er AE_NO_HARDWARE_RESPONSE .
322.It Va hw.acpi.no_reset_video
323Disables calling the VESA reset BIOS vector on the resume path.  Some
324graphic chips have problems such as LCD white-out after resume.  Try
325setting this to 1 if necessary.
326.It Va hw.acpi.os_name
327Some systems' ASL may have problems because they look for names
328of Microsoft operating systems.  This tunable overrides the
329default value of "FreeBSD".
330.It Va hw.acpi.pci.link.%d.%d.%d.irq
331Override the interrupt to use.
332.It Va hw.acpi.verbose
333Turn on verbose debugging information about what ACPI is doing.
334.El
335.Sh COMPATIBILITY
336ACPI is only found/supported on i386/ia32, ia64 and amd64.
337.Sh SEE ALSO
338.Xr loader.conf 5 ,
339.Xr acpiconf 8 ,
340.Xr acpidump 8 ,
341.Xr config 8 ,
342.Xr iasl 8
343.Rs
344.%A "Compaq Computer Corporation"
345.%A "Intel Corporation"
346.%A "Microsoft Corporation"
347.%A "Phoenix Technologies Ltd."
348.%A "Toshiba Corporation"
349.%D July 27 2000
350.%T "Advanced Configuration and Power Interface Specification"
351.%O http://acpi.info/spec.htm
352.Re
353.Sh AUTHORS
354.An -nosplit
355The ACPI CA subsystem is developed and maintained by
356Intel Architecture Labs.
357.Pp
358The following people made notable contributions to the ACPI subsystem
359in
360.Fx :
361.An Michael Smith ,
362.An Takanori Watanabe Aq takawata@jp.FreeBSD.org ,
363.An Mitsuru IWASAKI Aq iwasaki@jp.FreeBSD.org ,
364.An Munehiro Matsuda ,
365.An Nate Lawson ,
366the ACPI-jp mailing list at
367.Aq acpi-jp@jp.FreeBSD.org ,
368and many other contributors.
369.Pp
370This manual page was written by
371.An Michael Smith Aq msmith@FreeBSD.org .
372.Sh BUGS
373If the
374.Nm
375driver is loaded as a module when it is already linked as part of the
376kernel, odd things may happen.
377