From owner-svn-doc-all@FreeBSD.ORG Tue Apr 15 16:12:59 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id A20B21CA; Tue, 15 Apr 2014 16:12:59 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 8CE5E1D0E; Tue, 15 Apr 2014 16:12:59 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s3FGCx0B013599; Tue, 15 Apr 2014 16:12:59 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s3FGCxnE013598; Tue, 15 Apr 2014 16:12:59 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201404151612.s3FGCxnE013598@svn.freebsd.org> From: Dru Lavigne Date: Tue, 15 Apr 2014 16:12:59 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44561 - head/en_US.ISO8859-1/books/handbook/config X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 15 Apr 2014 16:12:59 -0000 Author: dru Date: Tue Apr 15 16:12:59 2014 New Revision: 44561 URL: http://svnweb.freebsd.org/changeset/doc/44561 Log: 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 Modified: head/en_US.ISO8859-1/books/handbook/config/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/config/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/config/chapter.xml Tue Apr 15 12:42:29 2014 (r44560) +++ head/en_US.ISO8859-1/books/handbook/config/chapter.xml Tue Apr 15 16:12:59 2014 (r44561) @@ -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 - - - Here is a list of common error messages, their cause, and - how to fix them: + 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: - - 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. - - - - Missing Return Statements - - 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. - - - - Overriding the Default <acronym>AML</acronym> - - After customizing your.asl, compile - it with this command: + 2009" in + /boot/loader.conf, using the most recent &windows; + version listed in the ASL. + + 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. - &prompt.root; iasl your.asl + &prompt.root; iasl -f my.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,13 +3277,44 @@ hw.acpi.s4bios: 0 acpi_dsdt_name="/boot/DSDT.aml" Be sure to copy DSDT.aml to - /boot. - + /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. - - Getting Debugging Output from - <acronym>ACPI</acronym> + + + Getting and Submitting Debugging Info + + + + + Nate + Lawson + + Written by + + + + + + + Peter + Schultz + + With contributions from + + + + + Tom + Rhodes + + + + ACPI @@ -3329,13 +3329,14 @@ acpi_dsdt_name="/boot/DSDT.aml"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) + 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 - ACPI_LV_ERROR (just report errors) to ACPI_LV_VERBOSE - (everything). The level is a bitmask so + (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 @@ -3343,160 +3344,72 @@ acpi_dsdt_name="/boot/DSDT.aml" Debugging output is not enabled by default. To enable it, - add options ACPI_DEBUG to the kernel + 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 it is a module, recompile just the + 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 + &prompt.root; cd /sys/modules/acpi/acpi && make clean && make ACPI_DEBUG=1 - Install acpi.ko in + Copy the compiled acpi.ko to /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. + 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, leave out changes to - /boot/loader.conf and instead use - &man.sysctl.8; to specify the layer and level after booting + 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 &man.sysctl.8; are named + variables which can be set using sysctl 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. - - - - - - - Debugging &os; <acronym>ACPI</acronym> - - - - - Nate - Lawson - - Written by - - - - - - - Peter - Schultz - - With contributions from - - - - - Tom - Rhodes - - - - ACPI 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. - - 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. + 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; + + +