 @@ -1,588 +1,557 @@
-.\" $NetBSD: acpi.4,v 1.54 2010/08/06 16:44:06 jruoho Exp $
+.\" $NetBSD: acpi.4,v 1.55 2010/08/06 18:54:50 jruoho Exp $
 .\"
 .\" Copyright (c) 2002, 2004, 2010 The NetBSD Foundation, Inc.
 .\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
 .\"
-.Dd June 30, 2010
+.Dd August 6, 2010
 .Dt ACPI 4
 .Os
 .Sh NAME
 .Nm acpi
 .Nd Advanced Configuration and Power Interface
 .Sh SYNOPSIS
 .Cd "acpi0	at mainbus0"
 .Pp
 .Cd "options	ACPI_DEBUG"
 .Cd "options	ACPIVERBOSE"
 .Cd "options	ACPI_ACTIVATE_DEV"
 .Cd "options	ACPI_DSDT_OVERRIDE"
 .Cd "options	ACPI_DSDT_FILE=\*[q]\*[q]"
 .Sh DESCRIPTION
 .Nx
 provides machine-independent bus support for
 Advanced Configuration and Power Interface
 .Pq Tn ACPI
 devices and includes several
 .Tn ACPI
 device drivers.
 .Pp
 The
 .Nx
 implementation of
 .Tn ACPI
 integrates Intel's ACPI Component Architecture
 .Pq Tn ACPI-CA
 for the OS-independent part.
 The
 .Tn ACPI-CA
 provides OS-neutral
 .Tn ACPI
 functionalities such as
 .Tn ACPI
 .Tn BIOS
 table support,
 an
 .Tn ACPI
 event framework and an ACPI Machine Language
 .Pq Tn AML
 interpreter.
 .Pp
 Options:
 .Bl -tag -width ACPI_DSDT_FILE__filename_XX -offset 3n
 .It Dv ACPI_DEBUG
 Enable various debug facilities.
 .It Dv ACPIVERBOSE
 Enable verbose debug messages.
 .It Dv ACPI_ACTIVATE_DEV
 Determine if the
 .Tn ACPI
 driver should attempt to activate inactive devices.
 The default is off.
 .It Dv ACPI_DSDT_OVERRIDE
 Force a given Differentiated System Description Table
 .Pq Tn DSDT
 instead of the version supplied by the
 .Tn BIOS .
 Use
 .Dv ACPI_DSDT_FILE
 to specify a
 .Tn DSDT .
 .It Dv ACPI_DSDT_FILE="filename"
 If
 .Dv ACPI_DSDT_FILE
 is not specified, default to
 .Dq dsdt.hex
 in the build directory.
 .El
 .Sh SYSCTL SUPPORT
 Few
 .Xr sysctl 8
 variables are directly relevant for
 .Tn ACPI .
 .Bl -tag -width "123456" -offset indent
 .It Ic hw.acpi.root
 The
 .Tn ACPI
 root pointer.
 .It Ic hw.acpi.supported_states
 A list of the
 .Tn ACPI
 sleep states that the machine supports.
 The possible values are:
 .Pp
 .Bl -tag -width XS1X -offset indent -compact
 .It S0
 fully running
 .It S1
 power on suspend (CPU and hard disks are off)
 .It S2
 similar to S3, usually not implemented
 .It S3
 suspend-to-RAM
 .It S4
 suspend-to-disk (not supported on
 .Nx )
 .It S5
 power off
 .El
 .It Ic hw.acpi.stat.gpe
 The number of dispatched General Purpose Events
 .Pq Tn GPEs .
 .It Ic hw.acpi.stat.sci
 The number of System Control Interrupts
 .Pq Tn SCIs .
 See
 .Xr acpiec 4
 for a brief description of both
 .Tn GPEs
 and
 .Tn SCIs .
 .It Ic hw.acpi.stat.fixed
 The number of
 .Dq fixed events .
 .It Ic hw.acpi.stat.method
 The number of
 .Tn ACPI
 methods executed by the interpreter.
 .It Ic machdep.acpi_beep_on_reset
 A boolean variable that controls whether the
 .Tn PC
 speaker beeps upon resume.
 .It Ic machdep.acpi_vbios_reset
 Defines the handling of the graphics card.
 The supported values are:
 .Bl -tag -width '2' -offset indent
 .It 0
 No attempt to reset the
 .Tn VGA
 controller will be made.
 .It 1
 Call the
 .Tn VGA
 .Tn BIOS
 when still in real mode.
 This can result in direct reboots.
 In that case, use
 .Sq 2
 or
 .Ic vbetool post
 from the
 .Pa pkgsrc/sysutils/vbetool
 package.
 .It 2
 Call the
 .Tn VGA
 .Tn BIOS
 using the in-kernel x86 emulator.
 .El
 .El
 .Sh SUPPORTED DEVICES
 .Nx
 .Tn ACPI
 supports several machine-dependent and machine-independent devices:
 .Ss Machine-independent devices
 .Bl -tag -width "thinkpad(4) " -offset indent -compact
 .It Xr acpiacad 4
 .Tn ACPI
 AC adapters.
 .It Xr acpibat 4
 .Tn ACPI
 batteries.
 .It Xr acpibut 4
 .Tn ACPI
 power and sleep buttons.
 .It Xr acpicpu 4
 .Tn ACPI
 processors.
 .It Xr acpidalb 4
 .Tn ACPI
 direction application launch buttons.
 .It Xr acpiec 4
 .Tn ACPI
 embedded controllers.
 .It Xr acpiecdt 4
 .Tn ACPI
 Embedded Controller Boot Resource Table
 .Pq Tn ECDT .
 .It Xr acpilid 4
 .Tn ACPI
 lid switches.
 .It Xr acpismbus 4
 .Tn ACPI
 SMBus via Control Method Interface
 .Pq Tn CMI .
 .It Xr acpitz 4
 .Tn ACPI
 thermal zones.
 .It Xr acpiwmi 4
 .Tn ACPI
 support for Windows Management Instrumentation.
 .It Xr aibs 4
 ASUSTeK voltage, temperature and fan sensors.
 .It asus
 ASUS laptop hotkeys.
 .It Xr attimer 4
 AT Timer.
 .It Xr com 4
 NS8250-, NS16450-, and NS16550-based serial ports.
 .It Xr fdc 4
 Floppy disk controllers.
 .It Xr hpet 4
 High Precision Event Timer
 .Pq Tn HPET .
 .It Xr hpqlb 4
 HP Quick Launch Buttons.
 .It Xr joy 4
 Joystick/Game port interface.
 .It Xr lpt 4
 Standard ISA parallel port interface.
 .It Xr mpu 4
 Roland MPU-401 (compatible) MIDI UART.
 .It Xr pcppi 4
 AT-style speaker sound.
 .It Xr thinkpad 4
 IBM/Lenovo ThinkPad laptop device driver.
 .It Xr ug 4
 Abit uGuru Hardware monitor.
 .It Xr vald 4
 Toshiba Libretto device.
 .It Xr wb 4
 Winbond W83L518D Integrated Media Reader.
 .It Xr wss 4
 Windows Sound System-compatible sound cards
 .It Xr ym 4
 Yamaha OPL3-SA2 and OPL3-SA3 audio device driver.
 .El
 .Ss i386-dependent devices
 .Bl -tag -width "thinkpad(4) " -offset indent -compact
 .It Xr npx 4
 i386 numeric processing extension coprocessor.
 .It Xr pckbc 4
 PC keyboard controllers.
 .It Xr sony 4
 Sony Miscellaneous Controller
 .It Xr spic 4
 Sony programmable I/O controller.
 .El
 .Sh DEBUGGING
 Although the situation has become better over the years,
 .Tn ACPI
 is typically prone to various errors,
 ranging from blatant flaws in the firmware to bugs in the implementation.
 Before anything else, it is a good practice to upgrade the
 .Tn BIOS
 to the latest version available from the vendor.
 .Pp
 To ease the task of diagnosing and fixing different problems, the
 .Tn ACPICA
 reference implementation provides a rich
 facility of different debugging methods.
 In
 .Nx
 these are generally only available if the kernel has been compiled with the
 .Tn ACPI_DEBUG
 option.
 .Ss Custom DSDT
 .Tn ACPI
 interprets bytecode known as
 .Tn ACPI
 Machine Language
 .Pq Tn AML ,
 provided by the
 .Tn BIOS
 as a memory image during the system bootstrap.
 Most of the
 .Tn AML
 relevant to
 .Nm
 is implemented in the so-called
 Differentiated System Descriptor Table
 .Pq Tn DSDT .
 .Nx
 provides support for overriding the default
 .Tn DSDT
 supplied by the
 .Tn BIOS .
 .Pp
 The following steps can be used to override the
 .Tn DSDT :
 .Bl -enum -offset indent
 .It
 Dump the raw
 .Tn DSDT
 with
 .Xr acpidump 8 .
 .It
 Disassemble the table with
 .Xr iasl 8 .
 .It
 Modify the disassembled table.
 .It
 Compile the table with
 .Xr iasl 8
 using the option
 .Ar \-tc .
 .It
 Either copy the
 .Pq Pa *.hex
 file to
 .Bd -literal -offset indent
 src/sys/dev/acpi/acpica/Osd/custom_dsdt.hex
 .Ed
 .Pp
 or use the option
 .Bd -literal -offset indent
 ACPI_DSDT_FILE="/some/directory/custom_dsdt.hex"
 .Ed
 .Pp
 in the kernel configuration file.
 .It
 Define
 .Tn ACPI_DSDT_OVERRIDE
 in the kernel configuration file and rebuild.
 .El
 .Ss Debugger
 The
 .Tn ACPICA
 interpreter provides its own debugger for low-level debugging.
 It can be used to display internal data structures and namespace objects,
 and to debug the execution of control methods.
 Single step and breakpoint functionality are available.
 In
 .Nx
 this is integrated to the in-kernel
 .Xr ddb 4 .
 In order to enter the
 .Tn ACPICA
 debugger from
 .Xr ddb 4 ,
 use the command
 .Ic call
 with the argument
 .Ic acpi_osd_debugger .
 .Ss Debug Output
 .Nx
 provides three
 .Xr sysctl 8
 variables that control the debug output at runtime.
 The
 .Ic hw.acpi.debug.layer
 variable limits the output to a specific
 .Tn ACPI
 layer and the
 .Ic hw.acpi.debug.level
 variable controls the debug level.
 Both
 .Xr sysctl 8
 variables are string literals.
 The third variable is
 .Ic hw.acpi.debug.object .
 This is a boolean that controls whether debug messages internal to the
 .Tn AML
 are enabled.
 .Pp
 For the first two variables, the possible values are:
 .Bl -column -offset indent \
 "ACPI_RESOURCE_COMPONENT     " "ACPI_RESOURCE_COMPONENT     "
 .It Sy LAYER Ta Sy LEVEL
 .It Li ACPI_DEBUG_NONE Ta ACPI_DEBUG_NONE
 .It Ta
 .It Li ACPI_UTILITIES Ta ACPI_LV_INIT
 .It Li ACPI_HARDWARE Ta ACPI_LV_DEBUG_OBJECT
 .It Li ACPI_EVENTS Ta ACPI_LV_INFO
 .It Li ACPI_TABLES Ta ACPI_LV_ALL_EXCEPTIONS *
 .It Li ACPI_NAMESPACE Ta
 .It Li ACPI_PARSER Ta ACPI_LV_INIT_NAMES
 .It Li ACPI_DISPATCHER Ta ACPI_LV_PARSE
 .It Li ACPI_EXECUTER Ta ACPI_LV_LOAD
 .It Li ACPI_RESOURCES Ta ACPI_LV_DISPATCH
 .It Li ACPI_CA_DEBUGGER Ta ACPI_LV_EXEC
 .It Li ACPI_OS_SERVICES Ta ACPI_LV_NAMES
 .It Li ACPI_CA_DISASSEMBLER Ta ACPI_LV_OPREGION
 .It Li ACPI_COMPILER Ta ACPI_LV_BFIELD
 .It Li ACPI_TOOLS Ta ACPI_LV_TABLES
 .It Li ACPI_EXAMPLE Ta ACPI_LV_VALUES
 .It Li ACPI_DRIVER Ta ACPI_LV_OBJECTS
 .It Li ACPI_ALL_COMPONENTS * Ta ACPI_LV_RESOURCES
 .It Ta ACPI_LV_USER_REQUESTS
 .It Li ACPI_BUS_COMPONENT Ta ACPI_LV_PACKAGE
 .It Li ACPI_ACAD_COMPONENT Ta ACPI_LV_VERBOSITY1 *
 .It Li ACPI_BAT_COMPONENT Ta
 .It Li ACPI_BUTTON_COMPONENT Ta ACPI_LV_ALLOCATIONS
 .It Li APCI_EC_COMPONENT Ta ACPI_LV_FUNCTIONS
 .It Li ACPI_LID_COMPONENT Ta ACPI_LV_OPTIMIZATIONS
 .It Li ACPI_RESOURCE_COMPONENT Ta ACPI_LV_VERBOSITY2 *
 .It Li ACPI_TZ_COMPONENT Ta
 .It Li ACPI_ALL_DRIVERS * Ta ACPI_LV_MUTEX
 .It Ta ACPI_LV_THREADS
 .It Ta ACPI_LV_IO
 .It Ta ACPI_LV_AML_INTERRUPTS
 .It Li "* This is a compound" Ta ACPI_LV_VERBOSITY3 *
 .It Li "  constant, including" Ta
 .It Li "  all previous elements." Ta ACPI_LV_AML_DISASSEMBLE
 .It Ta ACPI_LV_VERBOSE_INFO
 .It Ta ACPI_LV_FULL_TABLES
 .It Ta ACPI_LV_EVENTS
 .It Ta ACPI_LV_VERBOSE *
 .El
 .Pp
 In addition, there is
 .Dv ACPI_DEBUG_DEFAULT
 that is used by
 .Tn ACPICA
 as the default debug level.
 It includes
 .Dv ACPI_LV_INIT
 and
 .Dv ACPI_LV_DEBUG_OBJECT .
 .Pp
 The debug layer can be divided into two groups:
 the first one is specific to the
 .Tn ACPICA
 interpreter and the second one contains the internal
 .Tn ACPI
 components of
 .Nx .
 The constant
 .Dv ACPI_ALL_DRIVERS
 includes all
 .Nx
 specific parts.
 .Pp
 The
 .Tn ACPICA
 interpreter uses several debug levels internally,
 but the
 .Nx
 specific parts are typically limited to
 .Dv ACPI_LV_DEBUG_OBJECT
 and
 .Dv ACPI_LV_DEBUG_INFO .
 The debug output can be stopped by setting
 .Ic hw.acpi.debug.level
 to
 .Dv ACPI_DEBUG_NONE .
 .Ss Example
 As an example, a driver may have defined the component it belongs to and
 the name of the module:
 .Bd -literal -offset indent
 #define _COMPONENT	ACPI_BUS_COMPONENT
 ACPI_MODULE_NAME	("acpi_example")
 .Ed
 .Pp
 The driver may also utilize the debug facility:
 .Bd -literal -offset indent
 ACPI_DEBUG_PRINT((ACPI_DB_INFO, "Failed to evaluate _STA\\n"));
 .Ed
 .Pp
 With these options the debug message from the
 .Dv ACPI_DEBUG_PRINT
 macro is only visible when
 .Ic hw.acpi.debug.layer
 is either
 .Dv ACPI_BUS_COMPONENT
 or a compound constant including it, and
 .Ic hw.acpi.debug.level
 is
 .Dv ACPI_LV_INFO
 or some constant that includes it.
 Finally, it can be noted that the
 .Tn ACPI
 implementation uses the prefix
 .Dv ACPI_DB ,
 whereas the debug level
 .Xr sysctl 8
 variable is always specified with the prefix
 .Dv ACPI_LV .
 .Pp
 Another example can be mentioned for the use of
 .Ic hw.acpi.debug.object .
 The following could appear in an
 .Tn ASL
 code:
 .Bd -literal -offset indent
 Method(_Q19, 0, NotSerialized)
