docs/handbook/handbook-acpi-debug.mdwn

   1 \r
   2 \r
   3 ## Using and Debugging DragonFly ACPI \r
   4 \r
   5 ***Written by Nate Lawson. With contributions from Peter Schultz and Tom Rhodes. ***\r
   6 \r
   7 ACPI is a fundamentally new way of discovering devices, managing power usage, and providing standardized access to various hardware previously managed by the BIOS. Progress is being made toward ACPI working on all systems, but bugs in some motherboards ***ACPI Machine Language*** (AML) bytecode, incompleteness in DragonFly's kernel subsystems, and bugs in the Intel ACPI-CA interpreter continue to appear.\r
   8 \r
   9 This document is intended to help you assist the DragonFly ACPI maintainers in identifying the root cause of problems you observe and debugging and developing a solution. Thanks for reading this and we hope we can solve your system's problems.\r
  10 \r
  11 ### Submitting Debugging Information \r
  12 \r
  13  **Note:** Before submitting a problem, be sure you are running the latest BIOS version and, if available, embedded controller firmware version.\r
  14 \r
  15 For those of you that want to submit a problem right away, please send the following information to [bugs](http://leaf.dragonflybsd.org/mailarchive/)\r
  16 \r
  17
  18 * Description of the buggy behavior, including system type and model and anything that causes the bug to appear. Also, please note as accurately as possible when the bug began occurring if it is new for you.\r
  19
  20 * The dmesg output after ***boot `-v`***, including any error messages generated by you exercising the bug.\r
  21
  22 * dmesg output from ***boot `-v`*** with ACPI disabled, if disabling it helps fix the problem.\r
  23
  24 * Output from ***sysctl hw.acpi***. This is also a good way of figuring out what features your system offers.\r
  25
  26 * URL where your ***ACPI Source Language*** (ASL) can be found. Do ***not*** send the ASL directly to the list as it can be very large. Generate a copy of your ASL by running this command:\r
  27       \r
  28       # acpidump -t -d > name-system.asl\r
  29   \r
  30   (Substitute your login name for `name` and manufacturer/model for `system`. Example: `njl-FooCo6000.asl`)\r
  31 \r
  32 ### Background \r
  33 \r
  34 ACPI is present in all modern computers that conform to the ia32 (x86), ia64 (Itanium), and amd64 (AMD) architectures. The full standard has many features including CPU performance management, power planes control, thermal zones, various battery systems, embedded controllers, and bus enumeration. Most systems implement less than the full standard. For instance, a desktop system usually only implements the bus enumeration parts while a laptop might have cooling and battery management support as well. Laptops also have suspend and resume, with their own associated complexity.\r
  35 \r
  36 An ACPI-compliant system has various components. The BIOS and chipset vendors provide various fixed tables (e.g., FADT) in memory that specify things like the APIC map (used for SMP), config registers, and simple configuration values. Additionally, a table of bytecode (the ***Differentiated System Description Table*** DSDT) is provided that specifies a tree-like name space of devices and methods.\r
  37 \r
  38 The ACPI driver must parse the fixed tables, implement an interpreter for the bytecode, and modify device drivers and the kernel to accept information from the ACPI subsystem. For DragonFly, Intel has provided an interpreter (ACPI-CA) that is shared with Linux and NetBSD®. The path to the ACPI-CA source code is `src/sys/dev/acpica5`.  Finally, drivers that implement various ACPI devices are found in `src/sys/dev/acpica5`.\r
  39 \r
  40 ### Common Problems \r
  41 \r
  42 For ACPI to work correctly, all the parts have to work correctly. Here are some common problems, in order of frequency of appearance, and some possible workarounds or fixes.\r
  43 \r
  44 #### Suspend/Resume \r
  45 \r
  46 ACPI has three suspend to RAM (STR) states, `S1`-`S3`, and one suspend to disk state (`STD`), called `S4`. `S5` is ***soft off*** and is the normal state your system is in when plugged in but not powered up. `S4` can actually be implemented two separate ways. `S4`BIOS is a BIOS-assisted suspend to disk. `S4`OS is implemented entirely by the operating system.\r
  47 \r
  48 Start by checking `sysctl` `hw.acpi` for the suspend-related items. Here are the results for my Thinkpad:\r
  49 \r
  50     \r
  51     hw.acpi.supported_sleep_state: S3 S4 S5\r
  52 \r
  53 \r
  54     \r
  55     hw.acpi.s4bios: 0\r
  56 \r
  57 \r
  58 This means that I can use `acpiconf -s` to test `S3`, `S4`OS, and `S5`. If `s4bios` was one (`1`), I would have `S4`BIOS support instead of `S4` OS.\r
  59 \r
  60 When testing suspend/resume, start with `S1`, if supported. This state is most likely to work since it doesn't require much driver support. No one has implemented `S2` but if you have it, it's similar to `S1`. The next thing to try is `S3`. This is the deepest STR state and requires a lot of driver support to properly reinitialize your hardware. If you have problems resuming, feel free to email the [bugs](http://leaf.dragonflybsd.org/mailarchive/) list but do not expect the problem to be resolved since there are a lot of drivers/hardware that need more testing and work.\r
  61 \r
  62 To help isolate the problem, remove as many drivers from your kernel as possible. If it works, you can narrow down which driver is the problem by loading drivers until it fails again. Typically binary drivers like `nvidia.ko`,  **X11**  display drivers, and USB will have the most problems while Ethernet interfaces usually work fine. If you can load/unload the drivers ok, you can automate this by putting the appropriate commands in `/etc/rc.suspend` and `/etc/rc.resume`. There is a commented-out example for unloading and loading a driver. Try setting `hw.acpi.reset_video` to zero (0) if your display is messed up after resume. Try setting longer or shorter values for `hw.acpi.sleep_delay` to see if that helps.\r
  63 \r
  64 Another thing to try is load a recent Linux distribution with ACPI support and test their suspend/resume support on the same hardware. If it works on Linux, it's likely a DragonFly driver problem and narrowing down which driver causes the problems will help us fix the problem. Note that the ACPI maintainers do not usually maintain other drivers (e.g sound, ATA, etc.) so any work done on tracking down a driver problem should probably eventually be posted to the [bugs](http://leaf.dragonflybsd.org/mailarchive/) list and mailed to the driver maintainer. If you are feeling adventurous, go ahead and start putting some debugging [printf(3)](http://leaf.dragonflybsd.org/cgi/web-man?command#printf&section3)s in a problematic driver to track down where in its resume function it hangs.\r
  65 \r
  66 Finally, try disabling ACPI and enabling APM instead. If suspend/resume works with APM, you may be better off sticking with APM, especially on older hardware (pre-2000). It took vendors a while to get ACPI support correct and older hardware is more likely to have BIOS problems with ACPI.\r
  67 \r
  68 #### System Hangs (temporary or permanent) \r
  69 \r
  70 Most system hangs are a result of lost interrupts or an interrupt storm. Chipsets have a lot of problems based on how the BIOS configures interrupts before boot, correctness of the APIC (MADT) table, and routing of the ***System Control Interrupt*** (SCI).\r
  71 \r
  72 Interrupt storms can be distinguished from lost interrupts by checking the output of `vmstat -i` and looking at the line that has `acpi0`. If the counter is increasing at more than a couple per second, you have an interrupt storm. If the system appears hung, try breaking to DDB ( **CTRL** + **ALT** + **ESC**  on console) and type `show interrupts`.\r
  73 \r
  74 Your best hope when dealing with interrupt problems is to try disabling APIC support with `hint.apic.0.disabled="1"` in `loader.conf`.\r
  75 \r
  76 #### Panics \r
  77 \r
  78 Panics are relatively rare for ACPI and are the top priority to be fixed. The first step is to isolate the steps to reproduce the panic (if possible) and get a backtrace. Follow the advice for enabling `options DDB` and setting up a serial console (see [ this section](serialconsole-setup.html#SERIALCONSOLE-DDB)) or setting up a [dump(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#dump&section8) partition. You can get a backtrace in DDB with `tr`. If you have to handwrite the backtrace, be sure to at least get the lowest five (5) and top five (5) lines in the trace.\r
  79 \r
  80 Then, try to isolate the problem by booting with ACPI disabled. If that works, you can isolate the ACPI subsystem by using various values of `debug.acpi.disable`. See the [acpi(4)](http://leaf.dragonflybsd.org/cgi/web-man?command#acpi&section4) manual page for some examples.\r
  81 \r
  82 #### System Powers Up After Suspend or Shutdown \r
  83 \r
  84 First, try setting `hw.acpi.disable_on_poweroff#0` in [loader.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?commandloader.conf&section=5). This keeps ACPI from disabling various events during the shutdown process. Some systems need this value set to ***1*** (the default) for the same reason. This usually fixes the problem of a system powering up spontaneously after a suspend or poweroff.\r
  85 \r
  86 #### Other Problems \r
  87 \r
  88 If you have other problems with ACPI (working with a docking station, devices not detected, etc.), please email a description to the mailing list as well; however, some of these issues may be related to unfinished parts of the ACPI subsystem so they might take a while to be implemented. Please be patient and prepared to test patches we may send you.\r
  89 \r
  90 ### ASL, acpidump, and IASL \r
  91 \r
  92 The most common problem is the BIOS vendors providing incorrect (or outright buggy!) bytecode. This is usually manifested by kernel console messages like this:\r
  93 \r
  94     \r
  95     ACPI-1287: *** Error: Method execution failed [\\_SB_.PCI0.LPC0.FIGD._STA] \\\r
  96     (Node 0xc3f6d160), AE_NOT_FOUND\r
  97 \r
  98 \r
  99 Often, you can resolve these problems by updating your BIOS to the latest revision. Most console messages are harmless but if you have other problems like battery status not working, they're a good place to start looking for problems in the AML. The bytecode, known as AML, is compiled from a source language called ASL. The AML is found in the table known as the DSDT. To get a copy of your ASL, use [acpidump(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#acpidump&section8). You should use both the `-t` (show contents of the fixed tables) and `-d` (disassemble AML to ASL) options. See the [submitting Debugging Information](acpi-debug.html#ACPI-SUBMITDEBUG) section for an example syntax.\r
 100 \r
 101 The simplest first check you can do is to recompile your ASL to check for errors. Warnings can usually be ignored but errors are bugs that will usually prevent ACPI from working correctly. To recompile your ASL, issue the following command:\r
 102 \r
 103     \r
 104     # iasl your.asl\r
 105 \r
 106 \r
 107 ### Fixing Your ASL \r
 108 \r
 109 In the long run, our goal is for almost everyone to have ACPI work without any user intervention. At this point, however, we are still developing workarounds for common mistakes made by the BIOS vendors. The Microsoft interpreter (`acpi.sys` and `acpiec.sys`) does not strictly check for adherence to the standard, and thus many BIOS vendors who only test ACPI under Windows never fix their ASL. We hope to continue to identify and document exactly what non-standard behavior is allowed by Microsoft's interpreter and replicate it so DragonFly can work without forcing users to fix the ASL. As a workaround and to help us identify behavior, you can fix the ASL manually. If this works for you, please send a [diff(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#diff&section1) of the old and new ASL so we can possibly work around the buggy behavior in ACPI-CA and thus make your fix unnecessary.\r
 110 \r
 111 Here is a list of common error messages, their cause, and how to fix them:\r
 112 \r
 113 #### OS dependencies \r
 114 \r
 115 Some AML assumes the world consists of various Windows versions. You can tell DragonFly to claim it is any OS to see if this fixes problems you may have. An easy way to override this is to set `hw.acpi.osname=Windows 2001` in `/boot/loader.conf` or other similar strings you find in the ASL.\r
 116 \r
 117 #### Missing Return statements \r
 118 \r
 119 Some methods do not explicitly return a value as the standard requires. While ACPI-CA does not handle this, DragonFly has a workaround that allows it to return the value implicitly. You can also add explicit Return statements where required if you know what value should be returned. To force `iasl` to compile the ASL, use the `-f` flag.\r
 120 \r
 121 #### Overriding the Default AML \r
 122 \r
 123 After you customize `your.asl`, you will want to compile it, run:\r
 124 \r
 125     \r
 126     # iasl your.asl\r
 127 \r
 128 \r
 129 You can add the `-f` flag to force creation of the AML, even if there are errors during compilation. Remember that some errors (e.g., missing Return statements) are automatically worked around by the interpreter.\r
 130 \r
 131 `DSDT.aml` is the default output filename for `iasl`. You can load this instead of your BIOS's buggy copy (which is still present in flash memory) by editing `/boot/loader.conf` as follows:\r
 132 \r
 133     \r
 134     acpi_dsdt_load="YES"\r
 135     acpi_dsdt_name="/boot/DSDT.aml"\r
 136 \r
 137 \r
 138 Be sure to copy your `DSDT.aml` to the `/boot` directory.\r
 139 \r
 140 ### Getting Debugging Output From ACPI \r
 141 \r
 142 The ACPI driver has a very flexible debugging facility. It allows you to specify a set of subsystems as well as the level of verbosity. The subsystems you wish to debug are specified as ***layers*** and are broken down into ACPI-CA components (ACPI_ALL_COMPONENTS) and ACPI hardware support (ACPI_ALL_DRIVERS). The verbosity of debugging output is specified as the ***level*** and ranges from ACPI_LV_ERROR (just report errors) to ACPI_LV_VERBOSE (everything). The ***level*** is a bitmask so multiple options can be set at once, separated by spaces. In practice, you will want to use a serial console to log the output if it is so long it flushes the console message buffer.\r
 143 \r
 144 Debugging output is not enabled by default. To enable it, add `options ACPI_DEBUG` to your kernel config if ACPI is compiled into the kernel. You can add `ACPI_DEBUG=1` to your `/etc/make.conf` to enable it globally. If it is a module, you can recompile just your `acpi.ko` module as follows:\r
 145 \r
 146     \r
 147     # cd /sys/dev/acpica5 && make clean && make ACPI_DEBUG=1\r
 148 \r
 149 \r
 150 Install `acpi.ko` in `/boot/kernel` and add your desired level and layer to `loader.conf`. This example enables debug messages for all ACPI-CA components and all ACPI hardware drivers (CPU, LID, etc.) It will only output error messages, the least verbose level.\r
 151 \r
 152     \r
 153     debug.acpi.layer="ACPI_ALL_COMPONENTS ACPI_ALL_DRIVERS"\r
 154     debug.acpi.level="ACPI_LV_ERROR"\r
 155 \r
 156 \r
 157 If the information you want is triggered by a specific event (say, a suspend and then resume), you can leave out changes to `loader.conf` and instead use `sysctl` to specify the layer and level after booting and preparing your system for the specific event. The `sysctl`s are named the same as the tunables in `loader.conf`.\r
 158 \r
 159 ### References \r
 160 \r
 161 More information about ACPI may be found in the following locations:\r
 162 \r
 163
 164 * The [FreeBSD ACPI mailing list](http://lists.FreeBSD.org/mailman/listinfo/freebsd-acpi) (This is FreeBSD-specific; posting DragonFly questions here may not generate much of an answer.)\r
 165
 166 * The ACPI Mailing List Archives (FreeBSD) http://lists.freebsd.org/pipermail/freebsd-acpi/\r
 167
 168 * The old ACPI Mailing List Archives (FreeBSD) http://home.jp.FreeBSD.org/mail-list/acpi-jp/\r
 169
 170 * The ACPI 2.0 Specification http://acpi.info/spec.htm\r
 171
 172 * DragonFly Manual pages: [acpidump(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#acpidump&section8), [acpiconf(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=acpiconf&section=8), [acpidb(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=acpidb&section=8)\r
 173
 174 * [DSDT debugging resource](http://www.cpqlinux.com/acpi-howto.html#fix_broken_dsdt). (Uses Compaq as an example but generally useful.)\r
 175 \r
 176 \r
 177 \r
 178 CategoryHandbook\r
 179 CategoryHandbook-configuration\r