457 lines
14 KiB
Groff
457 lines
14 KiB
Groff
.\"
|
|
.\" Copyright (c) 2001 Michael Smith
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd February 13, 2005
|
|
.Dt ACPI 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm acpi
|
|
.Nd Advanced Configuration and Power Management support
|
|
.Sh SYNOPSIS
|
|
.Cd "device acpi"
|
|
.Pp
|
|
.Cd "options ACPI_DEBUG"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
driver provides support for the Intel/Microsoft/Compaq/Toshiba ACPI
|
|
standard.
|
|
This support includes platform hardware discovery (superseding the
|
|
PnP and PCI BIOS), as well as power management (superseding APM) and
|
|
other features.
|
|
ACPI core support is provided by the ACPI CA reference implementation
|
|
from Intel.
|
|
.Pp
|
|
Note that the
|
|
.Nm
|
|
driver is automatically loaded by the
|
|
.Xr loader 8 ,
|
|
and should only be
|
|
compiled into the kernel on platforms where ACPI is mandatory.
|
|
.Sh SYSCTLS
|
|
The
|
|
.Nm
|
|
driver is intended to provide power management without user intervention.
|
|
Thus, some of these sysctls are controlled automatically by the
|
|
.Pa power_profile
|
|
.Xr rc 8
|
|
script, which can be configured via
|
|
.Xr rc.conf 5 .
|
|
If values are specified manually, they may be overridden.
|
|
.Bl -tag -width indent
|
|
.It Va hw.acpi.cpu.cx_usage
|
|
Debugging information listing the percent of total usage for each sleep state.
|
|
The values are reset when
|
|
.Va hw.acpi.cpu.cx_lowest
|
|
is modified.
|
|
.It Va hw.acpi.cpu.cx_lowest
|
|
Lowest Cx state to use for idling the CPU.
|
|
A scheduling algorithm will select states between C1 and this setting
|
|
as system load dictates.
|
|
To enable ACPI CPU idling control,
|
|
.Va machdep.cpu_idle_hlt
|
|
must be set to 1.
|
|
.It Va hw.acpi.cpu.cx_supported
|
|
List of supported CPU idle states and their transition latency
|
|
in microseconds.
|
|
Each state has a type (e.g., C2).
|
|
C1 is equivalent to the ia32 HLT instruction, C2 provides a deeper
|
|
sleep with the same semantics, and C3 provides the deepest sleep
|
|
but additionally requires bus mastering to be disabled.
|
|
States greater than C3 provide even more power savings with the same
|
|
semantics as the C3 state.
|
|
Deeper sleeps provide more power savings but increased transition
|
|
latency when an interrupt occurs.
|
|
.El
|
|
.Sh TUNABLES
|
|
Tunables can be set at the
|
|
.Xr loader 8
|
|
prompt before booting the kernel or stored in
|
|
.Pa /boot/loader.conf .
|
|
.Bl -tag -width indent
|
|
.It Va acpi_dsdt_load
|
|
Enables loading of a custom ACPI DSDT.
|
|
.It Va acpi_dsdt_name
|
|
Name of the DSDT table to load, if loading is enabled.
|
|
.It Va debug.acpi.disabled
|
|
Selectively disables portions of ACPI for debugging purposes.
|
|
.It Va debug.acpi.quirks
|
|
Override any automatic quirks completely.
|
|
.It Va hint.acpi.0.disabled
|
|
Set this to 1 to disable all of ACPI.
|
|
If ACPI has been disabled on your system due to a blacklist entry for your
|
|
BIOS, you can set this to 0 to re-enable ACPI for testing.
|
|
.It Va hw.acpi.ec.poll_timeout
|
|
Delay in milliseconds to wait for the EC to respond.
|
|
Try increasing this number if you get the error
|
|
.Qq Li AE_NO_HARDWARE_RESPONSE .
|
|
.It Va hw.acpi.host_mem_start
|
|
Override the assumed memory starting address for PCI host bridges.
|
|
.It Va hw.acpi.pci.link.%d.%d.%d.irq
|
|
Override the interrupt to use.
|
|
.It Va hw.acpi.reset_video
|
|
Enables calling the VESA reset BIOS vector on the resume path.
|
|
Some graphic chips have problems such as LCD white-out after resume.
|
|
Try setting this to 0 if this causes problems for you.
|
|
.It Va hw.acpi.serialize_methods
|
|
Allow override of whether methods execute in parallel or not.
|
|
Enable this for serial behavior, which fixes
|
|
.Qq Li AE_ALREADY_EXISTS
|
|
errors for
|
|
AML that really cannot handle parallel method execution.
|
|
It is off by default since this breaks recursive methods and some IBMs use
|
|
such code.
|
|
.It Va hw.acpi.verbose
|
|
Turn on verbose debugging information about what ACPI is doing.
|
|
.El
|
|
.Sh DISABLING ACPI
|
|
Since ACPI support on different platforms varies greatly, there are many
|
|
debugging and tuning options available.
|
|
.Pp
|
|
For machines known not to work with
|
|
.Nm
|
|
enabled, there is a BIOS blacklist.
|
|
Currently, the blacklist only controls whether
|
|
.Nm
|
|
should be disabled or not.
|
|
In the future, it will have more granularity to control features (the
|
|
infrastructure for that is already there).
|
|
.Pp
|
|
To enable
|
|
.Nm
|
|
(for debugging purposes, etc.) on machines that are on the blacklist, set the
|
|
kernel environment variable
|
|
.Va hint.acpi.0.disabled
|
|
to 0.
|
|
Before trying this, consider updating your BIOS to a more recent version that
|
|
may be compatible with ACPI.
|
|
.Pp
|
|
To disable the
|
|
.Nm
|
|
driver completely, set the kernel environment variable
|
|
.Va hint.acpi.0.disabled
|
|
to 1.
|
|
.Pp
|
|
Some i386 machines totally fail to operate with some or all of ACPI disabled.
|
|
Other i386 machines fail with ACPI enabled.
|
|
Disabling all or part of ACPI on non-i386 platforms (i.e., platforms where
|
|
ACPI support is mandatory) may result in a non-functional system.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
driver comprises a set of drivers, which may be selectively disabled
|
|
in case of problems.
|
|
To disable a sub-driver, list it in the kernel
|
|
environment variable
|
|
.Va debug.acpi.disabled .
|
|
Multiple entries can be listed, separated by a space.
|
|
.Pp
|
|
ACPI sub-devices and features that can be disabled:
|
|
.Bl -tag -width ".Li sysresource"
|
|
.It Li all
|
|
Disable all ACPI features and devices.
|
|
.It Li acad
|
|
.Pq Vt device
|
|
Supports AC adapter.
|
|
.It Li bus
|
|
.Pq Vt feature
|
|
Probes and attaches subdevices.
|
|
Disabling will avoid scanning the ACPI namespace entirely.
|
|
.It Li children
|
|
.Pq Vt feature
|
|
Attaches standard ACPI sub-drivers and devices enumerated in the
|
|
ACPI namespace.
|
|
Disabling this has a similar effect to disabling
|
|
.Dq Li bus ,
|
|
except that the
|
|
ACPI namespace will still be scanned.
|
|
.It Li button
|
|
.Pq Vt device
|
|
Supports ACPI button devices (typically power and sleep buttons).
|
|
.It Li cmbat
|
|
.Pq Vt device
|
|
Control-method batteries device.
|
|
.It Li cpu
|
|
.Pq Vt device
|
|
Supports CPU power-saving and speed-setting functions.
|
|
.It Li ec
|
|
.Pq Vt device
|
|
Supports the ACPI Embedded Controller interface, used to communicate
|
|
with embedded platform controllers.
|
|
.It Li isa
|
|
.Pq Vt device
|
|
Supports an ISA bus bridge defined in the ACPI namespace,
|
|
typically as a child of a PCI bus.
|
|
.It Li lid
|
|
.Pq Vt device
|
|
Supports an ACPI laptop lid switch, which typically puts a
|
|
system to sleep.
|
|
.It Li quirks
|
|
.Pq Vt feature
|
|
Do not honor quirks.
|
|
Quirks automatically disable ACPI functionality based on the XSDT table's
|
|
OEM vendor name and revision date.
|
|
.It Li pci
|
|
.Pq Vt device
|
|
Supports Host to PCI bridges.
|
|
.It Li pci_link
|
|
.Pq Vt feature
|
|
Performs PCI interrupt routing.
|
|
.It Li sysresource
|
|
.Pq Vt device
|
|
Pseudo-devices containing resources which ACPI claims.
|
|
.It Li thermal
|
|
.Pq Vt device
|
|
Supports system cooling and heat management.
|
|
.It Li timer
|
|
.Pq Vt device
|
|
Implements a timecounter using the ACPI fixed-frequency timer.
|
|
.El
|
|
.Pp
|
|
It is also possible to avoid portions of the ACPI namespace which
|
|
may be causing problems, by listing the full path of the root of
|
|
the region to be avoided in the kernel environment variable
|
|
.Va debug.acpi.avoid .
|
|
The object and all of its children will be ignored during the
|
|
bus/children scan of the namespace.
|
|
The ACPI CA code will still know about the avoided region.
|
|
.Sh DEBUGGING OUTPUT
|
|
To enable debugging output,
|
|
.Nm
|
|
must be compiled with
|
|
.Cd "options ACPI_DEBUG" .
|
|
Debugging output is separated between layers and levels, where a layer is
|
|
a component of the ACPI subsystem, and a level is a particular kind
|
|
of debugging output.
|
|
.Pp
|
|
Both layers and levels are specified as a whitespace-separated list of
|
|
tokens, with layers listed in
|
|
.Va debug.acpi.layer
|
|
and levels in
|
|
.Va debug.acpi.level .
|
|
.Pp
|
|
The first set of layers is for ACPI-CA components, and the second is for
|
|
.Fx
|
|
drivers.
|
|
The ACPI-CA layer descriptions include the prefix for the files they
|
|
refer to.
|
|
The supported layers are:
|
|
.Pp
|
|
.Bl -tag -compact -width ".Li ACPI_CA_DISASSEMBLER"
|
|
.It Li ACPI_UTILITIES
|
|
Utility ("ut") functions
|
|
.It Li ACPI_HARDWARE
|
|
Hardware access ("hw")
|
|
.It Li ACPI_EVENTS
|
|
Event and GPE ("ev")
|
|
.It Li ACPI_TABLES
|
|
Table access ("tb")
|
|
.It Li ACPI_NAMESPACE
|
|
Namespace evaluation ("ns")
|
|
.It Li ACPI_PARSER
|
|
AML parser ("ps")
|
|
.It Li ACPI_DISPATCHER
|
|
Internal representation of interpreter state ("ds")
|
|
.It Li ACPI_EXECUTER
|
|
Execute AML methods ("ex")
|
|
.It Li ACPI_RESOURCES
|
|
Resource parsing ("rs")
|
|
.It Li ACPI_CA_DEBUGGER
|
|
Debugger implementation ("db", "dm")
|
|
.It Li ACPI_OS_SERVICES
|
|
Usermode support routines ("os")
|
|
.It Li ACPI_CA_DISASSEMBLER
|
|
Disassembler implementation (unused)
|
|
.It Li ACPI_ALL_COMPONENTS
|
|
All the above ACPI-CA components
|
|
.It Li ACPI_AC_ADAPTER
|
|
AC adapter driver
|
|
.It Li ACPI_BATTERY
|
|
Control-method battery driver
|
|
.It Li ACPI_BUS
|
|
ACPI, ISA, and PCI bus drivers
|
|
.It Li ACPI_BUTTON
|
|
Power and sleep button driver
|
|
.It Li ACPI_EC
|
|
Embedded controller driver
|
|
.It Li ACPI_FAN
|
|
Fan driver
|
|
.It Li ACPI_OEM
|
|
Platform-specific driver for hotkeys, LED, etc.
|
|
.It Li ACPI_POWER
|
|
Power resource driver
|
|
.It Li ACPI_PROCESSOR
|
|
CPU driver
|
|
.It Li ACPI_THERMAL
|
|
Thermal zone driver
|
|
.It Li ACPI_TIMER
|
|
Timer driver
|
|
.It Li ACPI_ALL_DRIVERS
|
|
All the above
|
|
.Fx
|
|
ACPI drivers
|
|
.El
|
|
.Pp
|
|
The supported levels are:
|
|
.Pp
|
|
.Bl -tag -compact -width ".Li ACPI_LV_AML_DISASSEMBLE"
|
|
.It Li ACPI_LV_ERROR
|
|
Fatal error conditions
|
|
.It Li ACPI_LV_WARN
|
|
Warnings and potential problems
|
|
.It Li ACPI_LV_INIT
|
|
Initialization progress
|
|
.It Li ACPI_LV_DEBUG_OBJECT
|
|
Stores to objects
|
|
.It Li ACPI_LV_INFO
|
|
General information and progress
|
|
.It Li ACPI_LV_ALL_EXCEPTIONS
|
|
All the previous levels
|
|
.It Li ACPI_LV_INIT_NAMES
|
|
.It Li ACPI_LV_PARSE
|
|
.It Li ACPI_LV_LOAD
|
|
.It Li ACPI_LV_DISPATCH
|
|
.It Li ACPI_LV_EXEC
|
|
.It Li ACPI_LV_NAMES
|
|
.It Li ACPI_LV_OPREGION
|
|
.It Li ACPI_LV_BFIELD
|
|
.It Li ACPI_LV_TABLES
|
|
.It Li ACPI_LV_VALUES
|
|
.It Li ACPI_LV_OBJECTS
|
|
.It Li ACPI_LV_RESOURCES
|
|
.It Li ACPI_LV_USER_REQUESTS
|
|
.It Li ACPI_LV_PACKAGE
|
|
.It Li ACPI_LV_VERBOSITY1
|
|
All the previous levels
|
|
.It Li ACPI_LV_ALLOCATIONS
|
|
.It Li ACPI_LV_FUNCTIONS
|
|
.It Li ACPI_LV_OPTIMIZATIONS
|
|
.It Li ACPI_LV_VERBOSITY2
|
|
.It Li ACPI_LV_ALL
|
|
.It Li ACPI_LV_MUTEX
|
|
.It Li ACPI_LV_THREADS
|
|
.It Li ACPI_LV_IO
|
|
.It Li ACPI_LV_INTERRUPTS
|
|
.It Li ACPI_LV_VERBOSITY3
|
|
All the previous levels
|
|
.It Li ACPI_LV_AML_DISASSEMBLE
|
|
.It Li ACPI_LV_VERBOSE_INFO
|
|
.It Li ACPI_LV_FULL_TABLES
|
|
.It Li ACPI_LV_EVENTS
|
|
.It Li ACPI_LV_VERBOSE
|
|
All levels after
|
|
.Qq Li ACPI_LV_VERBOSITY3
|
|
.El
|
|
.Pp
|
|
Selection of the appropriate layer and level values is important
|
|
to avoid massive amounts of debugging output.
|
|
For example, the following configuration is a good way to gather initial
|
|
information.
|
|
It enables debug output for both ACPI-CA and the
|
|
.Nm
|
|
driver, printing basic information about errors, warnings, and progress.
|
|
.Bd -literal -offset indent
|
|
debug.acpi.layer="ACPI_ALL_COMPONENTS ACPI_ALL_DRIVERS"
|
|
debug.acpi.level="ACPI_LV_ALL_EXCEPTIONS"
|
|
.Ed
|
|
.Pp
|
|
Debugging output by the ACPI CA subsystem is prefixed with the
|
|
module name in lowercase, followed by a source line number.
|
|
Output from the
|
|
.Fx Ns -local
|
|
code follows the same format, but
|
|
the module name is uppercased.
|
|
.Sh OVERRIDING YOUR BIOS BYTECODE
|
|
ACPI interprets bytecode named AML
|
|
(ACPI Machine Language)
|
|
provided by the BIOS vendor as a memory image at boot time.
|
|
Sometimes, the AML code contains a bug that does not appear when parsed
|
|
by the Microsoft implementation.
|
|
.Fx
|
|
provides a way to override it with your own AML code to work around
|
|
or debug such problems.
|
|
Note that all AML in your DSDT and any SSDT tables is overridden.
|
|
.Pp
|
|
In order to load your AML code, you must edit
|
|
.Pa /boot/loader.conf
|
|
and include the following lines.
|
|
.Bd -literal -offset indent
|
|
acpi_dsdt_load="YES"
|
|
acpi_dsdt_name="/boot/acpi_dsdt.aml" # You may change this name.
|
|
.Ed
|
|
.Pp
|
|
In order to prepare your AML code, you will need the
|
|
.Xr acpidump 8
|
|
and
|
|
.Xr iasl 8
|
|
utilities and some ACPI knowledge.
|
|
.Sh COMPATIBILITY
|
|
ACPI is only found and supported on i386/ia32, ia64, and amd64.
|
|
.Sh SEE ALSO
|
|
.Xr kenv 1 ,
|
|
.Xr acpi_thermal 4 ,
|
|
.Xr device.hints 5 ,
|
|
.Xr loader.conf 5 ,
|
|
.Xr acpiconf 8 ,
|
|
.Xr acpidump 8 ,
|
|
.Xr config 8 ,
|
|
.Xr iasl 8
|
|
.Rs
|
|
.%A "Compaq Computer Corporation"
|
|
.%A "Intel Corporation"
|
|
.%A "Microsoft Corporation"
|
|
.%A "Phoenix Technologies Ltd."
|
|
.%A "Toshiba Corporation"
|
|
.%D August 25, 2003
|
|
.%T "Advanced Configuration and Power Interface Specification"
|
|
.%O http://acpi.info/spec.htm
|
|
.Re
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
The ACPI CA subsystem is developed and maintained by
|
|
Intel Architecture Labs.
|
|
.Pp
|
|
The following people made notable contributions to the ACPI subsystem
|
|
in
|
|
.Fx :
|
|
.An Michael Smith ,
|
|
.An Takanori Watanabe Aq takawata@jp.FreeBSD.org ,
|
|
.An Mitsuru IWASAKI Aq iwasaki@jp.FreeBSD.org ,
|
|
.An Munehiro Matsuda ,
|
|
.An Nate Lawson ,
|
|
the ACPI-jp mailing list at
|
|
.Aq acpi-jp@jp.FreeBSD.org ,
|
|
and many other contributors.
|
|
.Pp
|
|
This manual page was written by
|
|
.An Michael Smith Aq msmith@FreeBSD.org .
|
|
.Sh BUGS
|
|
If the
|
|
.Nm
|
|
driver is loaded as a module when it is already linked as part of the
|
|
kernel, odd things may happen.
|