docs/68595: [PATCH] add FAQ entry for lock order reversals

[Jonathan Noack]

>Number:         68595
>Category:       docs
>Synopsis:       [PATCH] add FAQ entry for lock order reversals
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Fri Jul 02 08:40:13 GMT 2004
>Closed-Date:
>Last-Modified:
>Originator:     Jonathan Noack
>Release:        FreeBSD 5.2-CURRENT i386
>Organization:
Concordia Lutheran High School
>Environment:
System: FreeBSD compgeek.noacks.org 5.2-CURRENT FreeBSD 5.2-CURRENT #11: Wed Jun 30 19:53:45 CDT 2004 noackjr at compgeek.noacks.org:/usr/obj/usr/src/sys/COMPGEEK i386
>Description:
	Add a FAQ entry for lock order reversals.  It basically just
	quotes a mailing list response by Robert Watson, but there is
	also a note pointing to the lock order reversal status page
	maintained by Bjoern Zeeb:
	http://sources.zabbadoz.net/freebsd/lor.html

	See recent comments in the freebsd-current archive:
	http://docs.freebsd.org/cgi/mid.cgi?20040701083434.GA83951
	http://docs.freebsd.org/cgi/mid.cgi?20040701103535.GA84499
	http://docs.freebsd.org/cgi/mid.cgi?40E3EBD2.2020106
>How-To-Repeat:
	N/A
>Fix:
	See patch below.

--- lor-faq.diff begins here ---
Index: book.sgml
===================================================================
RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/faq/book.sgml,v
retrieving revision 1.626
diff -u -r1.626 book.sgml
--- book.sgml	1 Jul 2004 07:29:04 -0000	1.626
+++ book.sgml	1 Jul 2004 11:29:35 -0000
@@ -4379,6 +4379,51 @@
             channel is numbered 0, and so on.</para>
         </answer>
       </qandaentry>
+
+      <qandaentry>
+        <question id="lock-order-reversal">
+          <para>What is a <errorname>lock order reversal</errorname>?</para>
+        </question>
+
+        <answer>
+          <para>&a.rwatson; answered this question very succinctly on
+            the freebsd-current list in a thread entitled <quote><ulink
+            url="http://docs.freebsd.org/cgi/getmsg.cgi?fetch=65165+0+/usr/local/www/db/text/2003/freebsd-current/20031221.freebsd-current">lock
+            order reversals - what do they mean?</ulink></quote></para>
+
+          <blockquote>
+            <attribution>&a.rwatson; on freebsd-current, December 14,
+              2003</attribution>
+
+            <para>These warnings are generated by Witness, a run-time lock
+              diagnostic system found in FreeBSD 5-CURRENT kernels (but
+              removed in releases).  You can read more about Witness in the
+              &man.witness.4; man page, which talks about its capabilities.  Among
+              other things, Witness performs run-time lock order verification
+              using a combination of hard coded lock orders, and run-time
+              detected lock orders, and generates console warnings when lock
+              orders are violated.  The intent of this is to detect the
+              potential for deadlocks due to lock order violations; it's worth
+              observing that Witness is actually slightly conservative, and so
+              it's possible to get false positives.  In the event that Witness
+              is accurately reporting a lock order problem, it's basically
+              saying "If you were unlucky, a deadlock would have happened
+              here".  There are a couple of "well known" false positives,
+              which we need to do a better job of documenting to prevent
+              spurious reports.  The non-well-known ones typically correspond
+              to bugs in newly added locking, as lock order reversals usually
+              get fixed pretty quickly because Witness is busy generating
+              warnings :-).</para>
+          </blockquote>
+
+          <note>
+            <para>See <ulink
+              url="http://sources.zabbadoz.net/freebsd/lor.html">Bjoern
+              Zeeb's lock order reversal page</ulink> for the status of
+              known lock order reversals.</para>
+          </note>
+        </answer>
+      </qandaentry>
     </qandaset>
   </chapter>
 
--- lor-faq.diff ends here ---


>Release-Note:
>Audit-Trail:
>Unformatted: