Document the procedure to obtain the debugging information

when the system deadlocks.

Approved by: pjd (mentor)

en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml

@@ -821,6 +821,38 @@ Reading symbols from /sys/modules/linux/linux.ko...done.
       on any configured console driver, including a serial
       console.</para>
   </sect1>
+
+  <sect1 id="kerneldebug-deadlocks">
+    <title>Debugging the Deadlocks</title>
+
+    <para>You may experience so called deadlocks, the situation where
+      system stops doing useful work. To provide the helpful bug report
+      in this situation, you shall use ddb as described above. Please,
+      include the output of <command>ps</command> and
+      <command>trace</command> for suspected processes in the
+      report.</para>
+
+    <para>If possible, consider doing further investigation. Receipt
+      below is especially useful if you suspect deadlock occurs in the
+      VFS layer. Add the options
+      <programlisting>makeoptions		DEBUG=-g
+	options		INVARIANTS
+	options		INVARIANT_SUPPORT
+	options		WITNESS
+	options		DEBUG_LOCKS
+	options		DEBUG_VFS_LOCKS
+	options		DIAGNOSTIC</programlisting>
+
+      to the kernel config. When deadlock occurs, in addition to the
+      output of the <command>ps</command> command, provide information
+      from the <command>show allpcpu</command>, <command>show
+      alllocks</command>, <command>show lockedvnods</command> and
+      <command>show alltrace</command>.</para>
+
+    <para>For threaded processes, to obtain meaningful backtraces, use
+      <command>thread thread-id</command> to switch to the thread
+      stack, and do backtrace with <command>where</command>.</para>
+  </sect1>
 </chapter>
 
 <!--