From owner-svn-doc-head@FreeBSD.ORG Sun Feb 24 22:19:55 2013 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id 48CCB42C; Sun, 24 Feb 2013 22:19:55 +0000 (UTC) (envelope-from keramida@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) by mx1.freebsd.org (Postfix) with ESMTP id 2BF718EF; Sun, 24 Feb 2013 22:19:55 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.5/8.14.5) with ESMTP id r1OMJsLq008154; Sun, 24 Feb 2013 22:19:54 GMT (envelope-from keramida@svn.freebsd.org) Received: (from keramida@localhost) by svn.freebsd.org (8.14.5/8.14.5/Submit) id r1OMJsbV008153; Sun, 24 Feb 2013 22:19:54 GMT (envelope-from keramida@svn.freebsd.org) Message-Id: <201302242219.r1OMJsbV008153@svn.freebsd.org> From: Giorgos Keramidas Date: Sun, 24 Feb 2013 22:19:54 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r41038 - head/en_US.ISO8859-1/books/faq X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 24 Feb 2013 22:19:55 -0000 Author: keramida Date: Sun Feb 24 22:19:53 2013 New Revision: 41038 URL: http://svnweb.freebsd.org/changeset/doc/41038 Log: Expand a bit the description of a LOR and what witness does While here try to explain a bit why a deadlock could happen when witness(4) reports a ’lock order reversal’ and why ’reversal’ is an important part of the deadlock-related warning. Approved by: gjb (mentor) Reviewed by: eadler Modified: head/en_US.ISO8859-1/books/faq/book.xml Modified: head/en_US.ISO8859-1/books/faq/book.xml ============================================================================== --- head/en_US.ISO8859-1/books/faq/book.xml Sun Feb 24 16:58:04 2013 (r41037) +++ head/en_US.ISO8859-1/books/faq/book.xml Sun Feb 24 22:19:53 2013 (r41038) @@ -2494,18 +2494,37 @@ kern.timecounter.hardware: TSC -> i82 The &os; kernel uses a number of resource locks to - arbitrate contention for certain resources. A run-time - lock diagnostic system found in &os.current; kernels - (but removed for releases), called &man.witness.4;, - detects the potential for deadlocks due to locking errors. - (It is possible to get false positives, as &man.witness.4; - is slightly conservative.) A true positive report - indicates that "if you were unlucky, a deadlock would have - happened here">. - - Problematic LORs tend to get fixed - quickly, so check &a.current.url; before posting to the - mailing lists. + arbitrate contention for certain resources. When multiple + kernel threads try to obtain multiple resource locks, + there's always the potential for a deadlock, + where two threads have each obtained one of the locks and + blocks forever waiting for the other thread to release one + of the other locks. This sort of locking problem can be + avoided if all threads obtain the locks in the same + order. + + A run-time lock diagnostic system called &man.witness.4;, + enabled in &os.current; and disabled by default for stable + branches and releases, detects the potential for deadlocks due to + locking errors, including errors caused by obtaining multiple + resource locks with a different order from different parts of the + kernel. The &man.witness.4; framework tries to detect this + problem as it happens, and reports it by printing a message to the + system console about a lock order reversal + (often referred to also as LOR). + + It is possible to get false positives, as &man.witness.4; + is conservative. A true positive report does + not mean that a system is dead-locked; instead + it should be understood as a warning of the form if + you were unlucky, a deadlock would have happened + here. + + + Problematic LORs tend to get fixed + quickly, so check &a.current.url; before posting to the + mailing lists. +