- Add some ACPI debugging advice

Submitted by:	danfe
Refined by:	bf

en_US.ISO8859-1/books/handbook/config/chapter.sgml

@@ -2807,6 +2807,29 @@ hw.acpi.s4bios: 0</screen>
 	  do not expect the problem to be resolved since there are a lot
 	  of drivers/hardware that need more testing and work.</para>
 
+	<para>A common problem with suspend/resume is that many device
+	  drivers do not save, restore, or reinitialize their firmware,
+	  registers, or device memory properly.  As a first attempt at
+	  debugging the problem, try:</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 may not lose power,
+	  and many will work 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 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