Date: Mon, 14 Apr 2014 19:48:31 +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: r44556 - head/en_US.ISO8859-1/books/handbook/config Message-ID: <201404141948.s3EJmVDu004769@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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@FreeBSD.org"> - freebsd-acpi@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@FreeBSD.org"> + freebsd-acpi@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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201404141948.s3EJmVDu004769>