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