os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Finish editorial review of ACPI chapter.

Browse source 
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
This commit is contained in:
Dru Lavigne 2014-04-15 16:12:59 +00:00
parent 55b51897c7
commit 627207c403
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=44561
1 changed files with 139 additions and 202 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

341
en_US.ISO8859-1/books/handbook/config/chapter.xml
View file

@ -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
&microsoft; 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
&microsoft;'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>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>
<para>Here is a list of common error messages, their cause, and
how to fix them:</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>
2009"</replaceable></literal> in
<filename>/boot/loader.conf</filename>, using the most recent &windows;
version listed in the <acronym>ASL</acronym>.</para>
<sect3>
<title>Missing Return Statements</title>
<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>
<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>
<screen>&prompt.root; <userinput>iasl -f <replaceable>my.asl</replaceable></userinput></screen>
<sect3>
<title>Overriding the Default <acronym>AML</acronym></title>
<para>After customizing <filename>your.asl</filename>, compile
it with this command:</para>
<screen>&prompt.root; <userinput>iasl your.asl</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,117 +3277,16 @@ 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>
</sect2>
<sect2 xml:id="ACPI-debugoutput">
<title>Getting Debugging Output from
<acronym>ACPI</acronym></title>
<indexterm>
<primary>ACPI</primary>
<secondary>problems</secondary>
</indexterm>
<indexterm>
<primary>ACPI</primary>
<secondary>debugging</secondary>
</indexterm>
<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)
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
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;.</para>
<para>Debugging output is not enabled by default. To enable it,
add <literal>options ACPI_DEBUG</literal> to the 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
<filename>acpi.ko</filename> module as follows:</para>
<screen>&prompt.root; <userinput>cd /sys/modules/acpi/acpi
&amp;&amp; make clean &amp;&amp;
make ACPI_DEBUG=1</userinput></screen>
<para>Install <filename>acpi.ko</filename> in
<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>
<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
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
<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>
<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-submitdebug">
<info>
<title>Debugging &os; <acronym>ACPI</acronym></title>
<title>Getting and Submitting Debugging Info</title>
<authorgroup>
<author>
@ -3453,50 +3321,95 @@ debug.acpi.level="ACPI_LV_ERROR"</programlisting>
<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>
<indexterm>
<primary>ACPI</primary>
<secondary>debugging</secondary>
</indexterm>
<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>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 layers and are broken down into
components (<literal>ACPI_ALL_COMPONENTS</literal>)
and <acronym>ACPI</acronym> hardware support
(<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
full list of the individual layers and levels is found in
&man.acpi.4;.</para>
<para>Debugging output is not enabled by default. To enable it,
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 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 &amp;&amp; make clean &amp;&amp; make ACPI_DEBUG=1</userinput></screen>
<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>. 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, 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 <command>sysctl</command> are named
the same as the tunables in
<filename>/boot/loader.conf</filename>.</para>
<indexterm>
<primary>ACPI</primary>
<secondary>problems</secondary>
</indexterm>
<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"</programlisting>
<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"</programlisting>
</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"</programlisting>
<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>