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 June 30, 2004
  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
  39 The
  40 .Nm
  41 driver provides support for the Intel/Microsoft/Compaq/Toshiba ACPI
  42 standard.
  43 This support includes platform hardware discovery (superseding the
  44 PnP and PCI BIOS), as well as power management (superseding APM) and
  45 other features.
  46 ACPI core support is provided by the ACPI CA reference implementation
  47 from Intel.
  48 .Pp
  49 Note that the
  50 .Nm
  51 driver is automatically loaded by the bootloader, and should not normally
  52 be compiled into the kernel.
  53 .Sh ENVIRONMENT
  54 This support is still experimental, and thus there are many debugging
  55 and tuning options which are managed via the kernel environment.
  56 Tunables can be set at the
  57 .Xr loader 8
  58 prompt before booting the kernel or stored in
  59 .Pa /boot/loader.conf .
  60 .Pp
  61 Debugging is separated between layers and levels, where a layer is
  62 a portion of the ACPI subsystem, and a level is a particular kind
  63 of debugging output.
  64 .Pp
  65 Both layers and levels are specified as a whitespace-separated list of
  66 tokens, with layers listed in
  67 .Va debug.acpi.layer
  68 and levels in
  69 .Va debug.acpi.level .
  70 The supported layers are:
  71 .Pp
  72 .Bl -item -offset indent -compact
  73 .It
  74 .Li ACPI_UTILITIES
  75 .It
  76 .Li ACPI_HARDWARE
  77 .It
  78 .Li ACPI_EVENTS
  79 .It
  80 .Li ACPI_TABLES
  81 .It
  82 .Li ACPI_NAMESPACE
  83 .It
  84 .Li ACPI_PARSER
  85 .It
  86 .Li ACPI_DISPATCHER
  87 .It
  88 .Li ACPI_EXECUTER
  89 .It
  90 .Li ACPI_RESOURCES
  91 .It
  92 .Li ACPI_CA_DEBUGGER
  93 .It
  94 .Li ACPI_OS_SERVICES
  95 .It
  96 .Li ACPI_CA_DISASSEMBLER
  97 .It
  98 .Li ACPI_ALL_COMPONENTS
  99 .It
 100 .Li ACPI_AC_ADAPTER
 101 .It
 102 .Li ACPI_BATTERY
 103 .It
 104 .Li ACPI_BUS
 105 .It
 106 .Li ACPI_BUTTON
 107 .It
 108 .Li ACPI_EC
 109 .It
 110 .Li ACPI_FAN
 111 .It
 112 .Li ACPI_POWER
 113 .It
 114 .Li ACPI_PROCESSOR
 115 .It
 116 .Li ACPI_THERMAL
 117 .It
 118 .Li ACPI_TIMER
 119 .It
 120 .Li ACPI_ALL_DRIVERS
 121 .El
 122 .Pp
 123 The supported levels are:
 124 .Pp
 125 .Bl -item -offset indent -compact
 126 .It
 127 .Li ACPI_LV_ERROR
 128 .It
 129 .Li ACPI_LV_WARN
 130 .It
 131 .Li ACPI_LV_INIT
 132 .It
 133 .Li ACPI_LV_DEBUG_OBJECT
 134 .It
 135 .Li ACPI_LV_INFO
 136 .It
 137 .Li ACPI_LV_ALL_EXCEPTIONS
 138 .It
 139 .Li ACPI_LV_INIT_NAMES
 140 .It
 141 .Li ACPI_LV_PARSE
 142 .It
 143 .Li ACPI_LV_LOAD
 144 .It
 145 .Li ACPI_LV_DISPATCH
 146 .It
 147 .Li ACPI_LV_EXEC
 148 .It
 149 .Li ACPI_LV_NAMES
 150 .It
 151 .Li ACPI_LV_OPREGION
 152 .It
 153 .Li ACPI_LV_BFIELD
 154 .It
 155 .Li ACPI_LV_TABLES
 156 .It
 157 .Li ACPI_LV_VALUES
 158 .It
 159 .Li ACPI_LV_OBJECTS
 160 .It
 161 .Li ACPI_LV_RESOURCES
 162 .It
 163 .Li ACPI_LV_USER_REQUESTS
 164 .It
 165 .Li ACPI_LV_PACKAGE
 166 .It
 167 .Li ACPI_LV_VERBOSITY1
 168 .It
 169 .Li ACPI_LV_ALLOCATIONS
 170 .It
 171 .Li ACPI_LV_FUNCTIONS
 172 .It
 173 .Li ACPI_LV_OPTIMIZATIONS
 174 .It
 175 .Li ACPI_LV_VERBOSITY2
 176 .It
 177 .Li ACPI_LV_ALL
 178 .It
 179 .Li ACPI_LV_MUTEX
 180 .It
 181 .Li ACPI_LV_THREADS
 182 .It
 183 .Li ACPI_LV_IO
 184 .It
 185 .Li ACPI_LV_INTERRUPTS
 186 .It
 187 .Li ACPI_LV_VERBOSITY3
 188 .It
 189 .Li ACPI_LV_AML_DISASSEMBLE
 190 .It
 191 .Li ACPI_LV_VERBOSE_INFO
 192 .It
 193 .Li ACPI_LV_FULL_TABLES
 194 .It
 195 .Li ACPI_LV_EVENTS
 196 .It
 197 .Li ACPI_LV_VERBOSE
 198 .El
 199 .Pp
 200 Selection of the appropriate layer and level values is important
 201 to avoid massive amounts of debugging output.
 202 Check the code to see which you need.
 203 .Pp
 204 Debugging output by the ACPI CA subsystem is prefixed with the
 205 module name in lowercase, followed by a source line number.
 206 Output from the
 207 .Fx Ns -local
 208 code follows the same format, but
 209 the module name is uppercased.
 210 .Pp
 211 For machines known not to work with
 212 .Nm
 213 enabled, there is a BIOS blacklist.
 214 Currently, the blacklist only controls whether
 215 .Nm
 216 should be disabled or not.
 217 In the future, it will have more granularity to control features (the
 218 infrastructure for that is already there).
 219 .Pp
 220 To enable
 221 .Nm
 222 (for debugging purposes, etc.) on machines that are on the blacklist, set the
 223 kernel environment variable
 224 .Va hint.acpi.0.disabled
 225 to 0.
 226 Before trying this, consider updating your BIOS to a more recent version that
 227 may be compatible with ACPI.
 228 .Pp
 229 To disable the
 230 .Nm
 231 driver completely, set the kernel environment variable
 232 .Va hint.acpi.0.disabled
 233 to 1.
 234 .Pp
 235 Some i386 machines totally fail to operate with some or all of ACPI disabled.
 236 Other i386 machines fail with ACPI enabled.
 237 Non-i386 platforms do not support operating systems which do not use ACPI.
 238 Disabling all or part of ACPI on non-i386 platforms may result in a
 239 non-functional system.
 240 .Pp
 241 The
 242 .Nm
 243 driver comprises a set of drivers, which may be selectively disabled
 244 in case of problems.
 245 To disable a sub-driver, list it in the kernel
 246 environment variable
 247 .Va debug.acpi.disabled .
 248 Multiple entries can be listed, separated by a space.
 249 .Pp
 250 ACPI sub-devices and features that can be disabled:
 251 .Bl -tag -width sysresource
 252 .It Li all
 253 Disable all ACPI features and devices.
 254 .It Li acad
 255 .Pq Vt device
 256 Supports AC adapter.
 257 .It Li bus
 258 .Pq Vt feature
 259 Probes and attaches subdevices.
 260 Disabling will avoid scanning the ACPI namespace entirely.
 261 .It Li children
 262 .Pq Vt feature
 263 Attaches standard ACPI sub-drivers and devices enumerated in the
 264 ACPI namespace.
 265 Disabling this has a similar effect to disabling
 266 .Dq Li bus ,
 267 except that the
 268 ACPI namespace will still be scanned.
 269 .It Li button
 270 .Pq Vt device
 271 Supports ACPI button devices (typically power and sleep buttons).
 272 .It Li cmbat
 273 .Pq Vt device
 274 Control-method batteries device.
 275 .It Li cpu
 276 .Pq Vt device
 277 Supports CPU power-saving and speed-setting functions.
 278 .It Li ec
 279 .Pq Vt device
 280 Supports the ACPI Embedded Controller interface, used to communicate
 281 with embedded platform controllers.
 282 .It Li isa
 283 .Pq Vt device
 284 Supports an ISA bus bridge defined in the ACPI namespace,
 285 typically as a child of a PCI bus.
 286 .It Li lid
 287 .Pq Vt device
 288 Supports an ACPI laptop lid switch, which typically puts a
 289 system to sleep.
 290 .It Li quirks
 291 .Pq Vt feature
 292 Do not honor quirks.
 293 Quirks automatically disable ACPI functionality based on the XSDT table's
 294 OEM vendor name and revision date.
 295 .It Li pci
 296 .Pq Vt device
 297 Supports Host to PCI bridges.
 298 .It Li pci_link
 299 .Pq Vt feature
 300 Performs PCI interrupt routing.
 301 .It Li sysresource
 302 .Pq Vt device
 303 Pseudo-devices containing resources which ACPI claims.
 304 .It Li thermal
 305 .Pq Vt device
 306 Supports system cooling and heat management.
 307 .It Li timer
 308 .Pq Vt device
 309 Implements a timecounter using the ACPI fixed-frequency timer.
 310 .El
 311 .Pp
 312 It is also possible to avoid portions of the ACPI namespace which
 313 may be causing problems, by listing the full path of the root of
 314 the region to be avoided in the kernel environment variable
 315 .Va debug.acpi.avoid .
 316 The object and all of its children will be ignored during the
 317 bus/children scan of the namespace.
 318 The ACPI CA code will still
 319 know about the avoided region.
 320 .Sh OVERRIDING YOUR BIOS BYTECODE
 321 ACPI interprets bytecode named AML, ACPI Machine Language, provided by the BIOS
 322 vendor as a memory image at boot time.
 323 Sometimes, the AML code contains
 324 a problem that does not appear in the Microsoft implementation.
 325 So we provide a way to override it with your own AML code.
 326 .Pp
 327 In order to load your AML code,
 328 you must edit
 329 .Pa /boot/loader.conf
 330 and
 331 include the following lines.
 332 .Bd -literal -offset indent
 333 acpi_dsdt_load="YES"
 334 acpi_dsdt_name="/boot/acpi_dsdt.aml" #You may change the name.
 335 .Ed
 336 .Pp
 337 In order to prepare your AML code, you will need the
 338 .Xr acpidump 8
 339 and
 340 .Xr iasl 1
 341 utilities and some ACPI knowledge.
 342 .Sh TUNABLES
 343 .Bl -tag -width indent
 344 .It Va acpi_dsdt_load
 345 Enables loading of a custom ACPI DSDT.
 346 .It Va acpi_dsdt_name
 347 Name of the DSDT table to load, if loading is enabled.
 348 .It Va debug.acpi.disabled
 349 Selectively disables portions of ACPI for debugging purposes.
 350 .It Va hint.acpi.0.disabled
 351 Set this to 1 to disable all of ACPI.
 352 If ACPI has been disabled on your system due to a blacklist entry for your
 353 BIOS, you can set this to 0 to re-enable ACPI for testing.
 354 .It Va hw.acpi.ec.poll_timeout
 355 Delay in milliseconds to wait for the EC to respond.
 356 Try increasing this number if you get the error
 357 .Er AE_NO_HARDWARE_RESPONSE .
 358 .It Va hw.acpi.reset_video
 359 Enables calling the VESA reset BIOS vector on the resume path.
 360 Some graphic chips have problems such as LCD white-out after resume.
 361 Try setting this to 0 if this causes problems for you.
 362 .It Va hw.acpi.osname
 363 Some systems' ASL may have problems because they look for names
 364 of Microsoft operating systems.
 365 This tunable overrides the value of the
 366 .Qq Li \e_OS
 367 object from its default of
 368 .Qq Li FreeBSD .
 369 .It Va hw.acpi.pci.link.%d.%d.%d.irq
 370 Override the interrupt to use.
 371 .It Va hw.acpi.verbose
 372 Turn on verbose debugging information about what ACPI is doing.
 373 .El
 374 .Sh SYSCTLS
 375 .Bl -tag -width indent
 376 .It Va hw.acpi.cpu.throttle_max
 377 Maximum value for CPU throttling, equal to 100% of the clock rate.
 378 .It Va hw.acpi.cpu.throttle_state
 379 Get or set the current throttling state, from 1 to
 380 .Va hw.acpi.cpu.throttle_max .
 381 This scales back the CPU clock rate and the corresponding power consumption.
 382 .It Va hw.acpi.cpu.cx_usage
 383 Debugging information listing the percent of total usage for each sleep state.
 384 The values are reset when
 385 .Va hw.acpi.cpu.cx_lowest
 386 is modified.
 387 .It Va hw.acpi.cpu.cx_lowest
 388 Lowest Cx state to use for idling the CPU.
 389 A scheduling algorithm will select states between C1 and this setting
 390 as system load dictates.
 391 To enable ACPI CPU idling control,
 392 .Va machdep.cpu_idle_hlt
 393 must be set to 1.
 394 .It Va hw.acpi.cpu.cx_supported
 395 List of supported CPU idle states and their transition latency
 396 in microseconds.
 397 Each state has a type (e.g., C2).
 398 C1 is equivalent to the ia32 HLT instruction, C2 provides a deeper
 399 sleep with the same semantics, and C3 provides the deepest sleep
 400 but additionally requires bus mastering to be disabled.
 401 States greater than C3 provide even more power savings with the same
 402 semantics as the C3 state.
 403 Deeper sleeps provide more power savings but increased transition
 404 latency when an interrupt occurs.
 405 .El
 406 .Sh COMPATIBILITY
 407 ACPI is only found and supported on i386/ia32, ia64, and amd64.
 408 .Sh SEE ALSO
 409 .Xr kenv 1 ,
 410 .Xr acpi_thermal 4 ,
 411 .Xr device.hints 5 ,
 412 .Xr loader.conf 5 ,
 413 .Xr acpiconf 8 ,
 414 .Xr acpidump 8 ,
 415 .Xr config 8 ,
 416 .Xr iasl 8
 417 .Rs
 418 .%A "Compaq Computer Corporation"
 419 .%A "Intel Corporation"
 420 .%A "Microsoft Corporation"
 421 .%A "Phoenix Technologies Ltd."
 422 .%A "Toshiba Corporation"
 423 .%D August 25, 2003
 424 .%T "Advanced Configuration and Power Interface Specification"
 425 .%O http://acpi.info/spec.htm
 426 .Re
 427 .Sh AUTHORS
 428 .An -nosplit
 429 The ACPI CA subsystem is developed and maintained by
 430 Intel Architecture Labs.
 431 .Pp
 432 The following people made notable contributions to the ACPI subsystem
 433 in
 434 .Fx :
 435 .An Michael Smith ,
 436 .An Takanori Watanabe Aq takawata@jp.FreeBSD.org ,
 437 .An Mitsuru IWASAKI Aq iwasaki@jp.FreeBSD.org ,
 438 .An Munehiro Matsuda ,
 439 .An Nate Lawson ,
 440 the ACPI-jp mailing list at
 441 .Aq acpi-jp@jp.FreeBSD.org ,
 442 and many other contributors.
 443 .Pp
 444 This manual page was written by
 445 .An Michael Smith Aq msmith@FreeBSD.org .
 446 .Sh BUGS
 447 If the
 448 .Nm
 449 driver is loaded as a module when it is already linked as part of the
 450 kernel, odd things may happen.