diff --git a/en_US.ISO8859-1/books/handbook/config/chapter.sgml b/en_US.ISO8859-1/books/handbook/config/chapter.sgml index 0b00f43ce7..cb0a02487d 100644 --- a/en_US.ISO8859-1/books/handbook/config/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/config/chapter.sgml @@ -2251,7 +2251,7 @@ device_probe_and_attach: cbb0 attach returned 12 BIOS did not have enough room to implement a sophisticated power policy, or one that can adapt very well to the purpose of the machine. - + Plug and Play BIOS (PNPBIOS) was unreliable in many situations. PNPBIOS is 16-bit technology, so the OS has to use 16-bit emulation in order to @@ -2293,36 +2293,518 @@ device_probe_and_attach: cbb0 attach returned 12 The other options are available. Check out the &man.acpiconf.8; manual page for more information. + - - Debugging and Disabling <acronym>ACPI</acronym> + + + + + Nate + Lawson + Written by + + + + + Peter + Schultz + With contributions from + + + + + Tom + Rhodes + And + + + - Almost everything in ACPI is transparent, until - it does not work. That is usually when you as a user will know there - is something not working properly. The &man.acpi.4; driver - supports many debugging options, it is even possible to - selectively disable some parts of the ACPI - system. For more information about debugging facilities, read - the &man.acpi.4; manual page. + Using and Debugging &os; <acronym>ACPI</acronym> - Sometimes for various reasons, the - acpi.ko module must be unloaded. This - can only be done at boot time by the &man.loader.8;. You can - type at &man.loader.8; prompt the command - unset acpi_load each time you boot the - system, or to stop the autoloading of the - &man.acpi.4; driver add the following line to the - /boot/loader.conf file: + 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' AML bytecode, incompleteness in + &os;'s kernel subsystems, and bugs in the Intel + ACPI-CA interpreter continue to appear. - exec="unset acpi_load" + This document is intended to help you assist the &os; + ACPI maintainers in identifying the culprit + of problems you observe and debugging and developing a solution. + Thanks for reading this and we hope we can solve your system's + problems. - &os; 5.1-RELEASE and later come with a boot-time menu - that controls how &os; is booted. One of the proposed options - is to turn off ACPI. So to disable - ACPI just select - 2. Boot &os; with ACPI disabled - in the menu. + + Submitting Debugging Information + For those of you that want to submit a problem right away, + please send the following information to + + acpi-jp@jp.freebsd.org + + + + 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 + occuring if it is new for you. + + + + The dmesg output after boot + , including any error messages + generated by you exercising the bug. + + + + dmesg output from boot + with ACPI + disabled, if disabling it helps fix the problem. + + + + Output from sysctl hw.acpi. This is also + a good way of figuring out what features your system + offers. + + + + URL where your 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: + + &prompt.root; acpidump -t -d > $NAME-$SYSTEM.asl + + (Substitute your login name for + $NAME and manufacturer/model for + $SYSTEM. Example: + njl-FooCo6000.asl) + + + + Most of the developers watch the freebsd-current mailing + list but please submit problems to acpi-jp to be sure it is + seen. Please be patient, all of us have full-time jobs + elsewhere. If your bug is not immediately apparent, we will + probably ask you to submit a PR via + &man.send-pr.1;. When entering a PR, please + include the same information as requested above. This will help + us track the problem and resolve it. Do not send a + PR without emailing acpi-jp first as we use + PRs as reminders of existing problems, not a + reporting mechanism. + + + + Background + + 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 a lot of cooling and battery management support as well. + Laptops also have suspend and resume, with their own associated + complexity. + + An ACPIM-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 DSDT) is provided that specifies a + tree-like name space of devices and methods. + + 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 &os;, Intel has + provided an interpreter (ACPI-CA) that is + shared with Linux and NetBSD. The path to + ACPI-CA is + src/sys/contrib/dev/acpica. The glue code + that allows ACPI-CA to work on &os; is in + src/sys/dev/acpica/Osd. Finally, drivers + that implement various ACPI devices are found + in + src/sys/dev/acpica. + + + + Common Problems + + 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. + + + Suspend/Resume + + 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. S4BIOS is a + BIOS-assisted suspend to disk. + S4OS is implemented + entirely by the operating system. + + Start by checking sysctl + for the suspend-related items. Here + are the results for my Thinkpad: + + hw.acpi.supported_sleep_state: S3 S4 S5 + hw.acpi.s4bios: 0 + + This means that I can use acpiconf + to test S3, + S4OS, and + S5. If was one + (1), I would have S4BIOS + instead of S4OS. + + 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 acpi-jp list but + do not expect the problem to be resolved since there are a lot + of drivers/hardware that need more testing and work. + + 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 to zero (0) if + your display is messed up after resume. Try setting longer or + shorter values for to see + if that helps. + + 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 &os; 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 freebsd-current list and mailed to the driver + maintainer. If you are feeling adventurous, go ahead and + start putting some debugging &man.printf.3;s in a problematic + driver to track down where in its resume function it + hangs. + + 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. + + + + System Hangs (temporary or permanent) + + 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 + SCI. There are several patches and ad-hoc + workarounds that may help. + + Interrupt storms can be distinguished from lost interrupts + by checking the output of vmstat + 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 + ALTESC on + console) and type show interrupts. Patches + to try if you get an interrupt storm are: + + + + Panics + + 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 + and setting up a serial console + or setting up a &man.dump.8; partition. You can get a + backtrace in DDB with + . 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. + + 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 . See the + &man.acpi.4; manual page for some examples. + + + + Other Problems + + 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. + + + + + <acronym>ASL</acronym>, <command>acpidump</command>, and + <acronym>IASL</acronym> + + The most common problem is the BIOS + vendors providing incorrect (or outright buggy!) bytecode. This + is usually manifested by kernel console messages like + this: + + ACPI-1287: *** Error: Method execution failed + [\\_SB_.PCI0.LPC0.FIGD._STA] (Node 0xc3f6d160), AE_NOT_FOUND + + 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 &man.acpidump.8;. You should use + both the (show contents of the fixed tables) + and (disassemble AML to + ASL) options. See the + Submitting Debugging + Information section for an example syntax. + + 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: + + &prompt.root; iasl your.asl + + + + Fixing Your <acronym>ASL</acronym> + + 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 &os; 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 &man.diff.1; of the old and new + ASL so we can possibly work around the buggy + behavior in ACPI-CA and thus make your fix + unnecessary. + + Here is a list of common error messages, their cause, and + how to fix them: + + + _OS dependencies + + Some AML assumes the world consists of + various Windows versions. You can tell &os; to claim it is + any OS to see if this fixes problems you + may have. An easy way to override this is to set + =Windows 2001 + in /boot/loader.conf or other similar + strings you find in the ASL. You could + also manually change references to _OS or + _OS_ (they are the same thing) to check for + &os;. For example: + + If (MCTH (\_OS, "Microsoft Windows NT")) +{ + Return (PIC1) +} +Else +{ + Return (PIC0) +} + + Modified to look for &os;: + + If (MCTH (\_OS, "FreeBSD")) +{ + Return (PIC1) +} +Else +{ + Return (PIC0) +} + + + Missing Return statements + + Explaination of these things. + + + + Overriding the Default <acronym>AML</acronym> + + After you customize your.asl, it + will need rebuilt, run: + + &prompt.root; iasl your.asl + + You can add the 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. + + 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: + + acpi_dsdt_load="YES" +acpi_dsdt_name="/boot/DSDT.aml" + + Be sure to copy your DSDT.aml to the + /boot directory. + + + + Getting Debugging Output From + <acronym>ACPI</acronym> + + The ACPI driver has a very flexible + debuging 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). 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. A full list of the + individual layers and levels is found in the &man.acpi.4; manual + page. + + Debugging output is not enabled by default. To enable it, + add to your kernel config + if ACPI is compiled into the kernel. You can + add to your + /etc/make.conf to enable it globally. If + it is a module, you can recompile just your + acpi.ko module as follows: + + &prompt.root; cd /sys/modules/acpi/acpi + && make clean && make + ACPI_DEBUG=1 + + 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. + + debug.acpi.layer="ACPI_ALL_COMPONENTS ACPI_ALL_DRIVERS" +debug.acpi.level="ACPI_LV_ERROR" + + 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 + sysctls are named the same as the tunables + in loader.conf. + + + + References + + More information about ACPI may be found + in the following locations: + + + + The ACPI Mailing List + + acpi-jp@jp.freebsd.org + + + + The ACPI Mailing List Archives + + http://home.jp.freebsd.org/mail-list/acpi-jp/ + + + + The ACPI 2.0 Specification + + http://acpi.info/spec.htm/ + + + + &os; Manual pages: &man.acpi.4;, + &man.acpi.thermal.4;, &man.acpidump.8;, &man.iasl.8;, + &man.acpidb.8; + + + + + DSDT debugging resource. + (Uses Compaq as an example but useful.) + +