svn commit: r44556 - head/en_US.ISO8859-1/books/handbook/config
Dru Lavigne
dru at FreeBSD.org
Mon Apr 14 19:48:32 UTC 2014
Author: dru
Date: Mon Apr 14 19:48:31 2014
New Revision: 44556
URL: http://svnweb.freebsd.org/changeset/doc/44556
Log:
Editorial review of first 1/2 of ACPI chapter.
Move how to submit a report subsection to after the troubleshooting
sub-section.
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 Mon Apr 14 18:39:12 2014 (r44555)
+++ head/en_US.ISO8859-1/books/handbook/config/chapter.xml Mon Apr 14 19:48:31 2014 (r44556)
@@ -2854,9 +2854,7 @@ kern.maxvnodes: 100000</screen>
specific to the hardware platform. An <acronym>APM</acronym>
driver in the operating system mediates access to the
<acronym>APM</acronym> Software Interface, which allows
- management of power levels. <acronym>APM</acronym> should still
- be used for systems manufactured at or before the year
- 2000.</para>
+ management of power levels.</para>
<para>There are four major problems in <acronym>APM</acronym>.
First, power management is done by the vendor-specific
@@ -2881,15 +2879,15 @@ kern.maxvnodes: 100000</screen>
or one that can adapt well to the purpose of the
machine.</para>
- <para>The <emphasis>Plug and Play <acronym>BIOS</acronym>
- (<acronym>PNPBIOS</acronym>)</emphasis> was unreliable in
+ <para>The Plug and Play <acronym>BIOS</acronym>
+ (<acronym>PNPBIOS</acronym>) was unreliable in
many situations. <acronym>PNPBIOS</acronym> is 16-bit
technology, so the operating system has to use 16-bit
emulation in order to interface with
<acronym>PNPBIOS</acronym> methods. &os; provides an
- <acronym>APM</acronym> driver for backwards compatibility with
- older hardware. The driver is documented in
- &man.apm.4;.</para>
+ <acronym>APM</acronym> driver as <acronym>APM</acronym> should
+ still be used for systems manufactured at or before the year
+ 2000. The driver is documented in &man.apm.4;.</para>
<indexterm>
<primary>ACPI</primary>
@@ -2902,14 +2900,11 @@ kern.maxvnodes: 100000</screen>
<para>The successor to <acronym>APM</acronym> is the Advanced
Configuration and Power Interface (<acronym>ACPI</acronym>).
<acronym>ACPI</acronym> is a standard written by an
- alliance of vendors to provide a standard interface for
+ alliance of vendors to provide an interface for
hardware resources and power management. It is a key
element in <emphasis>Operating System-directed configuration
and Power Management</emphasis> as it provides more control
- and flexibility to the operating system. Modern systems
- stretched the limits of the current Plug and
- Play interfaces prior to the introduction of
- <acronym>ACPI</acronym>..</para>
+ and flexibility to the operating system.</para>
<para>This chapter demonstrates how to configure
<acronym>ACPI</acronym> on &os;. It then offers some tips on
@@ -2921,21 +2916,18 @@ kern.maxvnodes: 100000</screen>
<sect2 xml:id="acpi-config">
<title>Configuring <acronym>ACPI</acronym></title>
- <para>The &man.acpi.4; driver is loaded by default at start
- up by &man.loader.8; and should
- <emphasis>not</emphasis> be compiled into the kernel. The
- reasoning is that modules are easier to work with and do not
- require a kernel rebuild. This has the advantage of making
- testing easier. Another reason is that starting
- <acronym>ACPI</acronym> after a system has been brought up
- often does not work well. If experiencing problems,
- <acronym>ACPI</acronym> can be disabled altogether. This
- driver should not and can not be unloaded because the system
+ <para>In &os; the &man.acpi.4; driver is loaded by default at system
+ boot and should
+ <emphasis>not</emphasis> be compiled into the kernel. This
+ driver can not be unloaded after boot because the system
bus uses it for various hardware interactions.
- <acronym>ACPI</acronym> can be disabled by rebooting after
+ However, if the system is experiencing problems,
+ <acronym>ACPI</acronym> can be disabled altogether
+ by rebooting after
setting <literal>hint.acpi.0.disabled="1"</literal> in
<filename>/boot/loader.conf</filename> or by setting this
- variable at the &man.loader.8; prompt.</para>
+ variable at the loader prompt, as described in <xref
+ linkend="boot-loader"/>.</para>
<note>
<para><acronym>ACPI</acronym> and <acronym>APM</acronym>
@@ -2945,146 +2937,26 @@ kern.maxvnodes: 100000</screen>
</note>
<para><acronym>ACPI</acronym> can be used to put the system into
- a sleep mode with &man.acpiconf.8;, the <option>-s</option>
- flag, and a <literal>1-5</literal> option. Most users
+ a sleep mode with <command>acpiconf</command>, the <option>-s</option>
+ flag, and a number from <literal>1</literal> to <literal>5</literal>. Most users
only need <literal>1</literal> (quick suspend to
<acronym>RAM</acronym>) or <literal>3</literal> (suspend to
<acronym>RAM</acronym>). Option <literal>5</literal> performs
- a soft-off which is the same action as:</para>
+ a soft-off which is the same as running <command>halt -p</command>.</para>
- <screen>&prompt.root; <userinput>halt -p</userinput></screen>
-
- <para>Other options are available via &man.sysctl.8;. Refer to
+ <para>Other options are available using <command>sysctl</command>. Refer to
&man.acpi.4; and &man.acpiconf.8; for more information.</para>
</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> is a fundamentally new way of
- 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' <firstterm><acronym>ACPI</acronym> Machine
- Language</firstterm> (<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>
-
- <note>
- <para>Before submitting a problem, 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>
-
- <itemizedlist>
- <listitem>
- <para>Description of the buggy behavior, including system
- type and 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
- <command>boot -v</command>, including any error messages
- generated by the bug.</para>
- </listitem>
-
- <listitem>
- <para>The &man.dmesg.8; output from <command>boot
- -v</command> with <acronym>ACPI</acronym> disabled,
- if disabling it helps to fix the problem.</para>
- </listitem>
-
- <listitem>
- <para>Output from <command>sysctl hw.acpi</command>. This
- lists which features the system offers.</para>
- </listitem>
-
- <listitem>
- <para>The <acronym>URL</acronym> to a pasted version of the
- <firstterm><acronym>ACPI</acronym> Source
- Language</firstterm> (<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 command:</para>
-
- <screen>&prompt.root; <userinput>acpidump -dt > <replaceable>name</replaceable>-<replaceable>system</replaceable>.asl</userinput></screen>
-
- <para>Substitute the login name for
- <replaceable>name</replaceable> and manufacturer/model for
- <replaceable>system</replaceable>. For example, use
- <filename>njl-FooCo6000.asl</filename>.</para>
- </listitem>
- </itemizedlist>
-
- <para>Most &os; developers watch &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
- &man.send-pr.1;. When entering a <acronym>PR</acronym>,
- include the same information as requested above. This helps
- developers to track the problem and resolve it. Do not send a
- <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-background">
- <title>Background</title>
-
+ <sect2 xml:id="ACPI-comprob">
+ <title>Common Problems</title>
<indexterm>
<primary><acronym>ACPI</acronym></primary>
</indexterm>
<para><acronym>ACPI</acronym> is present in all modern computers
that conform to the ia32 (x86), ia64 (Itanium), and amd64
- (AMD) architectures. The full standard has many features
+ (<acronym>AMD</acronym>) architectures. The full standard has many features
including <acronym>CPU</acronym> performance management, power
planes control, thermal zones, various battery systems,
embedded controllers, and bus enumeration. Most systems
@@ -3100,8 +2972,8 @@ kern.maxvnodes: 100000</screen>
in memory that specify things like the <acronym>APIC</acronym>
map (used for <acronym>SMP</acronym>), config registers, and
simple configuration values. Additionally, a bytecode table,
- the <firstterm>Differentiated System Description
- Table</firstterm> <acronym>DSDT</acronym>, specifies a
+ the Differentiated System Description
+ Table <acronym>DSDT</acronym>, specifies a
tree-like name space of devices and methods.</para>
<para>The <acronym>ACPI</acronym> driver must parse the fixed
@@ -3116,10 +2988,6 @@ kern.maxvnodes: 100000</screen>
in <filename>src/sys/dev/acpica/Osd</filename>. Finally,
drivers that implement various <acronym>ACPI</acronym> devices
are found in <filename>src/sys/dev/acpica</filename>.</para>
- </sect2>
-
- <sect2 xml:id="ACPI-comprob">
- <title>Common Problems</title>
<indexterm>
<primary>ACPI</primary>
@@ -3129,7 +2997,9 @@ kern.maxvnodes: 100000</screen>
<para>For <acronym>ACPI</acronym> to work correctly, all the
parts have to work correctly. Here are some common problems,
in order of frequency of appearance, and some possible
- workarounds or fixes.</para>
+ workarounds or fixes. If a fix does not resolve the issue,
+ refer to <xref linkend="ACPI-submitdebug"/> for instructions
+ on how to submit a bug report.</para>
<sect3>
<title>Mouse Issues</title>
@@ -3137,9 +3007,7 @@ kern.maxvnodes: 100000</screen>
<para>In some cases, resuming from a suspend operation will
cause the mouse to fail. A known work around is to add
<literal>hint.psm.0.flags="0x3000"</literal> to
- <filename>/boot/loader.conf</filename>. If this does not
- work, consider sending a bug report using
- &man.send-pr.1;.</para>
+ <filename>/boot/loader.conf</filename>.</para>
</sect3>
<sect3>
@@ -3148,18 +3016,18 @@ kern.maxvnodes: 100000</screen>
<para><acronym>ACPI</acronym> has three suspend to
<acronym>RAM</acronym> (<acronym>STR</acronym>) states,
<literal>S1</literal>-<literal>S3</literal>, and one suspend
- to disk state (<literal>STD</literal>), called
- <literal>S4</literal>. <literal>S5</literal> is
- <quote>soft off</quote> and is the normal state the system
- is in when plugged in but not powered up.
- <literal>S4</literal> can be implemented in two separate
- ways. <literal>S4</literal><acronym>BIOS</acronym> is a
- <acronym>BIOS</acronym>-assisted suspend to disk.
+ to disk state (<acronym>STD</acronym>), called
+ <literal>S4</literal>. <acronym>STD</acronym> can be implemented in two separate
+ ways. The <literal>S4</literal><acronym>BIOS</acronym> is a
+ <acronym>BIOS</acronym>-assisted suspend to disk and
<literal>S4</literal><acronym>OS</acronym> is implemented
- entirely by the operating system.</para>
+ entirely by the operating system. The normal state the system
+ is in when plugged in but not powered up is
+ <quote>soft off</quote> (<literal>S5</literal>).
+ </para>
- <para>Start by checking <command>sysctl hw.acpi</command>
- for the suspend-related items. Here are the results for a
+ <para>Use <command>sysctl hw.acpi</command> to check
+ for the suspend-related items. These example results are from a
Thinkpad:</para>
<screen>hw.acpi.supported_sleep_state: S3 S4 S5
@@ -3167,11 +3035,11 @@ hw.acpi.s4bios: 0</screen>
<para>Use <command>acpiconf -s</command> to test
<literal>S3</literal>,
- <literal>S4</literal><acronym>OS</acronym>, and
+ <literal>S4</literal>, and
<literal>S5</literal>. An <option>s4bios</option> of one
- (<literal>1</literal>), indicates
+ (<literal>1</literal>) indicates
<literal>S4</literal><acronym>BIOS</acronym> support instead
- of <literal>S4</literal> <acronym>OS</acronym>.</para>
+ of <literal>S4</literal> operating system support.</para>
<para>When testing suspend/resume, start with
<literal>S1</literal>, if supported. This state is most
@@ -3180,11 +3048,7 @@ hw.acpi.s4bios: 0</screen>
which is similar to <literal>S1</literal>. Next, try
<literal>S3</literal>. This is the deepest
<acronym>STR</acronym> state and requires a lot of driver
- support to properly reinitialize the hardware. If there are
- problems resuming, email &a.acpi.name;. However, the
- problem may not be resolved quickly since due to the amount
- of drivers and hardware that need more testing and
- work.</para>
+ support to properly reinitialize the hardware.</para>
<para>A common problem with suspend/resume is that many device
drivers do not save, restore, or reinitialize their
@@ -3210,8 +3074,8 @@ hw.acpi.s4bios: 0</screen>
console, a Firewire port and cable for using &man.dcons.4;,
and kernel debugging skills.</para>
- <para>To help isolate the problem, remove as many drivers
- from the kernel as possible. If it works, narrow down which
+ <para>To help isolate the problem, unload as many drivers
+ as possible. If it works, narrow down which
driver is the problem by loading drivers until it fails
again. Typically, binary drivers like
<filename>nvidia.ko</filename>, display drivers, and
@@ -3257,7 +3121,7 @@ hw.acpi.s4bios: 0</screen>
how the <acronym>BIOS</acronym> configures interrupts before
correctness of the <acronym>APIC</acronym>
(<acronym>MADT</acronym>) table, and routing of the
- <firstterm>System Control Interrupt</firstterm>
+ System Control Interrupt
(<acronym>SCI</acronym>).</para>
<indexterm>
@@ -3297,7 +3161,7 @@ hw.acpi.s4bios: 0</screen>
get a backtrace. Follow the advice for enabling
<literal>options DDB</literal> and setting up a serial
console in <xref linkend="serialconsole-ddb"/> or setting
- up a &man.dump.8; partition. To get a backtrace in
+ up a dump partition. To get a backtrace in
<acronym>DDB</acronym>, use <literal>tr</literal>. When
handwriting the backtrace, get at least the last five
and the top five lines in the trace.</para>
@@ -3314,25 +3178,13 @@ hw.acpi.s4bios: 0</screen>
<para>First, try setting
<literal>hw.acpi.disable_on_poweroff="0"</literal> in
- &man.loader.conf.5;. This keeps <acronym>ACPI</acronym>
+ <filename>/boot/loader</filename>. This keeps <acronym>ACPI</acronym>
from disabling various events during the shutdown process.
Some systems need this value set to <literal>1</literal>
(the default) for the same reason. This usually fixes the
problem of a system powering up spontaneously after a
suspend or poweroff.</para>
</sect3>
-
- <sect3>
- <title>Other Problems</title>
-
- <para>For other problems with <acronym>ACPI</acronym>, such as
- it not working with a docking station or devices not being
- detected, email a description to &a.acpi.name;. Some
- issues may be related to unfinished parts of the
- <acronym>ACPI</acronym> subsystem which might take a while
- to be implemented. Be patient and prepared to test
- patches.</para>
- </sect3>
</sect2>
<sect2 xml:id="ACPI-aslanddump">
@@ -3567,5 +3419,123 @@ debug.acpi.level="ACPI_LV_ERROR"</progra
</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>
+
+ <note>
+ <para>Before submitting a problem, 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>
+
+ <itemizedlist>
+ <listitem>
+ <para>Description of the buggy behavior, including system
+ type and 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
+ <command>boot -v</command>, including any error messages
+ generated by the bug.</para>
+ </listitem>
+
+ <listitem>
+ <para>The &man.dmesg.8; output from <command>boot
+ -v</command> with <acronym>ACPI</acronym> disabled,
+ if disabling it helps to fix the problem.</para>
+ </listitem>
+
+ <listitem>
+ <para>Output from <command>sysctl hw.acpi</command>. This
+ lists which features the system offers.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <acronym>URL</acronym> to a pasted version of the
+ <firstterm><acronym>ACPI</acronym> Source
+ Language</firstterm> (<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 command:</para>
+
+ <screen>&prompt.root; <userinput>acpidump -dt > <replaceable>name</replaceable>-<replaceable>system</replaceable>.asl</userinput></screen>
+
+ <para>Substitute the login name for
+ <replaceable>name</replaceable> and manufacturer/model for
+ <replaceable>system</replaceable>. For example, use
+ <filename>njl-FooCo6000.asl</filename>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Most &os; developers watch &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
+ &man.send-pr.1;. When entering a <acronym>PR</acronym>,
+ include the same information as requested above. This helps
+ developers to track the problem and resolve it. Do not send a
+ <acronym>PR</acronym> without emailing &a.acpi.name; first as
+ it is likely that the problem has been reported before.</para>
+ </sect2>
+
</sect1>
</chapter>
More information about the svn-doc-all
mailing list