Linux ACPI-HOWTO Ariel Glenn, ariel@columbia.edu v 0.1c, 16 July 2000 This document describes how to compile, install, and use the ACPI driver for Linux and its associated applications. The latest version of this document can be found at http://www.columbia.edu/~ariel/acpi/acpi_howto.txt. --------------------------------------------------------------------- Table of Contents 1. General information and hardware requirements 1.1 Introduction 1.2 Copyright notice and disclaimer 1.3 Changes to this document 1.4 Where are the latest acpi driver / acpid package / pmtools package, and where can I get them? 1.5 Are binary distributions available? 1.6 What chipsets are supported? 1.7 Which kernels are supported? 1.8 Which BIOSes are supported? 1.9 When will my favorite (unsupported) system become supported? 1.10 What ACPI capabilities are supported? 1.11 Mailing lists and other information sources 2. Compilation and installation 2.1 Prerequisites and kernel setup 2.2 Compilation and installation of acpid and acpictl 2.3 Compilation and installation of pmtools 2.4 Driver options 2.5 System resource settings 3. Miscellaneous driver information 3.1 What are all these proc entries and how can I use them? 3.2 What do these messages from 'e820' in /var/log/messages mean? 4. Debugging tips and programming information 4.1 The driver isn't working right for me. How can I figure out what's wrong? 4.2 Submitting useful bug reports 4.3 Guidelines for Linux device driver writers 6. Credits and license information 6.1 Credits 6.2 GNU Free Documentation License ------------------------------------------------------------------------ 1.1 Introduction ACPI, which stands for Advanced Configuration and Power Interface, is the successor to APM (Advanced Power Management). The specification provides for many functions besides power management, such as thermal management and plug-and-play events. However, this document concentrates on the power management functions, which is the principal work of the ACPI4Linux group to date. ACPI support for Linux consists of a driver which is supplied with recent kernels, a daemon and user client contained in the acpid package, and a set of analysis and debugging tools called pmtools. These packages and the driver are still in the early stages of development. They should not be considered stable software. Please take appropriate precautions before using them. Having said that, however, the more people help to test and debug them and add features, the sooner they will become production quality. Your help is most welcome! Please send suggestions, complaints or comments about this document to ariel@columbia.edu. Please do NOT send me bug reports about the driver; see section 4.2 (Submitting useful bug reports) for more information on reporting driver bugs. 1.2 Copyright notice and disclaimer Copyright (c) 2000 Ariel T. Glenn Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". This document is provided ``AS IS'', with no express or implied warranties. Use the information in this document at your own risk. 1.3 Changes to this document 0.1c Added documentation for pmtest script and utility Corrected version number of ACPI spec Added information on the driver included with the 2.4.0-test3 series of kernels and later (new /proc interface, reduced functionality of new acpid, changed driver options) 1.4 Where are the latest acpi driver / acpid package / pmtools package, and where can I get them? The latest version of the acpi driver is always included in the most recent Linux kernel which, as of this writing, is 2.4.0-test5-pre1. You can get the kernel at ftp://ftp.kernel.org/ or any of its mirror sites. Patches are not backported to earlier versions. The latest acpid is acpid-071100.tar.gz for 2.4.0-test3 and later kernels with the AML interpreter enabled, and acpid-052200.tar.gz otherwise. The latest pmtools is pmtools-060600.tar.gz. The latest versions are always available from http://www.geocities.com/SiliconValley/Hardware/3165/ and are mirrored at http://phobos.fs.tum.de/acpi/download.html. These packages include the full source. 1.5 Are binary distributions available? No; the driver is included only in development kernels and so precompiled versions are not available. Acpid and pmtools are still alpha software and likewise are not ready for binary distribution. 1.6 What chipsets are supported? In theory, any compliant ACPI implementation is supported. In practice, there are a lot of buggy ACPI implementations out there. Even implementations based on chipsets specifically targeted by the driver can have their oddities. The specific systems that are known to behave in a way the driver expects are: (list them here) Systems known to have odd behavior are: (list them here) 1.7 Which kernels are supported? The ACPI driver was included with the development kernel starting with version 2.3.19. Patches were at one time made available for 2.2.x but as new features have been added, no attempt has been made to backport the changes to the 2.2.x patches, and those patches are no longer available. 1.8 Which BIOSes are supported? A table of BIOS manufacturers and versions, along with what ACPI capabilities the BIOS supports, is available at http://phobos.fs.tum.de/acpi/bios.sql. 1.9 When will my favorite (unsupported) system become supported? If you test the package and can send the developers information about your ACPI BIOS, they will get to it sooner. If you write some code for your BIOS and submit it, they'll get to it even sooner yet :-) See section XXX on how to determine the capabilities of your BIOS. 1.10 What ACPI capabilities are supported? Currently, sleep mode (S1), resume, and power off (S5) are the only ACPI capabilities supported by the driver. Next on the todo list are other suspend states; lower on the list because it must be coordinated with updates to other device drivers is suspend-to-disk (hibernation). 1.11 Mailing lists and other information sources The ACPI driver and supporting packages are the work of the ACPI4Linux project, which has a web site at http://phobos.fs.tum.de/acpi/. The project has a mailing list which users and developers can join, by sending mail to acpi-request@phobos.fs.tum.de with the subject list "Subscribe" or by using the Web interface to subscribe at http://phobos.fs.tum.de/mailman/listinfo/acpi. Archives of the list are kept at http://phobos.fs.tum.de/pipermail/acpi/. The ACPI specification itself is on the Web at http://www.teleport.com/~acpi/, and a description of the ACPI Component Architecture, including in particular the AML interpreter and ACPI core code used in acpid, is available at ftp://download.intel.com/technology/iapc/downloads/cadoc100.zip. 2.1 Prerequisites and kernel setup There are two versions of the driver. The version included in kernels earlier than 2.4.0-test3 will be referred to as the no-AML-interpreter version; this is the same version you run if you answer 'n' to CONFIG_ACPI_INTERPRETER in later versions of the kernel. (See below for configuration options.) The version included in 2.4.0-test3 and later kernels that you run if you say 'y' to CONFIG_ACPI_INTERPRETER will be referred to as the includes-AML-interpreter version. You will need to know which version of the driver you are running when reading this document. You should start by obtaining the most recent kernel, 2.4.0-xxx. Earlier versions of the driver included with earlier versions of the kernel are not guaranteed to work with the most recent acpid or pmtools, and only the latest versions of those packages are guaranteed to be available. Make sure that you update all packages required to build the kernel; see the file Documentation/Changes in the kernel source tree for information. For more general information on building the Linux kernel, see the Kernel-HOWTO. Linux HOWTOS are kept at many sites, including the Linux Documentation Project, http://www.ldp.org/. You will need to rebuild your kernel to include ACPI support. Say 'y' to the CONFIG_ACPI option. If you want to build in the (as yet) experimental support for sleep mode, say 'y' to the CONFIG_ACPI_S1_SLEEP option as well. You do not need to disable APM support; if ACPI support is found at run-time, APM support will be turned off automatically in the running kernel. If you want to try the new 2.4.0-test3 or later driver interface, say 'y' to CONFIG_ACPI_INTERPRETER, which builds the AML interpreter right into the kernel and makes some changes in the /proc/sys/acpi interface as well. After configuration, build and install your kernel as usual. You can test the driver by examining /proc/sys/acpi; if there isn't one, odds are you didn't configure the kernel correctly. Otherwise, if you have the includes-AML-interpreter driver, you should see /proc/sys/acpi/c2_exit_latency /proc/sys/acpi/c2_enter_latency /proc/sys/acpi/c3_exit_latency /proc/sys/acpi/c3_enter_latency /proc/sys/acpi/event If you have the no-AML-interpreter driver you should see the entries /proc/sys/acpi/facp /proc/sys/acpi/dsdt /proc/sys/acpi/pm1_enable /proc/sys/acpi/gpe_enable /proc/sys/acpi/gpe_level /proc/sys/acpi/event /proc/sys/acpi/p_blk /proc/sys/acpi/p_lvl2_lat /proc/sys/acpi/p_lvl3_lat /proc/sys/acpi/enter_lvl2_lat /proc/sys/acpi/enter_lvl3_lat /proc/sys/acpi/s0_slp_typ /proc/sys/acpi/s1_slp_typ /proc/sys/acpis5_slp_typ. In either case, if you compiled in the sleep option, you should also see /proc/sys/acpi/sleep. If you have the no-AML-interpreter driver, you can try cat -v /proc/sys/acpi/facp | more which should start with the characters 'FACP' and should then have a few bytes of garbage followed by an OEM name. If you see this, odds are that the driver has found the appropriate tables from your BIOS and is ready to roll. If not, you may need to set one of the boot options (or module options) as described in the driver options section. If you have the includes-AML-interpreter driver, there's not much in /proc for you to look at. You can check in /var/log/messages for the entry 'ACPI: ACPI support found'; if you see this, all tables including the FACP should have been loaded and the AML namespace loaded successfully as well. However, if you later see 'ACPI: enable failed' this means that there was a problem setting up event or SCI handlers or putting the system into ACPI mode, and your system will not be processing ACPI events. A more detailed discussion of log entries is in section XXX. 2.2 Build and Installation of apcid and acpictl Once you have rebuilt the Linux kernel with ACPI support, download the appropriate version of acpid. If you have the includes-AML-interpreter driver, you should download acpid-071100.tar.gz; if you answered 'n', you should download acpid-052200.tar.gz. Make a directory where you want to build the package. Cd into the directory and unpack the archive by giving the command zcat acpid-xxx.tar.gz | tar xvf - where xxx is the version of the package you downloaded. In the same directory, type ./configure to configure the package, make to build it, and make install to install it. Note that the default installation directory is /usr/local; if you prefer to install the files somewhere else, you will need to configure the package with ./configure --prefix=/new/place/to/put/them The programs installed are acpid and acpictl. Acpid will by default be placed in /usr/local/sbin, and acpictl will be placed in /usr/local/bin. No man pages are available for them currently, so here is a quick summary of each program. If you have the includes-AML-interpreter driver, read this section. Acpid is a daemon that watches for ACPI events and processes them; it also watches for user requests and sends them to the driver. It accepts the following options: -d or --debug Run daemon in the foreground. -v or --version Print version information. Acpictl is a user client that talks to acpid. It accepts the following options: -p or --pid print acpid's pid -b or --battery print battery information -- this option doesn't work with the new driver yet. -i or --intermediary act as intermediary between another program and acpid The intermediary option does not actually do anything right now :-) If you have the no-AML-interpreter driver, read this section. Acpid is a daemon that watches for ACPI events and processes them; it also watches for user requests and sends them to the driver. It accepts the following options: -d or --debug Run daemon in the foreground. -t or --trace Create a (sizeable) debug trace. -v or --version Print version information. The debug option, besides running acpid without disassociating from the tty, allows the user to specify various commands interactively. The list of commands can be seen by giving the command 'help' when in debug mode. Acpictl is a user client that talks to acpid. It accepts the following options: -p or --pid print acpid's pid -b or --battery print battery information -i or --intermediary act as intermediary between another program and acpid The intermediary option does not actually do anything right now :-) 2.3 Compilation and installation of pmtools You need perl to run some of the utilities in this package. Make sure you have downloaded the most recent version of pmtools. Make a directory where you want to build the package. Cd into the directory and unpack the archive by giving the command zcat pmtools-xxx.tar.gz | tar xvf - where xxx is the version of the package you downloaded. In the same directory, type make to build the package. No facilities are provided yet to install the utilities, so you will have to copy them to the appropriate place by hand: cp acpianalyze/acpianalyze /usr/local/bin cp acpidisasm/acpidisasm /usr/local/bin cp acpidmp/acpidmp acpdmp/acpitbl acpidmp/acpxtract /usr/local/bin cp pmtest/pmtest /usr/local/bin or to whichever directory you would like to install them. No documentation is provided for this package either, so here is a quick summary. Acpidmp must be run as root or installed suid (better to run it as root, if you have a multiuser system, but then why are you installing development kernels on it?) It looks for the tables provided by your ACPI BIOS and dumps the one you specify to stdout. The table names it knows are FACP, DSDT, and RSDT. If you want to know the innards of these tables, you should look at the ACPI version 1.0b specification. If you do not provide a name, all of the tables it finds will be dumped to stdout. It will also show the RSDP, which you can not ask for on the command line. Acpidmp does not produce human-readable output. For that, you need to pipe it through acpidisasm. Example: on my Sony VAIO F420, acpidmp DSDT | acpidisasm produces the output 00000000: Scope _PR_ (\_PR_) 00000006: Processor CPU0 (\_PR_.CPU0) 0000000d: 0x00 0000000e: 0x00008010 00000012: 0x06 00000013: Name _S0_ (\_S0_) 00000018: Package 0000001a: 0x04 0000001b: 0x05 0000001d: 0x05 0000001f: 0x00 00000021: 0x00 00000023: Name _S1_ (\_S1_) 00000028: Package 0000002a: 0x04 0000002b: 0x04 0000002d: 0x04 0000002f: 0x00 00000031: 0x00 00000033: Name _S3_ (\_S3_) 00000038: Package 0000003a: 0x04 ... (There are 3800 lines or so of output so I'll spare you the rest.) This actually disassembles the AML that is found in the DSDT table. If you have the no-AML-interpeter driver, you can use acpitbl to see table headers and registers without AML; this relies on /proc entries which are not available when the interpreter is enabled in the kernel. Here's an example from my laptop. acpitbl /proc/sys/acpi/dsdt produces Signature: DSDT Length: 11841 Revision: 0x01 Checksum: 0x3c OEMID: SONY OEM Table ID: K1 OEM Revision: 0x20000203 Creator ID: MSFT Creator Revision: 0x01000007 which is just the dsdt table header. The FACP table may be examined in the same fashion: acpitbl /proc/sys/acpi/facp shows, on my laptop, Signature: FACP Length: 116 Revision: 0x01 Checksum: 0x12 OEMID: SONY OEM Table ID: K1 OEM Revision: 0x20000203 Creator ID: PTL Creator Revision: 0x000f4240 FIRMWARE_CTRL: 0x03ffffc0 DSDT: 0x03ffc924 INT_MODEL: 0x00 SCI_INT: 9 SMI_CMD: 0x000000b2 ACPI_ENABLE: 0xf0 ACPI_DISABLE: 0xf1 S4BIOS_REQ: 0xf2 PM1a_EVT_BLK: 0x00008000 PM1b_EVT_BLK: 0x00000000 PM1a_CNT_BLK: 0x00008042 PM1b_CNT_BLK: 0x00000000 PM2_CNT_BLK: 0x00000022 PM_TMR_BLK: 0x00008008 GPE0_BLK: 0x0000800c GPE1_BLK: 0x00000000 PM1_EVT_LEN: 4 PM1_CNT_LEN: 2 PM2_CNT_LEN: 1 PM_TM_LEN: 4 GPE0_BLK_LEN: 4 GPE1_BLK_LEN: 0 GPE1_BASE: 0 P_LVL2_LAT: 10 P_LVL3_LAT: 4097 FLUSH_SIZE: 0 FLUSH_STRIDE: 0 DUTY_OFFSET: 1 DUTY_WIDTH: 3 DAY_ALRM: 0x0d MON_ALRM: 0x00 CENTURY: 0x32 Flags: 0x00000000 You should see the same entry names, though your values may vary. Alternatively, instead of reading from /proc or if you have the includes-AML-interpreter driver you can read right from /dev/mem by doing acpidmp FACP | acpitbl which should net you the same results. This is the only option you have available to you if you said 'y' to CONFIG_ACPI_INTERPRETER. Pmtest is intended for device driver writers who are adding support for different sleep states in their drivers. It is a kernel module which sets up the following entries in /proc: /proc/driver/pmtest/devices Reading from this interface lets you see which devices have been registered for power management, and what state they are in. It writes out triplets of devicetype deviceid state for each device, where state is 0-3 for device states D0-D3, devicetype is 0-5, where the mapping is given by the device types enumerated in /usr/include/linux/pm.h, and deviceid is one of those also listed in /usr/include/linux/pm.h. /proc/driver/pmtest/control Writing to this file lets you place one of the devices in the list shown in /proc/driver/pmtest/devices into a suspend state (one of D0-D3). You should write a triplet like those you see when you look at /proc/driver/pmtest/devices above, devicetype deviceid state You should use the perl scrip tpmtest in the same directory instead of using the module directly. Why? Because it's easy, it's convenient, and then you don't have to translate numeric device ids and types (for most commands). Make sure insmod and rmmod are in your path. You want to be root to run this. Pmtest loads the module, runs the command you give, and then unloads the module, very convenient for testing. Usage: pmtest [OPTION] [TYPE] [ID] where OPTION is one of: -l list devices (default) -d0 resume device (ACPI D0) -d1, -d2, -d3 suspend device (ACPI D1-D3) and TYPE is one of: unknown PCI USB SCSI ISA system and ID is one of: keyboard serial irda floppy vga pcmcia or a specific device number from /usr/include/linux/pm.h. Examples: pmtest -l PCI list all registered PCI devices pmtest -d0 VGA resume (unblank) the console pmtest -d3 PCI 0x1234 suspend a PCI device For example, on my laptop (with ACPI turned off), I see [root@devel2 pmtest]# ./pmtest -l VGA (D0) PCMCIA (D0) keyboard (D0) PCI 0x0 (D0) 2.4 Driver options If you have the includes-AML-interpreter driver, there are no run-time options. If you have the no-AML-interpreter driver, the ACPI driver supports the following run-time (module or kernel boot) options: on upon initialization, the driver will try to find an ACPI-compliant device and use it. (set by default) off the driver will not look for an ACPI-compliant device, and will not do any ACPI event processing. No /p[roc entries will be created. Use this option to disable ACPI at runtime. If you compile in ACPI together with APM, you can use this option to turn off ACPI so that APM handles power management events. (off by default) tables An ACPI BIOS provides several tables which contain information about capabilities, pointers to status registers, and pointers to registers which can cause a change in sleep status, among other things. These tables are used by the driver to enable and trigger ACPI events. Generally, a given chipset should always have the same capabilities and registers, but if you want to be sure that you are using the tables provided by the BIOS, set this option. (off by default) chipset The counterpart to the tables option above, this option tells the driver to use a predefined table for one of a list of known chipsets; if your device is one of these and you suspect the BIOS-provided tables of being inaccurate, try this option. The list of chipsets for which this option is supported is currently PIIX4 and VIA. (off by default) no-errata The ACPI implementor may have 'published' changes to the root-level ACPI table header (RSDP). In theory, this option should tell the driver to ignore these changes. In practice, this option appears to be unimplemented in the current version of the driver. copy-tables If this option is set, the FACP and DSDT ACPI tables will be copied to a new location in memory before they are used. Some ACPI BIOSes require this. These BIOSes put the tables in low memory without being reserved by the memory map code. Copying ensures that we have a good snapshot of the table available for later use. You'll know if your BIOS is one of these by noticing if, upon initialization, the driver writes the error "ACPI: unreserved memory @ 0xnn!" in /var/log/messages. (For a fixed list of BIOSes this option is on by default; currently that list consists of AMI only. For all other BIOSes, this option is off by default.) trust-tables This option is generally used in conjunction with the copy-table option above. Use it when your BIOS publishes ACPI tables in low memory without them being reserved by the memory map code. You'll see the same message as above in your log. WARNING: if you use this option and the tables are not really there, a kernel panic will result. (For a fixed list of BIOSes this option is on by default; currently that list consists of AMI only. For all other BIOSes, this option is off by default.) no-sci If this option is enabled, no irq will be requested for ACPI and no events will be enabled or processed. In particular, changes may not be made to the pm1x_evt, gpe0 and gpe1 registers. You may want to use this option if you would like the driver to load the ACPI tables but not to do any event handling, for debugging purposes. (off by default) no-c2 Before initialization, some global variables are set so that the no-c3 processor power states C2 and C3 states cannot be entered. During normal initialization, C2 (cpu idle) and C3 (cpu idle, caches ignore snoops) states are both enabled. This step will be skipped if these options are enabled. Set the no-c2 option to disable entering C2; set no-c3 to disable entering C3. (off by default) no-s1 If these options are enabled, the S1 and S5 sleeping states will no-s5 not be entered. Set no-s1 to disable entering S1 or sleep mode; set no-s5 to disable entering S5 (soft off). (no-s5 is off by default; no-s1 is on if CONFIG_ACPI_S1_SLEEP was not defined during configuration of the kernel, and off otherwise) 2.5 System resource settings If the pci driver cannot find an interrupt for the appropriate pin of the ACPI device, you may need to specify pci=biosirq as a boot option to the kernel. Ordinarily the kernel looks for the IRQ routing table for PCI interrupts in the region of memory reserved for that table, but if it cannot find the table, and the pci=biosirq option is set, the kernel will then proceed to try to get the same information from the PCI BIOS. In rare cases the ACPI interrupt may conflict with some other device already configured on your system. You may disable that other device or try to reconfigure it. To check for interrupt conflicts, cat /proc/interrupts and examine the output. The only devices you should see that share an interrupt with the ACPI device are PCI devices; all others should be using some other interrupt(s). My sample output, for example, shows [ariel@devel2 kernel]$ cat /proc/interrupts CPU0 0: 5416567 XT-PIC timer 1: 55261 XT-PIC keyboard 2: 0 XT-PIC cascade 3: 364126 XT-PIC wvlan_cs 8: 7 XT-PIC rtc 9: 134 XT-PIC ACPI, Ricoh Co Ltd RL5c478, Ricoh Co Ltd RL5c478 (#2) 12: 602159 XT-PIC PS/2 Mouse 13: 1 XT-PIC fpu 14: 129102 XT-PIC ide0 15: 9 XT-PIC ide1 NMI: 0 ERR: 0 A quick check of /proc/pci shows that the two Ricoh devices are cardbus bridges on the PCI bus, so they can share the same interrupt comfortably. One user reported seeing both ACPI and fpu on 13; this is a case of a genuine conflict which must be resolved if the device is to function properly. 3.1 What are all these proc entries and how can I use them? If you have the includes-AML-interpreter driver, read this section. /proc/sys/acpi/c2_exit_latency /proc/sys/acpi/c3_exit_latency These indicate the latency for exiting level 2 or level 3 processor sleep states (C2 or C3). These can be used to do things like "sleep in C2 until the power drops to %n (where %n is computed based on the latency for coming out of C3)..." Initially they are set to infinity, but when C2 and C3 are enabled, these are determined by values in the FACP table. If your driver cannot read the tables fro the BIOS and relies on its predefined tables instead, these values are left at infinity. You will then have to change them yourself to some reasonable values in order to enable C2 and C3 states. /proc/sys/acpi/c2_enter_latency /proc/sys/acpi/c3_enter_latency These indicate the latency for entering C2 or C3 sleep states. These are pretty short and are fixed, except initially when they are infinite (so that the states will not be entered until they are specifically enabled). /proc/sys/acpi/event Reading from this entry shows you the hex value associated with ACPI events noticed by the BIOS (and enabled). If in one window you do cat /proc/sys/acpi/event and in another window try pressing various buttons and key combinations, you can see if any of them register as ACPI events and how they register. Not all events are enabled by the driver. Currently there is no way to enable all events as you could do under the no-AML-interpreter driver. Your power button will only be visible as an event under /proc/sys/acpid/event if it is enabled by the driver. /proc/sys/acpi/sleep Writing to this is currently the only way to put the system into a sleep state; specifically, it will enter S1 if you echo 1 > /proc/sys/acpi/sleep WARNING: before you do this, it is a good idea to quit unnecessary processes. Possibly, your system may not recognize the various key presses that are supposed to trigger a wake-up! (Mine does not with the current driver.) If you have the no-AML-interpreter driver, read this section. Most of the ACPI /proc entries are informational; a few can be used to trigger ACPI events. Here is a decription of each one and how it can be used. /proc/sys/acpi/facp This allows access to the FACP table header and body. Reading this gives you a look at the table, which can can be examined to understand your ACPI's capabilities and current state; writing to it can either replace the header and body of the entire table (ordinarily only done by the driver) or can update the value of a single register. To read the FACP table and make any sense of it, you probably want to use the pmtools package and run the command acpitbl /proc/sys/acpi/facp which presents a more-or-less human-readable dump of the table. /proc/sys/acpi/dsdt This allows access to the DSDT table header and body. The notes on the facp entry hold here as well, with the exception that, to read the dsdt entry and make sense of it, you will want to run the command acpitbl /proc/sys/acpi/dsdt to look at the header, and cat /proc/sys/acpi/dsdt | acpidisasm to read the AML (disassembled). /proc/shys/acpi/pm1_enable Reading from this entry shows you which power management events are enabled. Each event has a corresponding bitmask; if the bits in the value corresponding to that mask are set, then the event is enabled, otherwise, it is disabled. Writing to this entry enables events. To enable all power management events that your ACPI implementation supports, write "0xffffffff" to the entry. When you read it, you will most likely not see 0xffffffff as the value, because not all defined events will be supported. (Even if they were, are all the bits in use?) How to determine which events correpsond to which bitmasks... /proc/sys/acpi/gpe_enable Reading from this entry shows you which general purpose events are enabled. Manipulating this entry is done in the same way as the pm1_enable entry described above. How to determine which events correspond to which bitmasks... /proc/sys/acpi/gpe_level Reading from this entry shows you which level the current general purpose events are; writing to it changes that level. (Read the spec for more info; section 4.7 talks about child events a bit.) /proc/sys/acpi/event Reading from this entry shows you the hex value associated with ACPI events noticed by the BIOS (and enabled). If you enable all events by writing 0xffffffff to gp1_enable and pm1_enable, and then in one window do cat /proc/sys/acpi/event and in another window try pressing various buttons and key combinations, you can see if any of them register as ACPI events and how they register. This is one way to see what your power button does, for example. For example, on my Sony VAIO, I did the following: [root@devel2 kernel]# echo 0xffffffff > /proc/sys/acpi/pm1_enable [root@devel2 kernel]# echo 0xffffffff > /proc/sys/acpi/gpe_enable [root@devel2 kernel]# cat /proc/sys/acpi/pm1_enable 0x00000521 [root@devel2 kernel]# cat /proc/sys/acpi/gpe_enable 0x00000f01 (press power button) [root@devel2 kernel]# cat /proc/sys/acpi/event 0x00000001 0x00000000 0x0 0x00000001 0x00000000 0x0 0x00000000 0x00000200 0x0 You can see the power button press: it's the last line in the cat. /proc/sys/acpi/p_blk There is one of these for each processor (according to the spec); it's used to control the processor, for example, to put it into C2 or C3 state. The driver only supports one processor at the moment, so there is only space for one of these in the /proc interface. You should never need to write to it directly; the driver will do that for you when switching from one sleep state to another. /proc/sys/acpi/p_lvl2_lat /proc/sys/acpi/p_lvl3_lat These indicate the latency for exiting level 2 or level 3 sleep states. These can be used to do things like "sleep in C2 until the power drops to %n (where %n is computed based on the latency for coming out of C3)..." Initially they are set to infinity, but when C2 and C3 are enabled, these are determined by values in the FACP table. If you are using the 'chipset' option to the driver, these values are set to infinity and are never changed; you will have to change them yourself to some reasonable values in order to enable C2 and C3 states. Likewise if the driver can't find your tables and falls back to using the chipset information, you will have to set the values yourself. /proc/sys/acpi/enter_lvl2_lat /proc/sys/acpi/enter_lvl3_lat These indicate the latency for entering level 2 or level 3 sleep states. These are pretty short and are fixed, except initially when they are infinite (so that the states will not be entered until they are specifically enabled). /proc/sys/acpi/s0_slp_typ /proc/sys/acpi/s1_slp_typ /proc/sys/acpi/s5_slp_typ These indicate the value that, after some processing, needs to be stuffed into pm1a_cnt and pm1b_cnt in order to place your system into the appropriate sleep state (S0, S1, or S5). The driver does not initialize these by itself; acpid looks them up via the BIOS nd then asks the driver to set them according to the values it retrieved. If you have trouble with acpid and want to set these values directly, you could try guessing according to the chipset, or you could try looking at the output from a dump of the DSDT. (Use the command acpidmp DSDT | acpidisasm.) It may indicate the values in a section something like: 00000013: Name _S0_ (\_S0_) 00000018: Package 0000001a: 0x04 0000001b: 0x05 0000001d: 0x05 0000001f: 0x00 00000021: 0x00 00000023: Name _S1_ (\_S1_) 00000028: Package 0000002a: 0x04 0000002b: 0x04 0000002d: 0x04 0000002f: 0x00 00000031: 0x00 00000033: Name _S3_ (\_S3_) 00000038: Package 0000003a: 0x04 0000003b: 0x01 0000003d: 0x01 0000003f: 0x00 00000041: 0x00 and so on. You can see that the second and third bytes in each entry correspond to the values in the logs below. If acpid is working, you can also see these values in /var/log/messages, written when acpid starts up. For example, my log entries look like Jun 11 00:51:02 devel2 acpid: S0 SLP_TYP (0x0505) Jun 11 00:51:02 devel2 acpid: S1 SLP_TYP (0x0404) Jun 11 00:51:02 devel2 acpid: S2 not supported Jun 11 00:51:02 devel2 acpid: S3 SLP_TYP (0x0101) Jun 11 00:51:02 devel2 acpid: S4 SLP_TYP (0x0000) Jun 11 00:51:02 devel2 acpid: S5 SLP_TYP (0x0000) Yes, you get a couple of bonus numbers for which there are no proc entries currently. /proc/sys/acpi/sleep Writing to this is currently the only way to put the system into a sleep state; specifically, it will enter S1 if you echo 1 > /proc/sys/acpi/sleep WARNING: before you do this, it is a good idea to quit unnecessary processes. Possibly, your system may not recognize the various key presses that are supposed to trigger a wake-up! (Mine does not with the current driver.) 3.2 What do these messages from 'e820' in /var/log/messages mean? You may see messages like these in your /var/log/messages: e820: 000000000000f800 @ 0000000003ff0000 (ACPI data) e820: 0000000000000800 @ 0000000003fff800 (ACPI NVS) Interrupt 15 subfunction e820 causes the BIOS to return the system memory map. The data area includes the various ACPI tables. This area cvan be reclaimed by the OS when it's done using the tables. NVS stands for Non-Volatile-Sleeping Memory; this area is supposed to be saved and restored by the OS before entering the S4 state. This area can never be reclaimed. If you don't see the ACPI data message in your logs, this is probably an indication that the driver can't find the tables. If it appears to be working anyways, it is probably using chipset-specific information. You can experiment with the boot options to find out (see section 2.4 for more information). 4.1 The driver isn't working right for me. How can I figure out what's wrong? If you have the includes-AML-interpreter driver, read this section. First, is the driver initializing? You can determine this by checking for /proc/sys/acpi entries. If it is, does your driver locate the APCI tables for your BIOS or is it guessing based on the chipset? You can determine this by looking in /var/log/messages for the message 'ACPI: support found'; if you see this message, the driver is getting the table information from the BIOS. If you don't see this message, but the driver has initialized, you are using chipset-based information, predefined for the PIIX4 or the VIA. If it is using the tables, what do they show? Use acpidmp DSDT | acpidisasm and acpidmp FACP | acpitbl to examine them. Does pressing your power button register as an ACPI event? To check this, cat /proc/sys/acpi/events and watch it; then in another window press the power button. Do you see a change? A non-zero value? Do you see instead an entry in /var/log/messages, like 'ACPI: EC GPE'? This is a pretty preliminary checklist; suggestions are appreciated. If you have the no-AML-interpreter driver, read this section. First, is the driver initializing? You can determine this by checking for /proc/sys/acpi entries. If it is, does your driver locate the APCI tables for your BIOS or is it guessing based on the chipset? You can determine this by using the tables option to the driver and see if the driver still initializes. If it is using the tables, what do they show? Use acpidmp DSDT | acpidisasm and acpidmp FACP | acpitbl to examine them. If you start acpid, then shoot it, then shutdown your host, does power off actually work (or does it sit there after writing 'Power off' to the console)? Does pressing your power button register as an ACPI event? To check this, echo "0xffffffff" > /proc/sys/acpi/pm1_enable echo 0xffffffff > /proc/sys/acpi/gpe_enable Now in one window do cat /proc/sys/acpi/events and watch it; then in another window press the power button. Do you see a change? A non-zero value? This is a pretty preliminary checklist; suggestions are appreciated. 4.2 Submitting useful bug reports If you would like to report an ACPI bug, please include the following information: 1) Any system information you have available (motherboard, chipset, BIOS, system vendor) 2) Any relevant information from the kernel log: do dmesg | grep -iE 'version|acpi|apm|e820' > kernel.log to get the relevant lines 3) Actual description of the problem you are experiencing and if possible how to reproduce it 4) Output of acpidmp: get this by acpidmp > acpidmp.log Acpidmp is part of the pmtools package described in section 2.3. If you have the no-AML-interpreter driver, do this. 5) Output of acpid with debug turned on: get this by doing acpid -d >& acpid.log If (and only if) acpid crashes, instead send a full debug trace by: acpid -dt >& acpid.log Beware, this file is going to be *large*. If you have the includes-AML-interpreter driver, do this. 5) Output of acpid with debug turned on: get this by doing acpid -d >& acpid.log 6) Package up the bug report and log files by: tar cvf - bugreport.txt *.log | gzip -9 > bug.tar.gz and mail them (preferrably as an attachment) to andy_henroid@yahoo.com. 7) You should also forward the bug report to the ACPI4Linux mailing list (acpi@phobos.fs.tum.de). PLEASE DO NOT INCLUDE ANY OF THE LOG FILES TO THE MAILING LIST AS THESE COULD BE RATHER LARGE AND MOST PEOPLE DON'T APPRECIATE MULTI-MEGABYTE MAILING LIST MESSAGES. 4.3 Guidelines for Linux device driver writers See the file Documentation/pm.txt for information on the calls you'll want to add. These calls work with either APM or ACPI. Briefly, 1) Register each instance of a device with "pm_register" 2) Call "pm_access" before accessing the hardware. (this will ensure that the hardware is awake and ready) 3) Your "pm_callback" is called before going into a suspend state (ACPI D1-D3) or after resuming (ACPI D0) from a suspend. 4) Call "pm_dev_idle" when the device is not being used (optional but will improve device idle detection) 5) When unloaded, unregister the device with "pm_unregister" 6.1 Credits Much of this information was obtained by scouring through the ACPI mailing list. Andy Henroid's postings in particular were invaluable. Pieces of this document were taken from the pm.txt file included with the driver; this too is Andy's work. Information on bug reports came from the documentation provided with the acpid package, also by Andy. Bug reports by Michael Johnson helped me understand the driver better. Finally, I shamelessly stole the framework for this document from David Hinds' PCMCIA-HOWTO since I had been looking at it earlier in the evening before starting to write the first draft. 6.2 GNU Free Documentation License GNU Free Documentation License Version 1.1, March 2000 Copyright (C) 2000 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 0. PREAMBLE The purpose of this License is to make a manual, textbook, or other written document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. 1. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque". Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only. The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. 2. VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. 3. COPYING IN QUANTITY If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five). C. State on the Title page the name of the publisher of the Modified Version, as the publisher. D. Preserve all the copyright notices of the Document. E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. H. Include an unaltered copy of this License. I. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. K. In any section entitled "Acknowledgements" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. M. Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version. N. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section. If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. 5. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgements", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements." 6. COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. 7. AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate. 8. TRANSLATION Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail. 9. TERMINATION You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 10. FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http:///www.gnu.org/copyleft/. Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. ADDENDUM: How to use this License for your documents To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page: Copyright (c) YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled "GNU Free Documentation License". If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being LIST"; likewise for Back-Cover Texts. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.