From noackjr@compgeek.noacks.org  Fri Jul  2 08:30:30 2004
Return-Path: <noackjr@compgeek.noacks.org>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 4344216A4CE
	for <FreeBSD-gnats-submit@freebsd.org>; Fri,  2 Jul 2004 08:30:30 +0000 (GMT)
Received: from smtp001.bizmail.yahoo.com (smtp001.bizmail.yahoo.com [216.136.172.125])
	by mx1.FreeBSD.org (Postfix) with SMTP id F343543D41
	for <FreeBSD-gnats-submit@freebsd.org>; Fri,  2 Jul 2004 08:30:29 +0000 (GMT)
	(envelope-from noackjr@compgeek.noacks.org)
Received: from unknown (HELO optimator.noacks.org) (noackjr@supercrime.org@70.240.179.20 with login)
  by smtp001.bizmail.yahoo.com with SMTP; 2 Jul 2004 08:29:31 -0000
Received: from localhost (localhost [127.0.0.1])
	by optimator.noacks.org (Postfix) with ESMTP id 1A8E661DE
	for <FreeBSD-gnats-submit@freebsd.org>; Fri,  2 Jul 2004 03:29:31 -0500 (CDT)
Received: from optimator.noacks.org ([127.0.0.1])
 by localhost (optimator.noacks.org [127.0.0.1]) (amavisd-new, port 10024)
 with LMTP id 06778-06 for <FreeBSD-gnats-submit@freebsd.org>;
 Fri,  2 Jul 2004 03:29:29 -0500 (CDT)
Received: from compgeek.noacks.org (compgeek [192.168.1.10])
	by optimator.noacks.org (Postfix) with ESMTP id 2ADC261D2
	for <FreeBSD-gnats-submit@freebsd.org>; Fri,  2 Jul 2004 03:29:29 -0500 (CDT)
Received: (from noackjr@localhost)
	by compgeek.noacks.org (8.12.11/8.12.11/Submit) id i628TTWw002413;
	Fri, 2 Jul 2004 03:29:29 -0500 (CDT)
	(envelope-from noackjr)
Message-Id: <200407020829.i628TTWw002413@compgeek.noacks.org>
Date: Fri, 2 Jul 2004 03:29:29 -0500 (CDT)
From: Jonathan Noack <noackj@concordiacrusaders.org>
Reply-To: Jonathan Noack <noackj@concordiacrusaders.org>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: [PATCH] add FAQ entry for lock order reversals
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         68595
>Category:       docs
>Synopsis:       [PATCH] add FAQ entry for lock order reversals
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Fri Jul 02 08:40:13 GMT 2004
>Closed-Date:    Mon Aug 02 05:28:13 GMT 2004
>Last-Modified:  Mon Aug 02 05:28:13 GMT 2004
>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@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:

From: Hiten Pandya <hmp@freebsd.org>
To: freebsd-gnats-submit@freebsd.org
Cc: noackj@concordiacrusaders.org
Subject: Re: docs/68595: [PATCH] add FAQ entry for lock order reversals
Date: Tue, 6 Jul 2004 19:40:55 -0400 (EDT)

 Dear Jonathan,
 
 This text actually belongs in the glossary part of the Handbook.
 
 People generally tend to print out the Handbook so by putting it
 there, it results into better documentation.
 
 Cheers.
 
 Hiten Pandya
 hmp at freebsd.org

From: Jonathan Noack <noackj@concordiacrusaders.org>
To: Hiten Pandya <hmp@freebsd.org>,
	<freebsd-gnats-submit@freebsd.org>
