Date: Tue, 15 Apr 2014 16:12:59 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> 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 Message-ID: <201404151612.s3FGCxnE013598@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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</screen> This usually fixes the problem of a system powering up spontaneously after a suspend or poweroff.</para> </sect3> - </sect2> - - <sect2 xml:id="ACPI-aslanddump"> - <title><acronym>ASL</acronym>, &man.acpidump.8;, and - <acronym>IASL</acronym></title> + + <sect3 xml:id="ACPI-aslanddump"> + <title>BIOS Contains Buggy Bytecode</title> <indexterm> <primary><acronym>ACPI</acronym></primary> @@ -3203,39 +3201,30 @@ hw.acpi.s4bios: 0</screen> <para>Often, these problems may be resolved by updating the <acronym>BIOS</acronym> 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 - <acronym>AML</acronym>, is compiled from a source language - called <acronym>ASL</acronym>. The <acronym>AML</acronym> is - found in the table known as the <acronym>DSDT</acronym>. To - get a copy of the system's <acronym>ASL</acronym>, use - &man.acpidump.8;. Include both <option>-t</option>, to show - the contents of the fixed tables, and <option>-d</option>, to - disassemble the <acronym>AML</acronym>. Refer to <xref - linkend="ACPI-submitdebug"/> for an example syntax.</para> - - <para>The simplest first check is to recompile the - <acronym>ASL</acronym> to check for errors. Warnings can - usually be ignored, but errors are bugs that will usually - prevent <acronym>ACPI</acronym> from working correctly. To - recompile the <acronym>ASL</acronym>, issue the following - command:</para> - - <screen>&prompt.root; <userinput>iasl your.asl</userinput></screen> + place to start looking for problems.</para> + </sect3> </sect2> - <sect2 xml:id="ACPI-fixasl"> - <title>Fixing the <acronym>ASL</acronym></title> + <sect2> + <title>Overriding the Default <acronym>AML</acronym></title> - <indexterm> + <para>The <acronym>BIOS</acronym> bytecode, known as + <acronym>ACPI</acronym> Machine Language + (<acronym>AML</acronym>), is compiled from a source language + called <acronym>ACPI</acronym> Source Language + (<acronym>ASL</acronym>). The <acronym>AML</acronym> is + found in the table known as the Differentiated System + Description Table (<acronym>DSDT</acronym>).</para> + <indexterm> <primary><acronym>ACPI</acronym></primary> <secondary><acronym>ASL</acronym></secondary> </indexterm> <para>The goal of &os; is for everyone to have working - <acronym>ACPI</acronym> without any user intervention. At - this point, workarounds are still being developed for common + <acronym>ACPI</acronym> without any user intervention. + Workarounds are still being developed for common mistakes made by <acronym>BIOS</acronym> vendors. The µsoft; interpreter (<filename>acpi.sys</filename> and <filename>acpiec.sys</filename>) does not strictly check for @@ -3245,60 +3234,40 @@ hw.acpi.s4bios: 0</screen> <acronym>ASL</acronym>. &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 <acronym>ASL</acronym>. - As a workaround, and to help identify behavior, fix the - <acronym>ASL</acronym> manually. If this works, send a - &man.diff.1; of the old and new <acronym>ASL</acronym> so - developers can possibly work around the buggy behavior in - <acronym>ACPI-CA</acronym>.</para> + work without forcing users to fix the <acronym>ASL</acronym>.</para> - <indexterm> - <primary><acronym>ACPI</acronym></primary> - <secondary>error messages</secondary> - </indexterm> - - <para>Here is a list of common error messages, their cause, and - how to fix them:</para> + <para>To help identify buggy behavior and possibly fix it manually, a copy can be + made of the system's + <acronym>ASL</acronym>. To copy the system's + <acronym>ASL</acronym> to a specified file name, use + <command>acpidump</command> with <option>-t</option>, to show + the contents of the fixed tables, and <option>-d</option>, to + disassemble the <acronym>AML</acronym>:</para> - <sect3> - <title>Operating System Dependencies</title> + <screen>&prompt.root; <userinput>acpidump -td > <replaceable>my.asl</replaceable></userinput></screen> <para>Some <acronym>AML</acronym> versions assume the user is running &windows;. To override this, set <literal>hw.acpi.osname=<replaceable>"Windows - 2001"</replaceable></literal> in - <filename>/boot/loader.conf</filename>, using the strings - in the <acronym>ASL</acronym>.</para> - </sect3> - - <sect3> - <title>Missing Return Statements</title> - - <para>Some methods do not explicitly return a value as the - standard requires. While <acronym>ACPI-CA</acronym> - 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 - <acronym>ASL</acronym>, use the <option>-f</option> - flag.</para> - </sect3> - - <sect3> - <title>Overriding the Default <acronym>AML</acronym></title> - - <para>After customizing <filename>your.asl</filename>, compile - it with this command:</para> + 2009"</replaceable></literal> in + <filename>/boot/loader.conf</filename>, using the most recent &windows; + version listed in the <acronym>ASL</acronym>.</para> + + <para>Other workarounds may require + <filename>my.asl</filename> to be customized. If this file is edited, compile the new + <acronym>ASL</acronym> using the following command. Warnings can + usually be ignored, but errors are bugs that will usually + prevent <acronym>ACPI</acronym> from working correctly.</para> - <screen>&prompt.root; <userinput>iasl your.asl</userinput></screen> + <screen>&prompt.root; <userinput>iasl -f <replaceable>my.asl</replaceable></userinput></screen> - <para>Adding the <option>-f</option> flag forces creation of + <para>Including <option>-f</option> forces creation of the <acronym>AML</acronym>, 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.</para> - <para>The default output filename for &man.iasl.8; is + <para>The default output filename for <command>iasl</command> is <filename>DSDT.aml</filename>. Load this file instead of the <acronym>BIOS</acronym>'s buggy copy, which is still present in flash memory, by editing @@ -3308,13 +3277,44 @@ hw.acpi.s4bios: 0</screen> acpi_dsdt_name="/boot/DSDT.aml"</programlisting> <para>Be sure to copy <filename>DSDT.aml</filename> to - <filename>/boot</filename>.</para> - </sect3> + <filename>/boot</filename>, then reboot the system. If this fixes the problem, send a + &man.diff.1; of the old and new <acronym>ASL</acronym> to + &a.acpi.name; so that + developers can work around the buggy behavior in + <filename>acpica</filename>.</para> </sect2> - <sect2 xml:id="ACPI-debugoutput"> - <title>Getting Debugging Output from - <acronym>ACPI</acronym></title> + <sect2 xml:id="ACPI-submitdebug"> + <info> + <title>Getting and Submitting Debugging Info</title> + + <authorgroup> + <author> + <personname> + <firstname>Nate</firstname> + <surname>Lawson</surname> + </personname> + <contrib>Written by </contrib> + </author> + </authorgroup> + + <authorgroup> + <author> + <personname> + <firstname>Peter</firstname> + <surname>Schultz</surname> + </personname> + <contrib>With contributions from </contrib> + </author> + + <author> + <personname> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + </personname> + </author> + </authorgroup> + </info> <indexterm> <primary>ACPI</primary> @@ -3329,13 +3329,14 @@ acpi_dsdt_name="/boot/DSDT.aml"</program <para>The <acronym>ACPI</acronym> 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 <quote>layers</quote> and are broken down into - <acronym>ACPI-CA</acronym> components (ACPI_ALL_COMPONENTS) + specified as layers and are broken down into + components (<literal>ACPI_ALL_COMPONENTS</literal>) and <acronym>ACPI</acronym> hardware support - (ACPI_ALL_DRIVERS). The verbosity of debugging output is - specified as the <quote>level</quote> and ranges from - ACPI_LV_ERROR (just report errors) to ACPI_LV_VERBOSE - (everything). The <quote>level</quote> is a bitmask so + (<literal>ACPI_ALL_DRIVERS</literal>). The verbosity of debugging output is + specified as the level and ranges from just report errors + (<literal>ACPI_LV_ERROR</literal>) to everything + (<literal>ACPI_LV_VERBOSE</literal>). + 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"</program &man.acpi.4;.</para> <para>Debugging output is not enabled by default. To enable it, - add <literal>options ACPI_DEBUG</literal> to the kernel + add <literal>options ACPI_DEBUG</literal> to the custom kernel configuration file if <acronym>ACPI</acronym> is compiled into the kernel. Add <literal>ACPI_DEBUG=1</literal> to <filename>/etc/make.conf</filename> 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 <filename>acpi.ko</filename> module as follows:</para> - <screen>&prompt.root; <userinput>cd /sys/modules/acpi/acpi -&& make clean && -make ACPI_DEBUG=1</userinput></screen> + <screen>&prompt.root; <userinput>cd /sys/modules/acpi/acpi && make clean && make ACPI_DEBUG=1</userinput></screen> - <para>Install <filename>acpi.ko</filename> in + <para>Copy the compiled <filename>acpi.ko</filename> to <filename>/boot/kernel</filename> and add the desired level - and layer to <filename>/boot/loader.conf</filename>. This - example enables debug messages for all - <acronym>ACPI-CA</acronym> components and all - <acronym>ACPI</acronym> hardware drivers such as - (<acronym>CPU</acronym> and <acronym>LID</acronym>. It only - outputs error messages at the least verbose level.</para> + and layer to <filename>/boot/loader.conf</filename>. The entries in this + example enable debug messages for all <acronym>ACPI</acronym> + components and + hardware drivers and + output error messages at the least verbose level:</para> <programlisting>debug.acpi.layer="ACPI_ALL_COMPONENTS ACPI_ALL_DRIVERS" debug.acpi.level="ACPI_LV_ERROR"</programlisting> <para>If the required information is triggered by a specific - event, such as a suspend and then resume, leave out changes to - <filename>/boot/loader.conf</filename> 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 + <filename>/boot/loader.conf</filename>. Instead, use + <command>sysctl</command> 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 <command>sysctl</command> are named the same as the tunables in <filename>/boot/loader.conf</filename>.</para> - </sect2> - - <sect2 xml:id="ACPI-References"> - <title>References</title> - - <para>More information about <acronym>ACPI</acronym> may be - found in the following locations:</para> - - <itemizedlist> - <listitem> - <para>The &a.acpi;</para> - </listitem> - - <listitem> - <para>The <acronym>ACPI</acronym> Mailing List Archives <uri - xlink:href="http://lists.freebsd.org/pipermail/freebsd-acpi/">http://lists.freebsd.org/pipermail/freebsd-acpi/</uri></para>; - </listitem> - - <listitem> - <para>The old <acronym>ACPI</acronym> Mailing List Archives - <uri - xlink:href="http://home.jp.FreeBSD.org/mail-list/acpi-jp/">http://home.jp.FreeBSD.org/mail-list/acpi-jp/</uri></para>; - </listitem> - - <listitem> - <para>The <acronym>ACPI</acronym> 2.0 Specification <uri - xlink:href="http://acpi.info/spec.htm">http://acpi.info/spec.htm</uri></para>; - </listitem> - - <listitem> - <para>&man.acpi.4;, &man.acpi.thermal.4;, &man.acpidump.8;, - &man.iasl.8;, and &man.acpidb.8;</para> - </listitem> - - <listitem> - <para><link - xlink:href="http://www.cpqlinux.com/acpi-howto.html#fix_broken_dsdt"><acronym>DSDT</acronym>; - debugging resource</link>.</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2 xml:id="ACPI-submitdebug"> - <info> - <title>Debugging &os; <acronym>ACPI</acronym></title> - - <authorgroup> - <author> - <personname> - <firstname>Nate</firstname> - <surname>Lawson</surname> - </personname> - <contrib>Written by </contrib> - </author> - </authorgroup> - - <authorgroup> - <author> - <personname> - <firstname>Peter</firstname> - <surname>Schultz</surname> - </personname> - <contrib>With contributions from </contrib> - </author> - - <author> - <personname> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - </personname> - </author> - </authorgroup> - </info> <indexterm> <primary>ACPI</primary> <secondary>problems</secondary> </indexterm> - <para><acronym>ACPI</acronym> provides a method for - discovering devices, managing power usage, and providing - standardized access to various hardware previously managed by - the <acronym>BIOS</acronym>. Progress is being made toward - <acronym>ACPI</acronym> working on all systems, but bugs in - some motherboards' <acronym>ACPI</acronym> Machine Language - (<acronym>AML</acronym>) bytecode, incompleteness in &os;'s - kernel subsystems, and bugs in the &intel; - <acronym>ACPI-CA</acronym> interpreter continue to - appear.</para> - - <para>This section is intended to help users assist the &os; - <acronym>ACPI</acronym> maintainers in identifying the root - cause of problems and in debugging and developing a - solution.</para> + <para>Once the debugging information is gathered, it can be + sent to &a.acpi.name; so that it can be used by the &os; + <acronym>ACPI</acronym> maintainers to identify the root cause + of the problem and to develop a solution.</para> <note> - <para>Before submitting a problem, ensure the latest + <para>Before submitting debugging information to this mailing list, ensure the latest <acronym>BIOS</acronym> version is installed and, if available, the embedded controller firmware version.</para> </note> - <para>When submitting a problem, send the following information - to <link xlink:href="mailto:freebsd-acpi@FreeBSD.org"> - freebsd-acpi@FreeBSD.org</link>:</para> + <para>When submitting a problem report, include the following + information:</para> <itemizedlist> <listitem> <para>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.</para> </listitem> <listitem> - <para>The output of &man.dmesg.8; after running + <para>The output of <command>dmesg</command> after running <command>boot -v</command>, including any error messages generated by the bug.</para> </listitem> <listitem> - <para>The &man.dmesg.8; output from <command>boot + <para>The <command>dmesg</command> output from <command>boot -v</command> with <acronym>ACPI</acronym> disabled, - if disabling it helps to fix the problem.</para> + if disabling <acronym>ACPI</acronym> helps to fix the problem.</para> </listitem> <listitem> @@ -3506,8 +3419,8 @@ debug.acpi.level="ACPI_LV_ERROR"</progra <listitem> <para>The <acronym>URL</acronym> to a pasted version of the - <firstterm><acronym>ACPI</acronym> Source - Language</firstterm> (<acronym>ASL</acronym>). Do + system's + <acronym>ASL</acronym>. Do <emphasis>not</emphasis> send the <acronym>ASL</acronym> directly to the list as it can be very large. Generate a copy of the <acronym>ASL</acronym> by running this @@ -3522,7 +3435,7 @@ debug.acpi.level="ACPI_LV_ERROR"</progra </listitem> </itemizedlist> - <para>Most &os; developers watch &a.current;, but one should + <para>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 <acronym>PR</acronym> using @@ -3532,5 +3445,29 @@ debug.acpi.level="ACPI_LV_ERROR"</progra <acronym>PR</acronym> without emailing &a.acpi.name; first as it is likely that the problem has been reported before.</para> </sect2> + + <sect2 xml:id="ACPI-References"> + <title>References</title> + + <para>More information about <acronym>ACPI</acronym> may be + found in the following locations:</para> + + <itemizedlist> + <listitem> + <para>The &os; <acronym>ACPI</acronym> Mailing List Archives (<uri + xlink:href="http://lists.freebsd.org/pipermail/freebsd-acpi/">http://lists.freebsd.org/pipermail/freebsd-acpi/</uri>)</para>; + </listitem> + + <listitem> + <para>The <acronym>ACPI</acronym> 2.0 Specification (<uri + xlink:href="http://acpi.info/spec.htm">http://acpi.info/spec.htm</uri>)</para>; + </listitem> + + <listitem> + <para>&man.acpi.4;, &man.acpi.thermal.4;, &man.acpidump.8;, + &man.iasl.8;, and &man.acpidb.8;</para> + </listitem> + </itemizedlist> + </sect2> </sect1> </chapter>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201404151612.s3FGCxnE013598>