[patch] deadlock debugging

[Kostik Belousov]

Reports of the deadlocks are reccurrent topic on the current- and stable- 
lists. Many of us have to repeat the instructions on how to provide
the useful initial bug report from them.

Please, comment proposed addition to the kernel debugging chapter
of the developer handbook.

Obviously, I am not an english native speaker. Your corrections
for both factual material and grammar/style are very much welcome !

P.S. I'm not on the list, do not remove CC: to me on replying.

Index: en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml
===================================================================
RCS file: /usr/local/arch/ncvs/doc/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml,v
retrieving revision 1.64
diff -u -r1.64 chapter.sgml
--- en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml	5 Jan 2006 20:03:34 -0000	1.64
+++ en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml	7 Jun 2006 08:39:20 -0000
@@ -821,6 +821,41 @@
       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 useful 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 usefull 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> and <command>show
+      lockedvnods</command>. More, please provide output of the
+      <command>where pid</command> for each process id mentioned in
+      the output of the <command>show</command> commands.
+    </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>
 
 <!--
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20060607/9a2adc2f/attachment.sig>