Cc: <noackj@concordiacrusaders.org>
Subject: Re: docs/68595: [PATCH] add FAQ entry for lock order reversals
Date: Thu, 08 Jul 2004 01:45:26 -0500

 I can't seem to find the glossary part of the handbook (there doesn't app=
 ear
 to be a glossary at http://www.freebsd.org/handbook/ and grepping for
 glossary in the doc source didn't turn up much).  Can you point me to whe=
 re
 it is defined?
 
 Jon
 
 
 Jonathan Noack
 Technology Coordinator
 Concordia Lutheran High School (http://www.concordiacrusaders.org)
 700 East Main Street
 Tomball, TX 77375-6721
 281.351.2547 x229 (work)
 713.480.7163 (cell)
 
 "Do not worry about your problems with computers, I assure you mine are f=
 ar
 greater." -- Jonathan Noack
 
 

From: "Simon L. Nielsen" <simon@FreeBSD.org>
To: Jonathan Noack <noackj@concordiacrusaders.org>
Cc: freebsd-gnats-submit@FreeBSD.org
Subject: Re: docs/68595: [PATCH] add FAQ entry for lock order reversals
Date: Thu, 8 Jul 2004 10:18:12 +0200

 --YiEDa0DAkWCtVeE4
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline
 Content-Transfer-Encoding: quoted-printable
 
 On 2004.07.08 06:50:24 +0000, Jonathan Noack wrote:
 
 > I can't seem to find the glossary part of the handbook (there doesn't
 > appear to be a glossary at http://www.freebsd.org/handbook/ and
 > grepping for glossary in the doc source didn't turn up much).  Can you
 > point me to where it is defined?
 
 It is not build by default (yet) since there hasn't been that much
 content in it (though that should probably be reconsidered soon).
 Anyway, it's located in:
 
 doc/en_US.ISO8859-1/share/sgml/glossary/freebsd-glossary.sgml
 
 --=20
 Simon L. Nielsen
 FreeBSD Documentation Team
 
 --YiEDa0DAkWCtVeE4
 Content-Type: application/pgp-signature
 Content-Disposition: inline
 
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1.2.4 (FreeBSD)
 
 iD8DBQFA7QNDh9pcDSc1mlERAmewAKCdITaRCk9xC2Y++8XBu1FsMMuLfACgopmt
 zbiZ5oNMJnFc/nwNGBaqvCs=
 =49+r
 -----END PGP SIGNATURE-----
 
 --YiEDa0DAkWCtVeE4--

From: Hiten Pandya <hmp@freebsd.org>
To: Jonathan Noack <noackj@concordiacrusaders.org>
Cc: freebsd-gnats-submit@freebsd.org
Subject: Re: docs/68595: [PATCH] add FAQ entry for lock order reversals
Date: Thu, 8 Jul 2004 07:15:49 -0400 (EDT)

 I do apologise.  The glossary is actually part of the Architecture
 Handbook.
 
 In that case, it might be just OK to add it to the FAQ right now,
 and once a Glossary chapter is written for the Handbook it can be
 included in there.
 
 Hiten Pandya
 hmp at freebsd.org
 
 On Thu, 8 Jul 2004, Jonathan Noack wrote:
 
  :I can't seem to find the glossary part of the handbook (there doesn't appear
  :to be a glossary at http://www.freebsd.org/handbook/ and grepping for
  :glossary in the doc source didn't turn up much).  Can you point me to where
  :it is defined?
  :
  :Jon
  :
  :
  :Jonathan Noack
  :Technology Coordinator
  :Concordia Lutheran High School (http://www.concordiacrusaders.org)
  :700 East Main Street
  :Tomball, TX 77375-6721
  :281.351.2547 x229 (work)
  :713.480.7163 (cell)
  :
  :"Do not worry about your problems with computers, I assure you mine are far
  :greater." -- Jonathan Noack
  :
  :
  :
State-Changed-From-To: open->closed 
State-Changed-By: murray 
State-Changed-When: Mon Aug 2 05:26:03 GMT 2004 
State-Changed-Why:  
The submitter did not send in a glossary entry.  It's true that we may 
want to add LOR to a glossary at some point, but as proved by the 
mailing list thread from which this submission was taken, this is in 
fact a frequently asked question.  This is very appropriate for the 
troubleshooting section of the FAQ as is. 

Thanks for the submission!  It will appear on the website within 24 
hours. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=68595 
>Unformatted:
