Skip site navigation (1)Skip section navigation (2)
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
 	&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>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
-&amp;&amp; make clean &amp;&amp;
-make ACPI_DEBUG=1</userinput></screen>
+      <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
+      <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>