[patch] Add some ACPI debugging advice to the Handbook

[Alexey Dokuchaev]

On Tue, Jul 27, 2010 at 05:36:32PM +0000, Alexey Dokuchaev wrote:
> On Tue, Jul 27, 2010 at 12:15:06PM -0400, Jung-uk Kim wrote:
> > The simplest thing to try is:
> > 
> > 	sysctl debug.bootverbose=1
> > 	sysctl debug.acpi.suspend_bounce=1
> > 	acpiconf -s 3
> > 
> > This test emulates suspend/resume cycle of all device drivers without 
> > actually going into S3 state.  In some cases, you can easily catch 
> > problems with this method (e.g., losing firmware state, device 
> > watchdog time out, and retrying forever).  Note that the system does 
> > not really enter S3 state, which means devices may not lose power at 
> > all.  It also means some devices will just work fine even if 
> > suspend/resume methods are totally missing unlike real S3 state.
> 
> This is really nice piece of advice.  Is any one interested (maybe even
> the author) in converting it do docbook format and adding to acpi-debug
> handbook chapter?  I can do it if no one else steps before me.

Could you please review attached diff, and I would appreciate if someone
on the doc@ team can correct my markup (I haven't done documentation
for a while) and commit it to HB?  I can sumbmit PR is that's preferred.

Thanks.

./danfe
-------------- next part --------------
Index: chapter.sgml
===================================================================
RCS file: /home/danfe/fbsd/FreeBSD-CVS/doc/en_US.ISO8859-1/books/handbook/config/chapter.sgml,v
retrieving revision 1.239
diff -u -r1.239 chapter.sgml
--- chapter.sgml	25 Oct 2009 21:21:54 -0000	1.239
+++ chapter.sgml	28 Jul 2010 15:33:16 -0000
@@ -2807,6 +2807,32 @@
 	  do not expect the problem to be resolved since there are a lot
 	  of drivers/hardware that need more testing and work.</para>
 
+	<para>One of the biggest problems with suspend/resume is that too
+	  many drivers exist that do not save, restore, or reinitialize
+	  their firmware, registers, or device memory properly.  To make
+	  these kind of problems easier to debug, the simplest thing to try
+	  is:</para>
+
+	<screen>&prompt.root; <userinput>sysctl
+	    debug.bootverbose=1</userinput>
+	  &prompt.root; <userinput>sysctl
+	    debug.acpi.suspend_bounce=1</userinput>
+	  &prompt.root; <userinput>acpiconf -s 3</userinput></screen>
+
+	<para>This test emulates suspend/resume cycle of all device drivers
+	  without actually going into <literal>S3</literal> state.  In some
+	  cases, you can easily catch problems with this method (e.g.,
+	  losing firmware state, device watchdog time out, and retrying
+	  forever).  Note that the system will not really enter
+	  <literal>S3</literal> state, which means devices may not lose
+	  power at all.  It also means some devices will just work fine
+	  even if suspend/resume methods are totally missing unlike real
+	  <literal>S3</literal> state.</para>
+
+	<para>Harder cases require additional hardware, i.e., serial
+	  port/cable for serial console or Firewire port/cable for
+	  &man.dcons.4;, and usual kernel debugging skills.</para>
+
 	<para>To help isolate the problem, remove as many drivers from
 	  your kernel as possible.  If it works, you can narrow down
 	  which driver is the problem by loading drivers until it fails