From 627207c403d65ab09670a271b11447944fd51c00 Mon Sep 17 00:00:00 2001 From: Dru Lavigne Date: Tue, 15 Apr 2014 16:12:59 +0000 Subject: [PATCH] Finish editorial review of ACPI chapter. Some shuffling of ASL/AML stuff to improve flow. Remove Japanese and Russian references. These resources could stay in their respective translations. Sponsored by: iXsystems --- .../books/handbook/config/chapter.xml | 341 +++++++----------- 1 file changed, 139 insertions(+), 202 deletions(-) diff --git a/en_US.ISO8859-1/books/handbook/config/chapter.xml b/en_US.ISO8859-1/books/handbook/config/chapter.xml index fb65f35aa7..c57374c5a8 100644 --- a/en_US.ISO8859-1/books/handbook/config/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/config/chapter.xml @@ -3183,11 +3183,9 @@ hw.acpi.s4bios: 0 This usually fixes the problem of a system powering up spontaneously after a suspend or poweroff. - - - - <acronym>ASL</acronym>, &man.acpidump.8;, and - <acronym>IASL</acronym> + + + BIOS Contains Buggy Bytecode ACPI @@ -3203,39 +3201,30 @@ hw.acpi.s4bios: 0 Often, these problems may be resolved by updating the BIOS to the latest revision. Most console - messages are harmless, but if there are other problems like + messages are harmless, but if there are other problems, like the battery status is not working, these messages are a good - place to start looking for problems. 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 the system's ASL, use - &man.acpidump.8;. Include both , to show - the contents of the fixed tables, and , to - disassemble the AML. Refer to for an example syntax. - - The simplest first check is to recompile the - ASL to check for errors. Warnings can - usually be ignored, but errors are bugs that will usually - prevent ACPI from working correctly. To - recompile the ASL, issue the following - command: - - &prompt.root; iasl your.asl + place to start looking for problems. + - - Fixing the <acronym>ASL</acronym> + + Overriding the Default <acronym>AML</acronym> - + The BIOS bytecode, known as + ACPI Machine Language + (AML), is compiled from a source language + called ACPI Source Language + (ASL). The AML is + found in the table known as the Differentiated System + Description Table (DSDT). + ACPI ASL The goal of &os; is for everyone to have working - ACPI without any user intervention. At - this point, workarounds are still being developed for common + ACPI without any user intervention. + Workarounds are still being developed for common mistakes made by BIOS vendors. The µsoft; interpreter (acpi.sys and acpiec.sys) does not strictly check for @@ -3245,60 +3234,40 @@ hw.acpi.s4bios: 0 ASL. &os; developers continue to identify and document which non-standard behavior is allowed by µsoft;'s interpreter and replicate it so that &os; can - work without forcing users to fix the ASL. - As a workaround, and to help identify behavior, fix the - ASL manually. If this works, send a - &man.diff.1; of the old and new ASL so - developers can possibly work around the buggy behavior in - ACPI-CA. + work without forcing users to fix the ASL. - - ACPI - error messages - + To help identify buggy behavior and possibly fix it manually, a copy can be + made of the system's + ASL. To copy the system's + ASL to a specified file name, use + acpidump with , to show + the contents of the fixed tables, and , to + disassemble the AML: - Here is a list of common error messages, their cause, and - how to fix them: - - - Operating System Dependencies + &prompt.root; acpidump -td > my.asl Some AML versions assume the user is running &windows;. To override this, set hw.acpi.osname="Windows - 2001" in - /boot/loader.conf, using the strings - in the ASL. - + 2009" in + /boot/loader.conf, using the most recent &windows; + version listed in the ASL. - - Missing Return Statements + Other workarounds may require + my.asl to be customized. If this file is edited, compile the new + ASL using the following command. Warnings can + usually be ignored, but errors are bugs that will usually + prevent ACPI from working correctly. - Some methods do not explicitly return a value as the - standard requires. While ACPI-CA - does not handle this, &os; has a workaround that allows it - to return the value implicitly. Explicit return statements - can be added where required if the value which should be - returned is known. To force &man.iasl.8; to compile the - ASL, use the - flag. - + &prompt.root; iasl -f my.asl - - Overriding the Default <acronym>AML</acronym> - - After customizing your.asl, compile - it with this command: - - &prompt.root; iasl your.asl - - Adding the flag forces creation of + Including forces creation of the AML, even if there are errors during compilation. Some errors, such as missing return - statements, are automatically worked around by the + statements, are automatically worked around by the &os; interpreter. - The default output filename for &man.iasl.8; is + The default output filename for iasl is DSDT.aml. Load this file instead of the BIOS's buggy copy, which is still present in flash memory, by editing @@ -3308,117 +3277,16 @@ hw.acpi.s4bios: 0 acpi_dsdt_name="/boot/DSDT.aml" Be sure to copy DSDT.aml to - /boot. - - - - - Getting Debugging Output from - <acronym>ACPI</acronym> - - - ACPI - problems - - - - ACPI - debugging - - - The ACPI driver has a flexible - debugging facility. A set of subsystems and the level of - verbosity can be specified. The subsystems 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, a serial console should be used to log the output - so it is not lost as the console message buffer flushes. A - full list of the individual layers and levels is found in - &man.acpi.4;. - - Debugging output is not enabled by default. To enable it, - add options ACPI_DEBUG to the kernel - configuration file if ACPI is compiled into - the kernel. Add ACPI_DEBUG=1 to - /etc/make.conf to enable it globally. - If it is a module, recompile just the - 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 the desired level - and layer to /boot/loader.conf. This - example enables debug messages for all - ACPI-CA components and all - ACPI hardware drivers such as - (CPU and LID. It only - outputs error messages at the least verbose level. - - debug.acpi.layer="ACPI_ALL_COMPONENTS ACPI_ALL_DRIVERS" -debug.acpi.level="ACPI_LV_ERROR" - - If the required information is triggered by a specific - event, such as a suspend and then resume, leave out changes to - /boot/loader.conf and instead use - &man.sysctl.8; to specify the layer and level after booting - and preparing the system for the specific event. The - variables which can be set using &man.sysctl.8; are named - the same as the tunables in - /boot/loader.conf. - - - - References - - More information about ACPI may be - found in the following locations: - - - - The &a.acpi; - - - - The ACPI Mailing List Archives http://lists.freebsd.org/pipermail/freebsd-acpi/ - - - - The old ACPI Mailing List Archives - http://home.jp.FreeBSD.org/mail-list/acpi-jp/ - - - - The ACPI 2.0 Specification http://acpi.info/spec.htm - - - - &man.acpi.4;, &man.acpi.thermal.4;, &man.acpidump.8;, - &man.iasl.8;, and &man.acpidb.8; - - - - DSDT - debugging resource. - - + /boot, then reboot the system. If this fixes the problem, send a + &man.diff.1; of the old and new ASL to + &a.acpi.name; so that + developers can work around the buggy behavior in + acpica. - Debugging &os; <acronym>ACPI</acronym> + Getting and Submitting Debugging Info @@ -3453,50 +3321,95 @@ debug.acpi.level="ACPI_LV_ERROR" problems - ACPI provides a method for - 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 &os;'s - kernel subsystems, and bugs in the &intel; - ACPI-CA interpreter continue to - appear. + + ACPI + debugging + - This section is intended to help users assist the &os; - ACPI maintainers in identifying the root - cause of problems and in debugging and developing a - solution. + The ACPI driver has a flexible + debugging facility. A set of subsystems and the level of + verbosity can be specified. The subsystems to debug are + specified as layers and are broken down into + components (ACPI_ALL_COMPONENTS) + and ACPI hardware support + (ACPI_ALL_DRIVERS). The verbosity of debugging output is + specified as the level and ranges from just report errors + (ACPI_LV_ERROR) to everything + (ACPI_LV_VERBOSE). + The level is a bitmask so + multiple options can be set at once, separated by spaces. In + practice, a serial console should be used to log the output + so it is not lost as the console message buffer flushes. A + full list of the individual layers and levels is found in + &man.acpi.4;. + + Debugging output is not enabled by default. To enable it, + add options ACPI_DEBUG to the custom kernel + configuration file if ACPI is compiled into + the kernel. Add ACPI_DEBUG=1 to + /etc/make.conf to enable it globally. + If a module is used instead of a custom kernel, recompile just the + acpi.ko module as follows: + + &prompt.root; cd /sys/modules/acpi/acpi && make clean && make ACPI_DEBUG=1 + + Copy the compiled acpi.ko to + /boot/kernel and add the desired level + and layer to /boot/loader.conf. The entries in this + example enable debug messages for all ACPI + components and + hardware drivers and + output error messages at the least verbose level: + + debug.acpi.layer="ACPI_ALL_COMPONENTS ACPI_ALL_DRIVERS" +debug.acpi.level="ACPI_LV_ERROR" + + If the required information is triggered by a specific + event, such as a suspend and then resume, do not modify + /boot/loader.conf. Instead, use + sysctl to specify the layer and level after booting + and preparing the system for the specific event. The + variables which can be set using sysctl are named + the same as the tunables in + /boot/loader.conf. + + + ACPI + problems + + + Once the debugging information is gathered, it can be + sent to &a.acpi.name; so that it can be used by the &os; + ACPI maintainers to identify the root cause + of the problem and to develop a solution. - Before submitting a problem, ensure the latest + Before submitting debugging information to this mailing list, ensure the latest BIOS version is installed and, if available, the embedded controller firmware version. - When submitting a problem, send the following information - to - freebsd-acpi@FreeBSD.org: + When submitting a problem report, include the following + information: Description of the buggy behavior, including system - type and model and anything that causes the bug to appear. + type, model, and anything that causes the bug to appear. Note as accurately as possible when the bug began occurring if it is new. - The output of &man.dmesg.8; after running + The output of dmesg after running boot -v, including any error messages generated by the bug. - The &man.dmesg.8; output from boot + The dmesg output from boot -v with ACPI disabled, - if disabling it helps to fix the problem. + if disabling ACPI helps to fix the problem. @@ -3506,8 +3419,8 @@ debug.acpi.level="ACPI_LV_ERROR" The URL to a pasted version of the - ACPI Source - Language (ASL). Do + system's + ASL. Do not send the ASL directly to the list as it can be very large. Generate a copy of the ASL by running this @@ -3522,7 +3435,7 @@ debug.acpi.level="ACPI_LV_ERROR" - Most &os; developers watch &a.current;, but one should + Most &os; developers watch the &a.current;, but one should submit problems to &a.acpi.name; to be sure it is seen. Be patient when waiting for a response. If the bug is not immediately apparent, submit a PR using @@ -3532,5 +3445,29 @@ debug.acpi.level="ACPI_LV_ERROR" PR without emailing &a.acpi.name; first as it is likely that the problem has been reported before. + + + References + + More information about ACPI may be + found in the following locations: + + + + The &os; ACPI Mailing List Archives (http://lists.freebsd.org/pipermail/freebsd-acpi/) + + + + The ACPI 2.0 Specification (http://acpi.info/spec.htm) + + + + &man.acpi.4;, &man.acpi.thermal.4;, &man.acpidump.8;, + &man.iasl.8;, and &man.acpidb.8; + + +