diff options
Diffstat (limited to 'static/netbsd/man4/acpi.4')
| -rw-r--r-- | static/netbsd/man4/acpi.4 | 573 |
1 files changed, 573 insertions, 0 deletions
diff --git a/static/netbsd/man4/acpi.4 b/static/netbsd/man4/acpi.4 new file mode 100644 index 00000000..8e07254f --- /dev/null +++ b/static/netbsd/man4/acpi.4 @@ -0,0 +1,573 @@ +.\" $NetBSD: acpi.4,v 1.89 2024/09/07 20:33:53 rillig 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 December 5, 2020 +.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="" +.Cd options ACPI_BLACKLIST_YEAR=2000 +.Cd options ACPI__DIS_IS_BROKEN +.Sh DESCRIPTION +.Nx +provides machine-independent bus support for +Advanced Configuration and Power Interface (ACPI) +devices and includes several ACPI device drivers. +.Pp +The +.Nx +implementation of ACPI integrates Intel's ACPI Component Architecture +(ACPI-CA) for the OS-independent part. +The ACPI-CA provides OS-neutral ACPI functionalities such as ACPI BIOS +table support, +an ACPI event framework and an ACPI Machine Language (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 ACPI driver should attempt to activate inactive devices. +The default is off. +.It Dv ACPI_DSDT_OVERRIDE +Force a given Differentiated System Description Table (DSDT) +instead of the version supplied by the BIOS. +Use +.Dv ACPI_DSDT_FILE +to specify a DSDT. +.It Dv ACPI_DSDT_FILE="filename" +If +.Dv ACPI_DSDT_FILE +is not specified, default to +.Dq dsdt.hex +in the build directory. +.It Dv ACPI_BLACKLIST_YEAR=2000 +Do not use ACPI with any BIOS made on or before the specified year. +.It Dv ACPI__DIS_IS_BROKEN +Do not call the ACPI "_DIS" method to disable interrupt links. +This may be required on specific +.Dq nForce4 +chipset systems, which hard hang when this method is called instead of +having it fail gracefully. +.El +.Sh SYSCTL SUPPORT +The following +.Xr sysctl 8 +variables are provided by the +.Nm +driver: +.Bl -tag -width "123456" -offset indent +.It Ic hw.acpi.root +The address of the ACPI root pointer in system memory. +.It Ic hw.acpi.sleep.state +The system sleep state. +.It Ic hw.acpi.sleep.states +A list of system 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.sleep.beep +A boolean variable that controls whether the PC +speaker beeps upon resume. +Only available on i386 and amd64 architectures. +.It Ic hw.acpi.sleep.vbios +Defines the handling of the graphics card on i386 and amd64 architectures. +The supported values are: +.Bl -tag -width '2' -offset 2n +.It 0 +No attempt to reset the VGA controller will be made. +.It 1 +Call the VGA 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 VGA BIOS using the in-kernel x86 emulator. +.El +.Pp +If the system has problems in resuming from the S3 +state, experimenting with different values may provide a solution. +.It Ic hw.acpi.stat.gpe +The number of dispatched General Purpose Events (GPEs). +.It Ic hw.acpi.stat.sci +The number of System Control Interrupts (SCIs). +See +.Xr acpiec 4 +for a brief description of both GPEs and SCIs. +.It Ic hw.acpi.stat.fixed +The number of +.Dq fixed events . +.It Ic hw.acpi.stat.method +The number of AML methods executed by the interpreter. +.It Ic hw.acpi.power +This read-only node describes the ACPI power state of devices. +The values range from D0 +.Pq Dq on +to D3 +.Pq Dq off . +.It Ic hw.acpi.wake +This node represents devices that can wake the system from the S3 or +S4 sleep state. +By default, +.Xr acpibut 4 , +.Xr acpilid 4 , +and +.Xr pckbd 4 +are allowed to wake the system, provided that the devices are present and +the firmware supports wake-up capabilities for the devices. +.El +.Sh SUPPORTED DEVICES +.Nx +ACPI supports several machine-dependent and machine-independent devices, +some specific to ACPI and some configured via it. +.Ss Machine-independent devices +.Bl -tag -width "thinkpad(4) " -offset indent -compact +.It Xr acpiacad 4 +ACPI AC adapters. +.It Xr acpibat 4 +ACPI batteries. +.It Xr acpibut 4 +ACPI power and sleep buttons. +.It Xr acpicpu 4 +ACPI processors. +.It Xr acpidalb 4 +ACPI direction application launch buttons. +.It Xr acpiec 4 +ACPI embedded controllers. +.It Xr acpiecdt 4 +ACPI Embedded Controller Boot Resource Table (ECDT). +.It Xr acpifan 4 +ACPI fans. +.It Xr acpilid 4 +ACPI lid switches. +.It Xr acpipmtr 4 +ACPI power meters. +.It Xr acpismbus 4 +ACPI SMBus via control method interface (CMI). +.It Xr acpitz 4 +ACPI thermal zones. +.It Xr acpivga 4 +ACPI display adapter and output devices. +.It Xr acpiwmi 4 +ACPI support for Windows Management Instrumentation. +.It Xr acpiwdrt 4 +ACPI watchdogs. +.It Xr aibs 4 +ASUSTeK voltage, temperature and fan sensors. +.It Xr asus 4 +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 fujbp 4 +Fujitsu brightness and pointer. +.It Xr fujhk 4 +Fujitsu hotkeys. +.It Xr hpacel 4 +HP 3D DriveGuard accelerometer. +.It Xr hpet 4 +High Precision Event Timer (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 sdhc 4 +SD Host Controller. +.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 valz 4 +Toshiba Dynabook 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 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, +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 BIOS +to the latest version available from the vendor. +.Pp +To ease the task of diagnosing and fixing different problems, the +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 +.Dv ACPI_DEBUG +option. +.Ss Verbose messages +The +.Dv ACPIVERBOSE +compile time option enables some verbose +debug messages printed during the system startup. +In a +.Dv MODULAR +(see +.Xr options 4 ) +system, the information can be printed also at runtime, +regardless of the presence of +.Dv ACPIVERBOSE . +To print the messages, +.Xr modload 8 +the +.Ic acpiverbose +module using the option +.Fl b Cm dump=true . +.Ss Custom DSDT +ACPI interprets bytecode known as ACPI Machine Language (AML), +provided by the BIOS as a memory image during the system bootstrap. +Most of the AML relevant to +.Nm +is implemented in the so-called +Differentiated System Descriptor Table (DSDT). +.Nx +provides support for overriding the default DSDT supplied by the BIOS. +.Pp +The following steps can be used to override the DSDT: +.Bl -enum -offset indent +.It +Dump the raw 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 +.Fl 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 +.Dv ACPI_DSDT_OVERRIDE +in the kernel configuration file and rebuild. +.El +.Ss Debugger +The 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 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 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 +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 Dv ACPI_DEBUG_NONE Ta Dv ACPI_DEBUG_NONE +.It Ta +.It Dv ACPI_UTILITIES Ta Dv ACPI_LV_INIT +.It Dv ACPI_HARDWARE Ta Dv ACPI_LV_DEBUG_OBJECT +.It Dv ACPI_EVENTS Ta Dv ACPI_LV_INFO +.It Dv ACPI_TABLES Ta Dv ACPI_LV_ALL_EXCEPTIONS No * +.It Dv ACPI_NAMESPACE Ta +.It Dv ACPI_PARSER Ta Dv ACPI_LV_INIT_NAMES +.It Dv ACPI_DISPATCHER Ta Dv ACPI_LV_PARSE +.It Dv ACPI_EXECUTER Ta Dv ACPI_LV_LOAD +.It Dv ACPI_RESOURCES Ta Dv ACPI_LV_DISPATCH +.It Dv ACPI_CA_DEBUGGER Ta Dv ACPI_LV_EXEC +.It Dv ACPI_OS_SERVICES Ta Dv ACPI_LV_NAMES +.It Dv ACPI_CA_DISASSEMBLER Ta Dv ACPI_LV_OPREGION +.It Dv ACPI_COMPILER Ta Dv ACPI_LV_BFIELD +.It Dv ACPI_TOOLS Ta Dv ACPI_LV_TABLES +.It Dv ACPI_EXAMPLE Ta Dv ACPI_LV_VALUES +.It Dv ACPI_DRIVER Ta Dv ACPI_LV_OBJECTS +.It Dv ACPI_ALL_COMPONENTS No * Ta Dv ACPI_LV_RESOURCES +.It Ta Dv ACPI_LV_USER_REQUESTS +.It Dv ACPI_BUS_COMPONENT Ta Dv ACPI_LV_PACKAGE +.It Dv ACPI_ACAD_COMPONENT Ta Dv ACPI_LV_VERBOSITY1 No * +.It Dv ACPI_BAT_COMPONENT Ta +.It Dv ACPI_BUTTON_COMPONENT Ta Dv ACPI_LV_ALLOCATIONS +.It Dv ACPI_EC_COMPONENT Ta Dv ACPI_LV_FUNCTIONS +.It Dv ACPI_LID_COMPONENT Ta Dv ACPI_LV_OPTIMIZATIONS +.It Dv ACPI_RESOURCE_COMPONENT Ta Dv ACPI_LV_VERBOSITY2 No * +.It Dv ACPI_TZ_COMPONENT Ta +.It Dv ACPI_DISPLAY_COMPONENT Ta +.It Dv ACPI_ALL_DRIVERS No * Ta Dv ACPI_LV_MUTEX +.It Ta Dv ACPI_LV_THREADS +.It Ta Dv ACPI_LV_IO +.It Ta Dv ACPI_LV_AML_INTERRUPTS +.It "* This is a compound" Ta Dv ACPI_LV_VERBOSITY3 No * +.It " constant, including" Ta +.It " all previous elements." Ta Dv ACPI_LV_AML_DISASSEMBLE +.It Ta Dv ACPI_LV_VERBOSE_INFO +.It Ta Dv ACPI_LV_FULL_TABLES +.It Ta Dv ACPI_LV_EVENTS +.It Ta Dv ACPI_LV_VERBOSE No * +.El +.Pp +In addition, there is +.Dv ACPI_DEBUG_DEFAULT +that is used by 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 ACPICA +interpreter and the second one contains the internal ACPI +components of +.Nx . +The constant +.Dv ACPI_ALL_DRIVERS +includes all +.Nx +specific parts. +.Pp +The 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_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 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 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 FILES +.Bl -tag -width /dev/acpi +.It Pa /dev/acpi +.El +.Sh SEE ALSO +.Xr ioapic 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 Len Brown +.%T ACPI in Linux - Myths vs. Reality +.%D June 27-30, 2007 +.%O Proceedings of the Linux Symposium +.%P 65-74 +.%U http://www.linuxsymposium.org/archives/OLS/Reprints-2007/brown_1-Reprint.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 127-134 +.%U https://2008.asiabsdcon.org/papers/P9A-paper.pdf +.Re +.Rs +.%A Takanori Watanabe +.%T ACPI Implementation on FreeBSD +.%I USENIX Association +.%B Proceedings of the FREENIX Track: 2002 USENIX Annual Technical Conference +.%P 121-131 +.%D June 10-15, 2002 +.%U https://www.usenix.org/legacy/event/usenix02/tech/freenix/full_papers/watanabe/watanabe.pdf +.Re +.Sh HISTORY +The +.Nm +driver +appeared in +.Nx 1.6 . +.Sh AUTHORS +.An -nosplit +Authors of the +.Nm +subsystem include +.An Charles M. Hannum , +.An Frank van der Linden , +.An Jared D. McNeill , +.An Jason R. Thorpe , +.An Joerg Sonnenberger , +and +.An Jukka Ruohonen , +among others. +.Sh BUGS +Most of the ACPI power management functionalities are not implemented. +.Pp +The +.Dv ACPI__DIS_IS_BROKEN +option should not be necessary. |