+{
 	Store("_Q19 invoked", Debug)
 	Notify(ACAD, 0x80)
+}
 .Ed
 .Pp
 When
 .Ic hw.acpi.debug.object
 is set to 1, the message stored to the debug object
 is printed every time the method is called by the interpreter.
 .Sh SEE ALSO
 .Xr acpiacad 4 ,
 .Xr acpibat 4 ,
 .Xr acpibut 4 ,
 .Xr acpicpu 4 ,
 .Xr acpidalb 4 ,
 .Xr acpiec 4 ,
 .Xr acpilid 4 ,
 .Xr acpismbus 4 ,
 .Xr acpitz 4 ,
 .Xr acpiwmi 4 ,
 .Xr aibs 4 ,
 .Xr apm 4 ,
 .Xr attimer 4 ,
 .Xr com 4 ,
 .Xr fdc 4 ,
 .Xr hpqlb 4 ,
 .Xr joy 4 ,
 .Xr lpt 4 ,
 .Xr mpu 4 ,
 .Xr npx 4 ,
 .Xr pci 4 ,
 .Xr pckbc 4 ,
 .Xr pcppi 4 ,
 .Xr sony 4 ,
 .Xr spic 4 ,
 .Xr thinkpad 4 ,
 .Xr ug 4 ,
 .Xr vald 4 ,
 .Xr wb 4 ,
 .Xr wss 4 ,
 .Xr ym 4 ,
 .Xr acpidump 8 ,
 .Xr amldb 8 ,
 .Xr iasl 8
 .Rs
 .%A Hewlett-Packard Corporation
 .%A Intel Corporation
 .%A Microsoft Corporation
 .%A Phoenix Technologies Ltd.
 .%A Toshiba Corporation
 .%T Advanced Configuration and Power Interface Specification
 .%N Revision 4.0
 .%D June 16, 2009
 .%U http://www.acpi.info/spec.htm
 .Re
 .Rs
 .%A Intel Corporation
 .%T ACPI Component Architecture,
 .%T Programmer Reference,
 .%T OS-Independent Subsystem, Debugger, and Utilities
 .%N Revision 1.27
 .%D January 20, 2010
 .%U http://www.acpica.org/download/acpica-reference.pdf
 .Re
 .Rs
 .%A Joerg Sonnenberger
 .%A Jared D. McNeill
 .%T Sleeping Beauty - NetBSD on Modern Laptops
 .%D February 3, 2008
 .%O Proceedings of AsiaBSDCon 2008
 .%P pp. 127-134
 .Re
 .Sh HISTORY
 The
 .Nm
 driver
 appeared in
 .Nx 1.6 .
 .Sh BUGS
 Most of the
 .Tn ACPI
 power management functionalities are not implemented.