svn commit: r44561 - head/en_US.ISO8859-1/books/handbook/config
Dru Lavigne
dru at FreeBSD.org
Tue Apr 15 16:12:59 UTC 2014
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 at FreeBSD.org">
- freebsd-acpi at 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>
More information about the svn-doc-all
mailing list