diff --git a/en_US.ISO8859-1/books/arch-handbook/book.sgml b/en_US.ISO8859-1/books/arch-handbook/book.sgml
index 4e64f19df1..1006c9f5d2 100644
--- a/en_US.ISO8859-1/books/arch-handbook/book.sgml
+++ b/en_US.ISO8859-1/books/arch-handbook/book.sgml
@@ -1,515 +1,520 @@
 <!--
      The FreeBSD Documentation Project
 
-     $FreeBSD: doc/en_US.ISO_8859-1/books/developers-handbook/book.sgml,v 1.9 2000/11/28 19:04:02 asmodai Exp $
+     $FreeBSD: doc/en_US.ISO_8859-1/books/developers-handbook/book.sgml,v 1.10 2000/11/28 19:07:40 asmodai Exp $
 -->
 
 <!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [
 <!ENTITY % bookinfo PUBLIC "-//FreeBSD//ENTITIES DocBook BookInfo Entities//EN">
 %bookinfo;
+<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
+%man;
 <!ENTITY % chapters SYSTEM "chapters.ent"> %chapters;
 ]>
 
 <book>
   <bookinfo>
     <title>FreeBSD Developers' Handbook</title>
     
     <authorgroup>
       <author>
 	<surname>The FreeBSD Documentation Project</surname>
         <affiliation>
           <address>
             <email>doc@FreeBSD.org</email>
           </address>
         </affiliation>
       </author>
     </authorgroup>
     
     <pubdate>August 2000</pubdate>
     
     <copyright>
       <year>2000</year>
       <holder>The FreeBSD Documentation Project</holder>
     </copyright>
 
     &bookinfo.legalnotice;
     
     <abstract>
       <para>Welcome to the Developers' Handbook.</para>
     </abstract>
   </bookinfo>
   
   <part id="introduction">
     <title>Introduction</title>
 
     <chapter id="developmentplatform">
       <title>Developing on FreeBSD</title>
 
       <para>This will need to discuss FreeBSD as a development
         platform, the vision of BSD, architectural overview, layout of
         /usr/src, history, etc.</para>
 
       <para>Thank you for considering FreeBSD as your development
         platform!  We hope it will not let you down.</para>
     </chapter>
 
     <chapter id="bsdvision">
       <title>The BSD Vision</title>
 
       <para></para>
     </chapter>
 
     <chapter id="archoverview">
       <title>Architectural Overview</title>
 
       <para></para>
     </chapter>
 
     <chapter id="sourcelayout">
       <title>The Layout of /usr/src</title>
 
       <para>The complete source code to FreeBSD is available from our
       public CVS repository.  The source code is normally installed in
       <filename class=directory>/usr/src</filename> which contains the
       following subdirectories.</para>
 
       <para>
       <informaltable frame="none">
         <tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Directory</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 	  
 	  <tbody>
 	    <row>
 	    <entry><filename class=directory>bin/</filename></entry>
             <entry>Source for files in
             <filename>/bin</filename></entry>
 	    </row>
 	    
 	    <row>
 	    <entry><filename class=directory>contrib/</filename></entry>
 	    <entry>Source for files from contribued software.</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>crypto/</filename></entry>
 	    <entry>DES source</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>etc/</filename></entry>
 	    <entry>Source for files in <filename
 	    class=directory>/etc</filename></entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>games/</filename></entry>
 	    <entry>Source for files in <filename
 	    class=directory>/usr/games</filename></entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>gnu/</filename></entry>
 	    <entry>Utilities covered by the GNU Public License</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>include/</filename></entry>
             <entry>Source for files in <filename
             class=directory>/usr/include</filename></entry>
 	    </row>
 
 	    <row>
 	    <entry><filename
  class=directory>kerberosIV/</filename></entry>
             <entry>Source for Kerbereros version IV</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename
  class=directory>kerberos5/</filename></entry>
             <entry>Source for Kerbereros version 5</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>lib/</filename></entry>
 	    <entry>Source for files in <filename
 	    class=directory>/usr/lib</filename></entry>
 	    </row>
 	    
 	    <row>
 	    <entry><filename class=directory>libexec/</filename></entry>
 	    <entry>Source for files in <filename
 	    class=directory>/usr/libexec</filename></entry>
 	    </row>
 	    
 	    <row>
 	    <entry><filename
  class=directory>release/</filename></entry>
             <entry>Files required to produce a FreeBSD release</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>sbin/</filename></entry>
 	    <entry>Source for files in <filename
 	    class=directory>/sbin</filename></entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>secure/</filename></entry>
 	    <entry>FreeSec sources</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>share/</filename></entry>
 	    <entry>Source for files in <filename
 	    class=directory>/sbin</filename></entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>sys/</filename></entry>
 	    <entry>Kernel source files</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>tools/</filename></entry>
 	    <entry>Tools used for maintenance and testing of
 	    FreeBSD</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename
  class=directory>usr.bin/</filename></entry>
             <entry>Source for files in <filename
  class=directory>/usr/bin</filename></entry>
             </row>
 
 	    <row>
 	    <entry><filename
  class=directory>usr.sbin/</filename></entry>
             <entry>Source for files in <filename
  class=directory>/usr/sbin</filename></entry>
             </row>
           </tbody>
 	</tgroup>
       </informaltable>
 
       </para>
 
     </chapter>
   </part>
 
   <part id="Basics">
     <title>Basics</title>
 
     &chap.tools;
     &chap.secure;
 
   </part>
 
   <part id="kernel">
     <title>Kernel</title>
 
     <chapter id="kernelhistory">
       <title>History of the Unix Kernel</title>
 
       <para>Some history of the Unix/BSD kernel, system calls, how do
         processes work, blocking, scheduling, threads (kernel),
         context switching, signals, interrupts, modules, etc.</para>
 
       <para></para>
     </chapter>
+
+    &chap.locking;
+
   </part>
 
   <part id="memory">
     <title>Memory and Virtual Memory</title>
 
     <chapter id="virtualmemory">
       <title>Virtual Memory</title>
 
       <para>VM, paging, swapping, allocating memory, testing for
         memory leaks, mmap, vnodes, etc.</para>
 
       <para></para>
     </chapter>
   </part>
 
   <part id="iosystem">
     <title>I/O System</title>
 
     <chapter id="ufs">
       <title>UFS</title>
 
       <para>UFS, FFS, Ext2FS, JFS, inodes, buffer cache, labeling,
         locking, metadata, soft-updates, LFS, portalfs, procfs,
         vnodes, memory sharing, memory objects, TLBs, caching</para>
 
     </chapter>
   </part>
 
   <part id="ipc">
     <title>Interprocess Communication</title>
     
     <chapter id="signals">
       <title>Signals</title>
 
       <para>Signals, pipes, semaphores, message queues, shared memory,
         ports, sockets, doors</para>
 
     </chapter>
   </part>
 
   <part id="networking">
     <title>Networking</title>
     
     <chapter id="sockets">
       <title>Sockets</title>
 
       <para>Sockets, bpf, IP, TCP, UDP, ICMP, OSI, bridging,
         firewalling, NAT, switching, etc</para>
 
     </chapter>
   </part>
   
   <part id="networkfs">
     <title>Network Filesystems</title>
 
     <chapter id="afs">
       <title>AFS</title>
 
       <para>AFS, NFS, SANs etc]</para>
 
     </chapter>
   </part>
   
   <part id="terminal">
     <title>Terminal Handling</title>
 
     <chapter id="syscons">
       <title>Syscons</title>
 
       <para>Syscons, tty, PCVT, serial console, screen savers,
         etc</para>
 
     </chapter>
   </part>
   
   <part id="sound">
     <title>Sound</title>
 
     <chapter id="oss">
       <title>OSS</title>
 
       <para>OSS, waveforms, etc</para>
 
     </chapter>
   </part>
   
   <part id="devicedrivers">
     <title>Device Drivers</title>
 
     &chap.driverbasics;
     &chap.pci;
 
     <chapter id="usb">
       <title>USB Devices</title>
 
       <para>This chapter will talk about the FreeBSD mechanisms for
       writing a device driver for a device on a USB bus.</para>
     </chapter>
 
     <chapter id="newbus">
       <title>NewBus</title>
 
       <para>This chapter will talk about the FreeBSD NewBus
       architecture.</para>
     </chapter>
 
   </part>
   
   <part id="architectures">
     <title>Architectures</title>
 
     <chapter id="ia32">
       <title>IA-32</title>
 
       <para>Talk about the architectural specifics of FreeBSD/x86.</para>
 
     </chapter>
 
     <chapter id="alpha">
       <title>Alpha</title>
 
       <para>Talk about the architectural specifics of
       FreeBSD/alpha.</para>
 
       <para>Explanation of allignment errors, how to fix, how to
       ignore.</para>
 
       <para>Example assembly language code for FreeBSD/alpha.</para>
     </chapter>
 
     <chapter id="ia64">
       <title>IA-64</title>
 
       <para>Talk about the architectural specifics of
       FreeBSD/ia64.</para>
 
     </chapter>
   </part>
   
   <part id="debuggingpart">
     <title>Debugging</title>
 
     <chapter id="truss">
       <title>Truss</title>
 
       <para>various descriptions on how to debug certain aspects of
         the system using truss, ktrace, gdb, kgdb, etc</para>
 
     </chapter>
   </part>
   
   <part id="compatibility">
     <title>Compatibility Layers</title>
 
     <chapter id="linux">
       <title>Linux</title>
 
       <para>Linux, SVR4, etc</para>
 
     </chapter>
   </part>
   
   <part id="appendices">
     <title>Appendices</title>
 
       <bibliography>
 
       <biblioentry id="COD" xreflabel="1">
         <authorgroup>
           <author>
             <firstname>Dave</firstname>
             <othername role="MI">A</othername>
             <surname>Patterson</surname>
           </author>
           <author>
             <firstname>John</firstname>
             <othername role="MI">L</othername>
             <surname>Hennessy</surname>
           </author>
         </authorgroup>
         <copyright><year>1998</year><holder>Morgan Kaufmann Publishers,
         Inc.</holder></copyright>
         <isbn>1-55860-428-6</isbn>
         <publisher>
           <publishername>Morgan Kaufmann Publishers, Inc.</publishername>
         </publisher>
         <title>Computer Organization and Design</title>
         <subtitle>The Hardware / Software Interface</subtitle>
         <pagenums>1-2</pagenums>
       </biblioentry>
 
       <biblioentry xreflabel="2">
         <authorgroup>
           <author>
             <firstname>W.</firstname>
             <othername role="Middle">Richard</othername>
             <surname>Stevens</surname>
           </author>
         </authorgroup>
         <copyright><year>1993</year><holder>Addison Wesley Longman,
         Inc.</holder></copyright>
         <isbn>0-201-56317-7</isbn>
         <publisher>
           <publishername>Addison Wesley Longman, Inc.</publishername>
         </publisher>
         <title>Advanced Programming in the Unix Environment</title>
         <pagenums>1-2</pagenums>
       </biblioentry>
 
       <biblioentry xreflabel="3">
         <authorgroup>
           <author>
             <firstname>Marshall</firstname>
             <othername role="Middle">Kirk</othername>
             <surname>McKusick</surname>
           </author>
           <author>
             <firstname>Keith</firstname>
             <surname>Bostic</surname>
           </author>
           <author>
             <firstname>Michael</firstname>
             <othername role="MI">J</othername>
             <surname>Karels</surname>
           </author>
           <author>
             <firstname>John</firstname>
             <othername role="MI">S</othername>
             <surname>Quarterman</surname>
           </author>
         </authorgroup>
         <copyright><year>1996</year><holder>Addison-Wesley Publishing Company,
         Inc.</holder></copyright>
         <isbn>0-201-54979-4</isbn>
         <publisher>
           <publishername>Addison-Wesley Publishing Company, Inc.</publishername>
         </publisher>
         <title>The Design and Implementation of the 4.4 BSD Operating System</title>
         <pagenums>1-2</pagenums>
       </biblioentry>
 
       <biblioentry id="Phrack" xreflabel="4">
         <authorgroup>
           <author>
             <firstname>Aleph</firstname>
             <surname>One</surname>
           </author>
         </authorgroup>
         <title>Phrack 49; "Smashing the Stack for Fun and Profit"</title>
       </biblioentry>
 
       <biblioentry id="StackGuard" xreflabel="5">
         <authorgroup>
           <author>
             <firstname>Chrispin</firstname>
             <surname>Cowan</surname>
           </author>
           <author>
             <firstname>Calton</firstname>
             <surname>Pu</surname>
           </author>
           <author>
             <firstname>Dave</firstname>
             <surname>Maier</surname>
           </author>
         </authorgroup>
         <title>StackGuard; Automatic Adaptive Detection and Prevention of
         Buffer-Overflow Attacks</title>
       </biblioentry>
 
       <biblioentry id="OpenBSD" xreflabel="6">
         <authorgroup>
 	  <author>
 	    <firstname>Todd</firstname>
 	    <surname>Miller</surname>
 	  </author>
 	  <author>
 	    <firstname>Theo</firstname>
 	    <surname>de Raadt</surname>
 	  </author>
 	</authorgroup>
 	<title>strlcpy and strlcat -- consistent, safe string copy and
 	concatenation.</title>
       </biblioentry>
 
       </bibliography>
 
   </part>
 
 </book>
diff --git a/en_US.ISO8859-1/books/arch-handbook/chapters.ent b/en_US.ISO8859-1/books/arch-handbook/chapters.ent
index e73ab6af45..c2149880e2 100644
--- a/en_US.ISO8859-1/books/arch-handbook/chapters.ent
+++ b/en_US.ISO8859-1/books/arch-handbook/chapters.ent
@@ -1,57 +1,58 @@
 <!-- 
      Creates entities for each chapter in the FreeBSD Developer's
      Handbook. Each entity is named chap.foo, where foo is the value
      of the id attribute on that chapter, and corresponds to the name of
      the directory in which that chapter's .sgml file is stored.
    
      Chapters should be listed in the order in which they are referenced.
  
-     $FreeBSD:$
+     $FreeBSD: doc/en_US.ISO_8859-1/books/developers-handbook/chapters.ent,v 1.1 2000/11/28 18:03:54 asmodai Exp $
 -->
 
 <!-- Part one -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part two -->
 <!ENTITY chap.tools			SYSTEM "tools/chapter.sgml">
 <!ENTITY chap.secure			SYSTEM "secure/chapter.sgml">
 
 <!-- Part three -->
 <!-- No significant material yet, still in book.sgml -->
+<!ENTITY chap.locking			SYSTEM "locking/chapter.sgml">
 
 <!-- Part four -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part five -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part six -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part seven -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part eight -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part nine -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part ten -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part eleven -->
 <!ENTITY chap.driverbasics		SYSTEM "driverbasics/chapter.sgml">
 <!ENTITY chap.pci			SYSTEM "pci/chapter.sgml">
 
 <!-- Part twelve -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part thirteen -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part fourteen -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part fifteen (appendices) -->
 <!ENTITY chap.bibliography		SYSTEM "bibliography/chapter.sgml">
diff --git a/en_US.ISO8859-1/books/arch-handbook/locking/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/locking/chapter.sgml
new file mode 100644
index 0000000000..54448a06ef
--- /dev/null
+++ b/en_US.ISO8859-1/books/arch-handbook/locking/chapter.sgml
@@ -0,0 +1,312 @@
+<!--
+     The FreeBSD Documentation Project
+     The FreeBSD SMP Next Generation Project
+
+     $FreeBSD$
+-->
+
+<chapter id="locking">
+  <title>Locking Notes</title>
+
+  <para><emphasis>This chapter is maintained by the FreeBSD SMP Next
+    Generation Project
+    <email>freebsd-smp@FreeBSD.org</email>.</emphasis></para>
+
+
+  <para>This document outlines the locking used in the FreeBSD kernel
+    to permit effective multi-processing within the kernel.  Locking
+    can be achieved via several means.  Data structures can be
+    protected by mutexes or &man.lockmgr.9; locks.  A few variables
+    are protected simply by always using atomic operations to access
+    them.</para>
+
+  <sect1>
+    <title>Mutexes</title>
+
+    <para>A mutex is simply a lock used to guarantee mutual exclusion.
+      Specifically, a mutex may only be owned by one entity at a time.
+      If another entity wishes to obtain a mutex that is already
+      owned, it must wait until the mutex is released.  In the FreeBSD
+      kernel, mutexes are owned by processes.</para>
+
+    <para>Mutexes may be recursively acquired, but they are intended
+      to be held for a short period of time.  Specifically, one may
+      not sleep while holding a mutex.  If you need to hold a lock
+      across a sleep, use a &man.lockmgr.9; lock.</para>
+    
+    <para>Each mutex has several properties of interest:</para>
+
+    <variablelist>
+	<varlistentry>
+	<term>Variable Name</term>
+	<listitem>
+	  <para>The name of the <type>struct mtx</type> variable in
+	    the kernel source.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>Logical Name</term>
+	<listitem>
+	  <para>The name of the mutex assigned to it by
+	    <function>mtx_init</function>.  This name is displayed in
+	    KTR trace messages and witness errors and warnings and is
+	    used to distinguish mutexes in the witness code.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>Type</term>
+	<listitem>
+	  <para>The type of the mutex in terms of the
+	    <constant>MTX_*</constant> flags.  The meaning for each
+	    flag is related to its meaning as documented in
+	    &man.mutex.9;.</para>
+
+	  <variablelist>
+	    <varlistentry>
+	      <term><constant>MTX_DEF</constant></term>
+	      <listitem>
+		<para>A sleep mutex</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><constant>MTX_SPIN</constant></term>
+	      <listitem>
+		<para>A spin mutex</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><constant>MTX_COLD</constant></term>
+	      <listitem>
+		<para>This mutex is initialized very early.  Thus, it
+		  must be declared via
+		  <function>MUTEX_DECLARE</function>, and the
+		  <constant>MTX_COLD</constant> flag must be passed to
+		  <function>mtx_init</function>.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><constant>MTX_TOPHALF</constant></term>
+	      <listitem>
+		<para>This spin mutex does not disable
+		  interrupts.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><constant>MTX_NORECURSE</constant></term>
+	      <listitem>
+		<para>This mutex is not allowed to recurse.</para>
+	      </listitem>
+	    </varlistentry>
+	  </variablelist>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>Protectees</term>
+	<listitem>
+	  <para>A list of data structures or data structure members
+	    that this entry protects.  For data structure members, the
+	    name will be in the form of
+	    <structname/structure name/.<structfield/member name/.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>Dependent Functions</term>
+	<listitem>
+	  <para>Functions that can only be called if this mutex is
+	    held.</para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+
+    <table frame="all" colsep="1" rowsep="1" pgwide="1">
+      <title>Mutex List</title>
+      
+      <tgroup cols="5">
+	<thead>
+	  <row>
+	    <entry>Variable Name</entry>
+	    <entry>Logical Name</entry>
+	    <entry>Type</entry>
+	    <entry>Protectees</entry>
+	    <entry>Dependent Functions</entry>
+	  </row>
+	</thead>
+	
+	<!-- The scheduler lock -->
+	<tbody>
+	  <row>
+	    <entry>sched_lock</entry>
+	    <entry><quote>sched lock</quote></entry>
+	    <entry>
+	      <constant>MTX_SPIN</constant> |
+	      <constant>MTX_COLD</constant>
+	    </entry>
+	    <entry>
+	      <varname>_gmonparam</varname>,
+	      <varname>cnt.v_swtch</varname>,
+	      <varname>cp_time</varname>,
+	      <varname>curpriority</varname>,
+	      <structname/mtx/.<structfield/mtx_blocked/,
+	      <structname/mtx/.<structfield/mtx_contested/,
+	      <structname/proc/.<structfield/p_contested/,
+	      <structname/proc/.<structfield/p_blocked/,
+	      <structname/proc/.<structfield/p_flag/
+		(<constant>P_PROFIL</constant> XXX,
+		 <constant>P_INMEM</constant>,
+	         <constant>P_SINTR</constant>,
+	         <constant>P_TIMEOUT</constant>,
+	         <constant>P_SWAPINREQ</constant> XXX,
+	         <constant>P_INMEN</constant> XXX),
+	      <structname/proc/.<structfield/p_nice/,
+	      <structname/proc/.<structfield/p_procq/,
+	      <structname/proc/.<structfield/p_blocked/,
+	      <structname/proc/.<structfield/p_estcpu/,
+	      <structname/proc/.<structfield/p_nativepri/,
+	      <structname/proc/.<structfield/p_priority/,
+	      <structname/proc/.<structfield/p_usrpri/,
+	      <structname/proc/.<structfield/p_rtprio/,
+	      <structname/proc/.<structfield/p_rqindex/,
+	      <structname/proc/.<structfield/p_stats->p_prof/,
+	      <structname/proc/.<structfield/p_stats->p_ru/,
+	      <structname/proc/.<structfield/p_stat/,
+	      <structname/proc/.<structfield/p_cpticks/
+	      <structname/proc/.<structfield/p_iticks/,
+	      <structname/proc/.<structfield/p_uticks/,
+	      <structname/proc/.<structfield/p_sticks/,
+	      <structname/proc/.<structfield/p_swtime/,
+	      <structname/proc/.<structfield/p_slptime/,
+	      <structname/proc/.<structfield/p_runtime/,
+	      <structname/proc/.<structfield/p_pctcpu/,
+	      <structname/proc/.<structfield/p_oncpu/,
+	      <structname/proc/.<structfield/p_asleep/,
+	      <structname/proc/.<structfield/p_wchan/,
+	      <structname/proc/.<structfield/p_wmesg/,
+	      <structname/proc/.<structfield/p_slpq/,
+	      <structname/proc/.<structfield/p_vmspace/
+		(XXX - in <function>statclock</function>),
+	      <varname>pscnt</varname>,
+	      <varname>slpque</varname>,
+	      <varname>itqueuebits</varname>,
+	      <varname>itqueues</varname>,
+	      <varname>rtqueuebits</varname>,
+	      <varname>rtqueues</varname>,
+	      <varname>queuebits</varname>,
+	      <varname>queues</varname>,
+	      <varname>idqueuebits</varname>,
+	      <varname>idqueues</varname>,
+	      <varname>callwheel</varname>,
+	      <varname>nextsoftcheck</varname>,
+	      <varname>switchtime</varname>,
+	      <varname>softticks</varname>,
+	      <varname>ticks</varname>
+	    </entry>
+	    <entry>
+	      <function>setrunqueue</function>,
+	      <function>remrunqueue</function>,
+	      <function>mi_switch</function>,
+	      <function>chooseproc</function>,
+	      <function>schedclock</function>,
+	      <function>resetpriority</function>,
+	      <function>updatepri</function>,
+	      <function>maybe_resched</function>,
+	      <function>cpu_switch</function>,
+	      <function>cpu_throw</function>
+	    </entry>
+	  </row>
+
+	  <!-- The vm86 pcb lock -->
+	  <row>
+	    <entry>vm86pcb_lock</entry>
+	    <entry><quote>vm86pcb lock</quote></entry>
+	    <entry>
+	      <constant>MTX_DEF</constant> |
+	      <constant>MTX_COLD</constant>
+	    </entry>
+	    <entry>
+	      <varname>vm86pcb</varname>
+	    </entry>
+	    <entry>
+	      <function>vm86_bioscall</function>
+	    </entry>
+	  </row>
+
+	  <!-- Giant -->
+	  <row>
+	    <entry>Giant</entry>
+	    <entry><quote>Giant</quote></entry>
+	    <entry>
+	      <constant>MTX_DEF</constant> |
+	      <constant>MTX_COLD</constant>
+	    </entry>
+	    <entry>nearly everything</entry>
+	    <entry>lots</entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </table>
+  </sect1>
+
+  <sect1>
+    <title>Lock Manager Locks</title>
+
+    <para>Locks that are provided via the &man.lockmgr.9; interface
+      are lock manager locks.  These locks are reader-writer locks and
+      may be held by a sleeping process.</para>
+
+    <table>
+      <title>&man.lockmgr.9; Lock List</title>
+
+      <tgroup cols="2">
+	<thead>
+	  <row>
+	    <entry>Variable Name</entry>
+	    <entry>Protectees</entry>
+	  </row>
+	</thead>
+	<tbody>
+	  <row>
+	    <entry><varname>allproc_lock</varname></entry>
+	    <entry>
+	      <varname>allproc</varname>
+	      <varname>zombproc</varname>
+	      <varname>pidhashtbl</varname>
+	      <structname/proc/.<structfield/p_list/
+	      <structname/proc/.<structfield/p_hash/
+	      <varname>nextpid</varname>
+	    </entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </table>
+  </sect1>
+
+  <sect1>
+    <title>Atomically Protected Variables</title>
+
+    <para>An atomically protected variable is a special variable that
+      is not protected by an explicit lock.  Instead, all data
+      accesses to the variables use special atomic operations as
+      described in &man.atomic.9;.  Very few variables are treated
+      this way, although other synchronization primitives such as
+      mutexes are implemented with atomically protected
+      variables.</para>
+
+    <itemizedlist>
+      <listitem>
+	<para><varname>astpending</varname></para>
+      </listitem>
+
+      <listitem>
+	<para><structname/mtx/.<structfield/mtx_lock/</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+</chapter>
diff --git a/en_US.ISO8859-1/books/developers-handbook/book.sgml b/en_US.ISO8859-1/books/developers-handbook/book.sgml
index 4e64f19df1..1006c9f5d2 100644
--- a/en_US.ISO8859-1/books/developers-handbook/book.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/book.sgml
@@ -1,515 +1,520 @@
 <!--
      The FreeBSD Documentation Project
 
-     $FreeBSD: doc/en_US.ISO_8859-1/books/developers-handbook/book.sgml,v 1.9 2000/11/28 19:04:02 asmodai Exp $
+     $FreeBSD: doc/en_US.ISO_8859-1/books/developers-handbook/book.sgml,v 1.10 2000/11/28 19:07:40 asmodai Exp $
 -->
 
 <!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [
 <!ENTITY % bookinfo PUBLIC "-//FreeBSD//ENTITIES DocBook BookInfo Entities//EN">
 %bookinfo;
+<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
+%man;
 <!ENTITY % chapters SYSTEM "chapters.ent"> %chapters;
 ]>
 
 <book>
   <bookinfo>
     <title>FreeBSD Developers' Handbook</title>
     
     <authorgroup>
       <author>
 	<surname>The FreeBSD Documentation Project</surname>
         <affiliation>
           <address>
             <email>doc@FreeBSD.org</email>
           </address>
         </affiliation>
       </author>
     </authorgroup>
     
     <pubdate>August 2000</pubdate>
     
     <copyright>
       <year>2000</year>
       <holder>The FreeBSD Documentation Project</holder>
     </copyright>
 
     &bookinfo.legalnotice;
     
     <abstract>
       <para>Welcome to the Developers' Handbook.</para>
     </abstract>
   </bookinfo>
   
   <part id="introduction">
     <title>Introduction</title>
 
     <chapter id="developmentplatform">
       <title>Developing on FreeBSD</title>
 
       <para>This will need to discuss FreeBSD as a development
         platform, the vision of BSD, architectural overview, layout of
         /usr/src, history, etc.</para>
 
       <para>Thank you for considering FreeBSD as your development
         platform!  We hope it will not let you down.</para>
     </chapter>
 
     <chapter id="bsdvision">
       <title>The BSD Vision</title>
 
       <para></para>
     </chapter>
 
     <chapter id="archoverview">
       <title>Architectural Overview</title>
 
       <para></para>
     </chapter>
 
     <chapter id="sourcelayout">
       <title>The Layout of /usr/src</title>
 
       <para>The complete source code to FreeBSD is available from our
       public CVS repository.  The source code is normally installed in
       <filename class=directory>/usr/src</filename> which contains the
       following subdirectories.</para>
 
       <para>
       <informaltable frame="none">
         <tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Directory</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 	  
 	  <tbody>
 	    <row>
 	    <entry><filename class=directory>bin/</filename></entry>
             <entry>Source for files in
             <filename>/bin</filename></entry>
 	    </row>
 	    
 	    <row>
 	    <entry><filename class=directory>contrib/</filename></entry>
 	    <entry>Source for files from contribued software.</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>crypto/</filename></entry>
 	    <entry>DES source</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>etc/</filename></entry>
 	    <entry>Source for files in <filename
 	    class=directory>/etc</filename></entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>games/</filename></entry>
 	    <entry>Source for files in <filename
 	    class=directory>/usr/games</filename></entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>gnu/</filename></entry>
 	    <entry>Utilities covered by the GNU Public License</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>include/</filename></entry>
             <entry>Source for files in <filename
             class=directory>/usr/include</filename></entry>
 	    </row>
 
 	    <row>
 	    <entry><filename
  class=directory>kerberosIV/</filename></entry>
             <entry>Source for Kerbereros version IV</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename
  class=directory>kerberos5/</filename></entry>
             <entry>Source for Kerbereros version 5</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>lib/</filename></entry>
 	    <entry>Source for files in <filename
 	    class=directory>/usr/lib</filename></entry>
 	    </row>
 	    
 	    <row>
 	    <entry><filename class=directory>libexec/</filename></entry>
 	    <entry>Source for files in <filename
 	    class=directory>/usr/libexec</filename></entry>
 	    </row>
 	    
 	    <row>
 	    <entry><filename
  class=directory>release/</filename></entry>
             <entry>Files required to produce a FreeBSD release</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>sbin/</filename></entry>
 	    <entry>Source for files in <filename
 	    class=directory>/sbin</filename></entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>secure/</filename></entry>
 	    <entry>FreeSec sources</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>share/</filename></entry>
 	    <entry>Source for files in <filename
 	    class=directory>/sbin</filename></entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>sys/</filename></entry>
 	    <entry>Kernel source files</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>tools/</filename></entry>
 	    <entry>Tools used for maintenance and testing of
 	    FreeBSD</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename
  class=directory>usr.bin/</filename></entry>
             <entry>Source for files in <filename
  class=directory>/usr/bin</filename></entry>
             </row>
 
 	    <row>
 	    <entry><filename
  class=directory>usr.sbin/</filename></entry>
             <entry>Source for files in <filename
  class=directory>/usr/sbin</filename></entry>
             </row>
           </tbody>
 	</tgroup>
       </informaltable>
 
       </para>
 
     </chapter>
   </part>
 
   <part id="Basics">
     <title>Basics</title>
 
     &chap.tools;
     &chap.secure;
 
   </part>
 
   <part id="kernel">
     <title>Kernel</title>
 
     <chapter id="kernelhistory">
       <title>History of the Unix Kernel</title>
 
       <para>Some history of the Unix/BSD kernel, system calls, how do
         processes work, blocking, scheduling, threads (kernel),
         context switching, signals, interrupts, modules, etc.</para>
 
       <para></para>
     </chapter>
+
+    &chap.locking;
+
   </part>
 
   <part id="memory">
     <title>Memory and Virtual Memory</title>
 
     <chapter id="virtualmemory">
       <title>Virtual Memory</title>
 
       <para>VM, paging, swapping, allocating memory, testing for
         memory leaks, mmap, vnodes, etc.</para>
 
       <para></para>
     </chapter>
   </part>
 
   <part id="iosystem">
     <title>I/O System</title>
 
     <chapter id="ufs">
       <title>UFS</title>
 
       <para>UFS, FFS, Ext2FS, JFS, inodes, buffer cache, labeling,
         locking, metadata, soft-updates, LFS, portalfs, procfs,
         vnodes, memory sharing, memory objects, TLBs, caching</para>
 
     </chapter>
   </part>
 
   <part id="ipc">
     <title>Interprocess Communication</title>
     
     <chapter id="signals">
       <title>Signals</title>
 
       <para>Signals, pipes, semaphores, message queues, shared memory,
         ports, sockets, doors</para>
 
     </chapter>
   </part>
 
   <part id="networking">
     <title>Networking</title>
     
     <chapter id="sockets">
       <title>Sockets</title>
 
       <para>Sockets, bpf, IP, TCP, UDP, ICMP, OSI, bridging,
         firewalling, NAT, switching, etc</para>
 
     </chapter>
   </part>
   
   <part id="networkfs">
     <title>Network Filesystems</title>
 
     <chapter id="afs">
       <title>AFS</title>
 
       <para>AFS, NFS, SANs etc]</para>
 
     </chapter>
   </part>
   
   <part id="terminal">
     <title>Terminal Handling</title>
 
     <chapter id="syscons">
       <title>Syscons</title>
 
       <para>Syscons, tty, PCVT, serial console, screen savers,
         etc</para>
 
     </chapter>
   </part>
   
   <part id="sound">
     <title>Sound</title>
 
     <chapter id="oss">
       <title>OSS</title>
 
       <para>OSS, waveforms, etc</para>
 
     </chapter>
   </part>
   
   <part id="devicedrivers">
     <title>Device Drivers</title>
 
     &chap.driverbasics;
     &chap.pci;
 
     <chapter id="usb">
       <title>USB Devices</title>
 
       <para>This chapter will talk about the FreeBSD mechanisms for
       writing a device driver for a device on a USB bus.</para>
     </chapter>
 
     <chapter id="newbus">
       <title>NewBus</title>
 
       <para>This chapter will talk about the FreeBSD NewBus
       architecture.</para>
     </chapter>
 
   </part>
   
   <part id="architectures">
     <title>Architectures</title>
 
     <chapter id="ia32">
       <title>IA-32</title>
 
       <para>Talk about the architectural specifics of FreeBSD/x86.</para>
 
     </chapter>
 
     <chapter id="alpha">
       <title>Alpha</title>
 
       <para>Talk about the architectural specifics of
       FreeBSD/alpha.</para>
 
       <para>Explanation of allignment errors, how to fix, how to
       ignore.</para>
 
       <para>Example assembly language code for FreeBSD/alpha.</para>
     </chapter>
 
     <chapter id="ia64">
       <title>IA-64</title>
 
       <para>Talk about the architectural specifics of
       FreeBSD/ia64.</para>
 
     </chapter>
   </part>
   
   <part id="debuggingpart">
     <title>Debugging</title>
 
     <chapter id="truss">
       <title>Truss</title>
 
       <para>various descriptions on how to debug certain aspects of
         the system using truss, ktrace, gdb, kgdb, etc</para>
 
     </chapter>
   </part>
   
   <part id="compatibility">
     <title>Compatibility Layers</title>
 
     <chapter id="linux">
       <title>Linux</title>
 
       <para>Linux, SVR4, etc</para>
 
     </chapter>
   </part>
   
   <part id="appendices">
     <title>Appendices</title>
 
       <bibliography>
 
       <biblioentry id="COD" xreflabel="1">
         <authorgroup>
           <author>
             <firstname>Dave</firstname>
             <othername role="MI">A</othername>
             <surname>Patterson</surname>
           </author>
           <author>
             <firstname>John</firstname>
             <othername role="MI">L</othername>
             <surname>Hennessy</surname>
           </author>
         </authorgroup>
         <copyright><year>1998</year><holder>Morgan Kaufmann Publishers,
         Inc.</holder></copyright>
         <isbn>1-55860-428-6</isbn>
         <publisher>
           <publishername>Morgan Kaufmann Publishers, Inc.</publishername>
         </publisher>
         <title>Computer Organization and Design</title>
         <subtitle>The Hardware / Software Interface</subtitle>
         <pagenums>1-2</pagenums>
       </biblioentry>
 
       <biblioentry xreflabel="2">
         <authorgroup>
           <author>
             <firstname>W.</firstname>
             <othername role="Middle">Richard</othername>
             <surname>Stevens</surname>
           </author>
         </authorgroup>
         <copyright><year>1993</year><holder>Addison Wesley Longman,
         Inc.</holder></copyright>
         <isbn>0-201-56317-7</isbn>
         <publisher>
           <publishername>Addison Wesley Longman, Inc.</publishername>
         </publisher>
         <title>Advanced Programming in the Unix Environment</title>
         <pagenums>1-2</pagenums>
       </biblioentry>
 
       <biblioentry xreflabel="3">
         <authorgroup>
           <author>
             <firstname>Marshall</firstname>
             <othername role="Middle">Kirk</othername>
             <surname>McKusick</surname>
           </author>
           <author>
             <firstname>Keith</firstname>
             <surname>Bostic</surname>
           </author>
           <author>
             <firstname>Michael</firstname>
             <othername role="MI">J</othername>
             <surname>Karels</surname>
           </author>
           <author>
             <firstname>John</firstname>
             <othername role="MI">S</othername>
             <surname>Quarterman</surname>
           </author>
         </authorgroup>
         <copyright><year>1996</year><holder>Addison-Wesley Publishing Company,
         Inc.</holder></copyright>
         <isbn>0-201-54979-4</isbn>
         <publisher>
           <publishername>Addison-Wesley Publishing Company, Inc.</publishername>
         </publisher>
         <title>The Design and Implementation of the 4.4 BSD Operating System</title>
         <pagenums>1-2</pagenums>
       </biblioentry>
 
       <biblioentry id="Phrack" xreflabel="4">
         <authorgroup>
           <author>
             <firstname>Aleph</firstname>
             <surname>One</surname>
           </author>
         </authorgroup>
         <title>Phrack 49; "Smashing the Stack for Fun and Profit"</title>
       </biblioentry>
 
       <biblioentry id="StackGuard" xreflabel="5">
         <authorgroup>
           <author>
             <firstname>Chrispin</firstname>
             <surname>Cowan</surname>
           </author>
           <author>
             <firstname>Calton</firstname>
             <surname>Pu</surname>
           </author>
           <author>
             <firstname>Dave</firstname>
             <surname>Maier</surname>
           </author>
         </authorgroup>
         <title>StackGuard; Automatic Adaptive Detection and Prevention of
         Buffer-Overflow Attacks</title>
       </biblioentry>
 
       <biblioentry id="OpenBSD" xreflabel="6">
         <authorgroup>
 	  <author>
 	    <firstname>Todd</firstname>
 	    <surname>Miller</surname>
 	  </author>
 	  <author>
 	    <firstname>Theo</firstname>
 	    <surname>de Raadt</surname>
 	  </author>
 	</authorgroup>
 	<title>strlcpy and strlcat -- consistent, safe string copy and
 	concatenation.</title>
       </biblioentry>
 
       </bibliography>
 
   </part>
 
 </book>
diff --git a/en_US.ISO8859-1/books/developers-handbook/chapters.ent b/en_US.ISO8859-1/books/developers-handbook/chapters.ent
index e73ab6af45..c2149880e2 100644
--- a/en_US.ISO8859-1/books/developers-handbook/chapters.ent
+++ b/en_US.ISO8859-1/books/developers-handbook/chapters.ent
@@ -1,57 +1,58 @@
 <!-- 
      Creates entities for each chapter in the FreeBSD Developer's
      Handbook. Each entity is named chap.foo, where foo is the value
      of the id attribute on that chapter, and corresponds to the name of
      the directory in which that chapter's .sgml file is stored.
    
      Chapters should be listed in the order in which they are referenced.
  
-     $FreeBSD:$
+     $FreeBSD: doc/en_US.ISO_8859-1/books/developers-handbook/chapters.ent,v 1.1 2000/11/28 18:03:54 asmodai Exp $
 -->
 
 <!-- Part one -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part two -->
 <!ENTITY chap.tools			SYSTEM "tools/chapter.sgml">
 <!ENTITY chap.secure			SYSTEM "secure/chapter.sgml">
 
 <!-- Part three -->
 <!-- No significant material yet, still in book.sgml -->
+<!ENTITY chap.locking			SYSTEM "locking/chapter.sgml">
 
 <!-- Part four -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part five -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part six -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part seven -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part eight -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part nine -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part ten -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part eleven -->
 <!ENTITY chap.driverbasics		SYSTEM "driverbasics/chapter.sgml">
 <!ENTITY chap.pci			SYSTEM "pci/chapter.sgml">
 
 <!-- Part twelve -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part thirteen -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part fourteen -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part fifteen (appendices) -->
 <!ENTITY chap.bibliography		SYSTEM "bibliography/chapter.sgml">
diff --git a/en_US.ISO8859-1/books/developers-handbook/locking/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/locking/chapter.sgml
new file mode 100644
index 0000000000..54448a06ef
--- /dev/null
+++ b/en_US.ISO8859-1/books/developers-handbook/locking/chapter.sgml
@@ -0,0 +1,312 @@
+<!--
+     The FreeBSD Documentation Project
+     The FreeBSD SMP Next Generation Project
+
+     $FreeBSD$
+-->
+
+<chapter id="locking">
+  <title>Locking Notes</title>
+
+  <para><emphasis>This chapter is maintained by the FreeBSD SMP Next
+    Generation Project
+    <email>freebsd-smp@FreeBSD.org</email>.</emphasis></para>
+
+
+  <para>This document outlines the locking used in the FreeBSD kernel
+    to permit effective multi-processing within the kernel.  Locking
+    can be achieved via several means.  Data structures can be
+    protected by mutexes or &man.lockmgr.9; locks.  A few variables
+    are protected simply by always using atomic operations to access
+    them.</para>
+
+  <sect1>
+    <title>Mutexes</title>
+
+    <para>A mutex is simply a lock used to guarantee mutual exclusion.
+      Specifically, a mutex may only be owned by one entity at a time.
+      If another entity wishes to obtain a mutex that is already
+      owned, it must wait until the mutex is released.  In the FreeBSD
+      kernel, mutexes are owned by processes.</para>
+
+    <para>Mutexes may be recursively acquired, but they are intended
+      to be held for a short period of time.  Specifically, one may
+      not sleep while holding a mutex.  If you need to hold a lock
+      across a sleep, use a &man.lockmgr.9; lock.</para>
+    
+    <para>Each mutex has several properties of interest:</para>
+
+    <variablelist>
+	<varlistentry>
+	<term>Variable Name</term>
+	<listitem>
+	  <para>The name of the <type>struct mtx</type> variable in
+	    the kernel source.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>Logical Name</term>
+	<listitem>
+	  <para>The name of the mutex assigned to it by
+	    <function>mtx_init</function>.  This name is displayed in
+	    KTR trace messages and witness errors and warnings and is
+	    used to distinguish mutexes in the witness code.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>Type</term>
+	<listitem>
+	  <para>The type of the mutex in terms of the
+	    <constant>MTX_*</constant> flags.  The meaning for each
+	    flag is related to its meaning as documented in
+	    &man.mutex.9;.</para>
+
+	  <variablelist>
+	    <varlistentry>
+	      <term><constant>MTX_DEF</constant></term>
+	      <listitem>
+		<para>A sleep mutex</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><constant>MTX_SPIN</constant></term>
+	      <listitem>
+		<para>A spin mutex</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><constant>MTX_COLD</constant></term>
+	      <listitem>
+		<para>This mutex is initialized very early.  Thus, it
+		  must be declared via
+		  <function>MUTEX_DECLARE</function>, and the
+		  <constant>MTX_COLD</constant> flag must be passed to
+		  <function>mtx_init</function>.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><constant>MTX_TOPHALF</constant></term>
+	      <listitem>
+		<para>This spin mutex does not disable
+		  interrupts.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><constant>MTX_NORECURSE</constant></term>
+	      <listitem>
+		<para>This mutex is not allowed to recurse.</para>
+	      </listitem>
+	    </varlistentry>
+	  </variablelist>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>Protectees</term>
+	<listitem>
+	  <para>A list of data structures or data structure members
+	    that this entry protects.  For data structure members, the
+	    name will be in the form of
+	    <structname/structure name/.<structfield/member name/.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>Dependent Functions</term>
+	<listitem>
+	  <para>Functions that can only be called if this mutex is
+	    held.</para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+
+    <table frame="all" colsep="1" rowsep="1" pgwide="1">
+      <title>Mutex List</title>
+      
+      <tgroup cols="5">
+	<thead>
+	  <row>
+	    <entry>Variable Name</entry>
+	    <entry>Logical Name</entry>
+	    <entry>Type</entry>
+	    <entry>Protectees</entry>
+	    <entry>Dependent Functions</entry>
+	  </row>
+	</thead>
+	
+	<!-- The scheduler lock -->
+	<tbody>
+	  <row>
+	    <entry>sched_lock</entry>
+	    <entry><quote>sched lock</quote></entry>
+	    <entry>
+	      <constant>MTX_SPIN</constant> |
+	      <constant>MTX_COLD</constant>
+	    </entry>
+	    <entry>
+	      <varname>_gmonparam</varname>,
+	      <varname>cnt.v_swtch</varname>,
+	      <varname>cp_time</varname>,
+	      <varname>curpriority</varname>,
+	      <structname/mtx/.<structfield/mtx_blocked/,
+	      <structname/mtx/.<structfield/mtx_contested/,
+	      <structname/proc/.<structfield/p_contested/,
+	      <structname/proc/.<structfield/p_blocked/,
+	      <structname/proc/.<structfield/p_flag/
+		(<constant>P_PROFIL</constant> XXX,
+		 <constant>P_INMEM</constant>,
+	         <constant>P_SINTR</constant>,
+	         <constant>P_TIMEOUT</constant>,
+	         <constant>P_SWAPINREQ</constant> XXX,
+	         <constant>P_INMEN</constant> XXX),
+	      <structname/proc/.<structfield/p_nice/,
+	      <structname/proc/.<structfield/p_procq/,
+	      <structname/proc/.<structfield/p_blocked/,
+	      <structname/proc/.<structfield/p_estcpu/,
+	      <structname/proc/.<structfield/p_nativepri/,
+	      <structname/proc/.<structfield/p_priority/,
+	      <structname/proc/.<structfield/p_usrpri/,
+	      <structname/proc/.<structfield/p_rtprio/,
+	      <structname/proc/.<structfield/p_rqindex/,
+	      <structname/proc/.<structfield/p_stats->p_prof/,
+	      <structname/proc/.<structfield/p_stats->p_ru/,
+	      <structname/proc/.<structfield/p_stat/,
+	      <structname/proc/.<structfield/p_cpticks/
+	      <structname/proc/.<structfield/p_iticks/,
+	      <structname/proc/.<structfield/p_uticks/,
+	      <structname/proc/.<structfield/p_sticks/,
+	      <structname/proc/.<structfield/p_swtime/,
+	      <structname/proc/.<structfield/p_slptime/,
+	      <structname/proc/.<structfield/p_runtime/,
+	      <structname/proc/.<structfield/p_pctcpu/,
+	      <structname/proc/.<structfield/p_oncpu/,
+	      <structname/proc/.<structfield/p_asleep/,
+	      <structname/proc/.<structfield/p_wchan/,
+	      <structname/proc/.<structfield/p_wmesg/,
+	      <structname/proc/.<structfield/p_slpq/,
+	      <structname/proc/.<structfield/p_vmspace/
+		(XXX - in <function>statclock</function>),
+	      <varname>pscnt</varname>,
+	      <varname>slpque</varname>,
+	      <varname>itqueuebits</varname>,
+	      <varname>itqueues</varname>,
+	      <varname>rtqueuebits</varname>,
+	      <varname>rtqueues</varname>,
+	      <varname>queuebits</varname>,
+	      <varname>queues</varname>,
+	      <varname>idqueuebits</varname>,
+	      <varname>idqueues</varname>,
+	      <varname>callwheel</varname>,
+	      <varname>nextsoftcheck</varname>,
+	      <varname>switchtime</varname>,
+	      <varname>softticks</varname>,
+	      <varname>ticks</varname>
+	    </entry>
+	    <entry>
+	      <function>setrunqueue</function>,
+	      <function>remrunqueue</function>,
+	      <function>mi_switch</function>,
+	      <function>chooseproc</function>,
+	      <function>schedclock</function>,
+	      <function>resetpriority</function>,
+	      <function>updatepri</function>,
+	      <function>maybe_resched</function>,
+	      <function>cpu_switch</function>,
+	      <function>cpu_throw</function>
+	    </entry>
+	  </row>
+
+	  <!-- The vm86 pcb lock -->
+	  <row>
+	    <entry>vm86pcb_lock</entry>
+	    <entry><quote>vm86pcb lock</quote></entry>
+	    <entry>
+	      <constant>MTX_DEF</constant> |
+	      <constant>MTX_COLD</constant>
+	    </entry>
+	    <entry>
+	      <varname>vm86pcb</varname>
+	    </entry>
+	    <entry>
+	      <function>vm86_bioscall</function>
+	    </entry>
+	  </row>
+
+	  <!-- Giant -->
+	  <row>
+	    <entry>Giant</entry>
+	    <entry><quote>Giant</quote></entry>
+	    <entry>
+	      <constant>MTX_DEF</constant> |
+	      <constant>MTX_COLD</constant>
+	    </entry>
+	    <entry>nearly everything</entry>
+	    <entry>lots</entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </table>
+  </sect1>
+
+  <sect1>
+    <title>Lock Manager Locks</title>
+
+    <para>Locks that are provided via the &man.lockmgr.9; interface
+      are lock manager locks.  These locks are reader-writer locks and
+      may be held by a sleeping process.</para>
+
+    <table>
+      <title>&man.lockmgr.9; Lock List</title>
+
+      <tgroup cols="2">
+	<thead>
+	  <row>
+	    <entry>Variable Name</entry>
+	    <entry>Protectees</entry>
+	  </row>
+	</thead>
+	<tbody>
+	  <row>
+	    <entry><varname>allproc_lock</varname></entry>
+	    <entry>
+	      <varname>allproc</varname>
+	      <varname>zombproc</varname>
+	      <varname>pidhashtbl</varname>
+	      <structname/proc/.<structfield/p_list/
+	      <structname/proc/.<structfield/p_hash/
+	      <varname>nextpid</varname>
+	    </entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </table>
+  </sect1>
+
+  <sect1>
+    <title>Atomically Protected Variables</title>
+
+    <para>An atomically protected variable is a special variable that
+      is not protected by an explicit lock.  Instead, all data
+      accesses to the variables use special atomic operations as
+      described in &man.atomic.9;.  Very few variables are treated
+      this way, although other synchronization primitives such as
+      mutexes are implemented with atomically protected
+      variables.</para>
+
+    <itemizedlist>
+      <listitem>
+	<para><varname>astpending</varname></para>
+      </listitem>
+
+      <listitem>
+	<para><structname/mtx/.<structfield/mtx_lock/</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+</chapter>
diff --git a/en_US.ISO_8859-1/books/developers-handbook/book.sgml b/en_US.ISO_8859-1/books/developers-handbook/book.sgml
index 4e64f19df1..1006c9f5d2 100644
--- a/en_US.ISO_8859-1/books/developers-handbook/book.sgml
+++ b/en_US.ISO_8859-1/books/developers-handbook/book.sgml
@@ -1,515 +1,520 @@
 <!--
      The FreeBSD Documentation Project
 
-     $FreeBSD: doc/en_US.ISO_8859-1/books/developers-handbook/book.sgml,v 1.9 2000/11/28 19:04:02 asmodai Exp $
+     $FreeBSD: doc/en_US.ISO_8859-1/books/developers-handbook/book.sgml,v 1.10 2000/11/28 19:07:40 asmodai Exp $
 -->
 
 <!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [
 <!ENTITY % bookinfo PUBLIC "-//FreeBSD//ENTITIES DocBook BookInfo Entities//EN">
 %bookinfo;
+<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
+%man;
 <!ENTITY % chapters SYSTEM "chapters.ent"> %chapters;
 ]>
 
 <book>
   <bookinfo>
     <title>FreeBSD Developers' Handbook</title>
     
     <authorgroup>
       <author>
 	<surname>The FreeBSD Documentation Project</surname>
         <affiliation>
           <address>
             <email>doc@FreeBSD.org</email>
           </address>
         </affiliation>
       </author>
     </authorgroup>
     
     <pubdate>August 2000</pubdate>
     
     <copyright>
       <year>2000</year>
       <holder>The FreeBSD Documentation Project</holder>
     </copyright>
 
     &bookinfo.legalnotice;
     
     <abstract>
       <para>Welcome to the Developers' Handbook.</para>
     </abstract>
   </bookinfo>
   
   <part id="introduction">
     <title>Introduction</title>
 
     <chapter id="developmentplatform">
       <title>Developing on FreeBSD</title>
 
       <para>This will need to discuss FreeBSD as a development
         platform, the vision of BSD, architectural overview, layout of
         /usr/src, history, etc.</para>
 
       <para>Thank you for considering FreeBSD as your development
         platform!  We hope it will not let you down.</para>
     </chapter>
 
     <chapter id="bsdvision">
       <title>The BSD Vision</title>
 
       <para></para>
     </chapter>
 
     <chapter id="archoverview">
       <title>Architectural Overview</title>
 
       <para></para>
     </chapter>
 
     <chapter id="sourcelayout">
       <title>The Layout of /usr/src</title>
 
       <para>The complete source code to FreeBSD is available from our
       public CVS repository.  The source code is normally installed in
       <filename class=directory>/usr/src</filename> which contains the
       following subdirectories.</para>
 
       <para>
       <informaltable frame="none">
         <tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Directory</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 	  
 	  <tbody>
 	    <row>
 	    <entry><filename class=directory>bin/</filename></entry>
             <entry>Source for files in
             <filename>/bin</filename></entry>
 	    </row>
 	    
 	    <row>
 	    <entry><filename class=directory>contrib/</filename></entry>
 	    <entry>Source for files from contribued software.</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>crypto/</filename></entry>
 	    <entry>DES source</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>etc/</filename></entry>
 	    <entry>Source for files in <filename
 	    class=directory>/etc</filename></entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>games/</filename></entry>
 	    <entry>Source for files in <filename
 	    class=directory>/usr/games</filename></entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>gnu/</filename></entry>
 	    <entry>Utilities covered by the GNU Public License</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>include/</filename></entry>
             <entry>Source for files in <filename
             class=directory>/usr/include</filename></entry>
 	    </row>
 
 	    <row>
 	    <entry><filename
  class=directory>kerberosIV/</filename></entry>
             <entry>Source for Kerbereros version IV</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename
  class=directory>kerberos5/</filename></entry>
             <entry>Source for Kerbereros version 5</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>lib/</filename></entry>
 	    <entry>Source for files in <filename
 	    class=directory>/usr/lib</filename></entry>
 	    </row>
 	    
 	    <row>
 	    <entry><filename class=directory>libexec/</filename></entry>
 	    <entry>Source for files in <filename
 	    class=directory>/usr/libexec</filename></entry>
 	    </row>
 	    
 	    <row>
 	    <entry><filename
  class=directory>release/</filename></entry>
             <entry>Files required to produce a FreeBSD release</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>sbin/</filename></entry>
 	    <entry>Source for files in <filename
 	    class=directory>/sbin</filename></entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>secure/</filename></entry>
 	    <entry>FreeSec sources</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>share/</filename></entry>
 	    <entry>Source for files in <filename
 	    class=directory>/sbin</filename></entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>sys/</filename></entry>
 	    <entry>Kernel source files</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>tools/</filename></entry>
 	    <entry>Tools used for maintenance and testing of
 	    FreeBSD</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename
  class=directory>usr.bin/</filename></entry>
             <entry>Source for files in <filename
  class=directory>/usr/bin</filename></entry>
             </row>
 
 	    <row>
 	    <entry><filename
  class=directory>usr.sbin/</filename></entry>
             <entry>Source for files in <filename
  class=directory>/usr/sbin</filename></entry>
             </row>
           </tbody>
 	</tgroup>
       </informaltable>
 
       </para>
 
     </chapter>
   </part>
 
   <part id="Basics">
     <title>Basics</title>
 
     &chap.tools;
     &chap.secure;
 
   </part>
 
   <part id="kernel">
     <title>Kernel</title>
 
     <chapter id="kernelhistory">
       <title>History of the Unix Kernel</title>
 
       <para>Some history of the Unix/BSD kernel, system calls, how do
         processes work, blocking, scheduling, threads (kernel),
         context switching, signals, interrupts, modules, etc.</para>
 
       <para></para>
     </chapter>
+
+    &chap.locking;
+
   </part>
 
   <part id="memory">
     <title>Memory and Virtual Memory</title>
 
     <chapter id="virtualmemory">
       <title>Virtual Memory</title>
 
       <para>VM, paging, swapping, allocating memory, testing for
         memory leaks, mmap, vnodes, etc.</para>
 
       <para></para>
     </chapter>
   </part>
 
   <part id="iosystem">
     <title>I/O System</title>
 
     <chapter id="ufs">
       <title>UFS</title>
 
       <para>UFS, FFS, Ext2FS, JFS, inodes, buffer cache, labeling,
         locking, metadata, soft-updates, LFS, portalfs, procfs,
         vnodes, memory sharing, memory objects, TLBs, caching</para>
 
     </chapter>
   </part>
 
   <part id="ipc">
     <title>Interprocess Communication</title>
     
     <chapter id="signals">
       <title>Signals</title>
 
       <para>Signals, pipes, semaphores, message queues, shared memory,
         ports, sockets, doors</para>
 
     </chapter>
   </part>
 
   <part id="networking">
     <title>Networking</title>
     
     <chapter id="sockets">
       <title>Sockets</title>
 
       <para>Sockets, bpf, IP, TCP, UDP, ICMP, OSI, bridging,
         firewalling, NAT, switching, etc</para>
 
     </chapter>
   </part>
   
   <part id="networkfs">
     <title>Network Filesystems</title>
 
     <chapter id="afs">
       <title>AFS</title>
 
       <para>AFS, NFS, SANs etc]</para>
 
     </chapter>
   </part>
   
   <part id="terminal">
     <title>Terminal Handling</title>
 
     <chapter id="syscons">
       <title>Syscons</title>
 
       <para>Syscons, tty, PCVT, serial console, screen savers,
         etc</para>
 
     </chapter>
   </part>
   
   <part id="sound">
     <title>Sound</title>
 
     <chapter id="oss">
       <title>OSS</title>
 
       <para>OSS, waveforms, etc</para>
 
     </chapter>
   </part>
   
   <part id="devicedrivers">
     <title>Device Drivers</title>
 
     &chap.driverbasics;
     &chap.pci;
 
     <chapter id="usb">
       <title>USB Devices</title>
 
       <para>This chapter will talk about the FreeBSD mechanisms for
       writing a device driver for a device on a USB bus.</para>
     </chapter>
 
     <chapter id="newbus">
       <title>NewBus</title>
 
       <para>This chapter will talk about the FreeBSD NewBus
       architecture.</para>
     </chapter>
 
   </part>
   
   <part id="architectures">
     <title>Architectures</title>
 
     <chapter id="ia32">
       <title>IA-32</title>
 
       <para>Talk about the architectural specifics of FreeBSD/x86.</para>
 
     </chapter>
 
     <chapter id="alpha">
       <title>Alpha</title>
 
       <para>Talk about the architectural specifics of
       FreeBSD/alpha.</para>
 
       <para>Explanation of allignment errors, how to fix, how to
       ignore.</para>
 
       <para>Example assembly language code for FreeBSD/alpha.</para>
     </chapter>
 
     <chapter id="ia64">
       <title>IA-64</title>
 
       <para>Talk about the architectural specifics of
       FreeBSD/ia64.</para>
 
     </chapter>
   </part>
   
   <part id="debuggingpart">
     <title>Debugging</title>
 
     <chapter id="truss">
       <title>Truss</title>
 
       <para>various descriptions on how to debug certain aspects of
         the system using truss, ktrace, gdb, kgdb, etc</para>
 
     </chapter>
   </part>
   
   <part id="compatibility">
     <title>Compatibility Layers</title>
 
     <chapter id="linux">
       <title>Linux</title>
 
       <para>Linux, SVR4, etc</para>
 
     </chapter>
   </part>
   
   <part id="appendices">
     <title>Appendices</title>
 
       <bibliography>
 
       <biblioentry id="COD" xreflabel="1">
         <authorgroup>
           <author>
             <firstname>Dave</firstname>
             <othername role="MI">A</othername>
             <surname>Patterson</surname>
           </author>
           <author>
             <firstname>John</firstname>
             <othername role="MI">L</othername>
             <surname>Hennessy</surname>
           </author>
         </authorgroup>
         <copyright><year>1998</year><holder>Morgan Kaufmann Publishers,
         Inc.</holder></copyright>
         <isbn>1-55860-428-6</isbn>
         <publisher>
           <publishername>Morgan Kaufmann Publishers, Inc.</publishername>
         </publisher>
         <title>Computer Organization and Design</title>
         <subtitle>The Hardware / Software Interface</subtitle>
         <pagenums>1-2</pagenums>
       </biblioentry>
 
       <biblioentry xreflabel="2">
         <authorgroup>
           <author>
             <firstname>W.</firstname>
             <othername role="Middle">Richard</othername>
             <surname>Stevens</surname>
           </author>
         </authorgroup>
         <copyright><year>1993</year><holder>Addison Wesley Longman,
         Inc.</holder></copyright>
         <isbn>0-201-56317-7</isbn>
         <publisher>
           <publishername>Addison Wesley Longman, Inc.</publishername>
         </publisher>
         <title>Advanced Programming in the Unix Environment</title>
         <pagenums>1-2</pagenums>
       </biblioentry>
 
       <biblioentry xreflabel="3">
         <authorgroup>
           <author>
             <firstname>Marshall</firstname>
             <othername role="Middle">Kirk</othername>
             <surname>McKusick</surname>
           </author>
           <author>
             <firstname>Keith</firstname>
             <surname>Bostic</surname>
           </author>
           <author>
             <firstname>Michael</firstname>
             <othername role="MI">J</othername>
             <surname>Karels</surname>
           </author>
           <author>
             <firstname>John</firstname>
             <othername role="MI">S</othername>
             <surname>Quarterman</surname>
           </author>
         </authorgroup>
         <copyright><year>1996</year><holder>Addison-Wesley Publishing Company,
         Inc.</holder></copyright>
         <isbn>0-201-54979-4</isbn>
         <publisher>
           <publishername>Addison-Wesley Publishing Company, Inc.</publishername>
         </publisher>
         <title>The Design and Implementation of the 4.4 BSD Operating System</title>
         <pagenums>1-2</pagenums>
       </biblioentry>
 
       <biblioentry id="Phrack" xreflabel="4">
         <authorgroup>
           <author>
             <firstname>Aleph</firstname>
             <surname>One</surname>
           </author>
         </authorgroup>
         <title>Phrack 49; "Smashing the Stack for Fun and Profit"</title>
       </biblioentry>
 
       <biblioentry id="StackGuard" xreflabel="5">
         <authorgroup>
           <author>
             <firstname>Chrispin</firstname>
             <surname>Cowan</surname>
           </author>
           <author>
             <firstname>Calton</firstname>
             <surname>Pu</surname>
           </author>
           <author>
             <firstname>Dave</firstname>
             <surname>Maier</surname>
           </author>
         </authorgroup>
         <title>StackGuard; Automatic Adaptive Detection and Prevention of
         Buffer-Overflow Attacks</title>
       </biblioentry>
 
       <biblioentry id="OpenBSD" xreflabel="6">
         <authorgroup>
 	  <author>
 	    <firstname>Todd</firstname>
 	    <surname>Miller</surname>
 	  </author>
 	  <author>
 	    <firstname>Theo</firstname>
 	    <surname>de Raadt</surname>
 	  </author>
 	</authorgroup>
 	<title>strlcpy and strlcat -- consistent, safe string copy and
 	concatenation.</title>
       </biblioentry>
 
       </bibliography>
 
   </part>
 
 </book>
diff --git a/en_US.ISO_8859-1/books/developers-handbook/chapters.ent b/en_US.ISO_8859-1/books/developers-handbook/chapters.ent
index e73ab6af45..c2149880e2 100644
--- a/en_US.ISO_8859-1/books/developers-handbook/chapters.ent
+++ b/en_US.ISO_8859-1/books/developers-handbook/chapters.ent
@@ -1,57 +1,58 @@
 <!-- 
      Creates entities for each chapter in the FreeBSD Developer's
      Handbook. Each entity is named chap.foo, where foo is the value
      of the id attribute on that chapter, and corresponds to the name of
      the directory in which that chapter's .sgml file is stored.
    
      Chapters should be listed in the order in which they are referenced.
  
-     $FreeBSD:$
+     $FreeBSD: doc/en_US.ISO_8859-1/books/developers-handbook/chapters.ent,v 1.1 2000/11/28 18:03:54 asmodai Exp $
 -->
 
 <!-- Part one -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part two -->
 <!ENTITY chap.tools			SYSTEM "tools/chapter.sgml">
 <!ENTITY chap.secure			SYSTEM "secure/chapter.sgml">
 
 <!-- Part three -->
 <!-- No significant material yet, still in book.sgml -->
+<!ENTITY chap.locking			SYSTEM "locking/chapter.sgml">
 
 <!-- Part four -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part five -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part six -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part seven -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part eight -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part nine -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part ten -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part eleven -->
 <!ENTITY chap.driverbasics		SYSTEM "driverbasics/chapter.sgml">
 <!ENTITY chap.pci			SYSTEM "pci/chapter.sgml">
 
 <!-- Part twelve -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part thirteen -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part fourteen -->
 <!-- No significant material yet, still in book.sgml -->
 
 <!-- Part fifteen (appendices) -->
 <!ENTITY chap.bibliography		SYSTEM "bibliography/chapter.sgml">
diff --git a/en_US.ISO_8859-1/books/developers-handbook/locking/chapter.sgml b/en_US.ISO_8859-1/books/developers-handbook/locking/chapter.sgml
new file mode 100644
index 0000000000..54448a06ef
--- /dev/null
+++ b/en_US.ISO_8859-1/books/developers-handbook/locking/chapter.sgml
@@ -0,0 +1,312 @@
+<!--
+     The FreeBSD Documentation Project
+     The FreeBSD SMP Next Generation Project
+
+     $FreeBSD$
+-->
+
+<chapter id="locking">
+  <title>Locking Notes</title>
+
+  <para><emphasis>This chapter is maintained by the FreeBSD SMP Next
+    Generation Project
+    <email>freebsd-smp@FreeBSD.org</email>.</emphasis></para>
+
+
+  <para>This document outlines the locking used in the FreeBSD kernel
+    to permit effective multi-processing within the kernel.  Locking
+    can be achieved via several means.  Data structures can be
+    protected by mutexes or &man.lockmgr.9; locks.  A few variables
+    are protected simply by always using atomic operations to access
+    them.</para>
+
+  <sect1>
+    <title>Mutexes</title>
+
+    <para>A mutex is simply a lock used to guarantee mutual exclusion.
+      Specifically, a mutex may only be owned by one entity at a time.
+      If another entity wishes to obtain a mutex that is already
+      owned, it must wait until the mutex is released.  In the FreeBSD
+      kernel, mutexes are owned by processes.</para>
+
+    <para>Mutexes may be recursively acquired, but they are intended
+      to be held for a short period of time.  Specifically, one may
+      not sleep while holding a mutex.  If you need to hold a lock
+      across a sleep, use a &man.lockmgr.9; lock.</para>
+    
+    <para>Each mutex has several properties of interest:</para>
+
+    <variablelist>
+	<varlistentry>
+	<term>Variable Name</term>
+	<listitem>
+	  <para>The name of the <type>struct mtx</type> variable in
+	    the kernel source.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>Logical Name</term>
+	<listitem>
+	  <para>The name of the mutex assigned to it by
+	    <function>mtx_init</function>.  This name is displayed in
+	    KTR trace messages and witness errors and warnings and is
+	    used to distinguish mutexes in the witness code.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>Type</term>
+	<listitem>
+	  <para>The type of the mutex in terms of the
+	    <constant>MTX_*</constant> flags.  The meaning for each
+	    flag is related to its meaning as documented in
+	    &man.mutex.9;.</para>
+
+	  <variablelist>
+	    <varlistentry>
+	      <term><constant>MTX_DEF</constant></term>
+	      <listitem>
+		<para>A sleep mutex</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><constant>MTX_SPIN</constant></term>
+	      <listitem>
+		<para>A spin mutex</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><constant>MTX_COLD</constant></term>
+	      <listitem>
+		<para>This mutex is initialized very early.  Thus, it
+		  must be declared via
+		  <function>MUTEX_DECLARE</function>, and the
+		  <constant>MTX_COLD</constant> flag must be passed to
+		  <function>mtx_init</function>.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><constant>MTX_TOPHALF</constant></term>
+	      <listitem>
+		<para>This spin mutex does not disable
+		  interrupts.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><constant>MTX_NORECURSE</constant></term>
+	      <listitem>
+		<para>This mutex is not allowed to recurse.</para>
+	      </listitem>
+	    </varlistentry>
+	  </variablelist>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>Protectees</term>
+	<listitem>
+	  <para>A list of data structures or data structure members
+	    that this entry protects.  For data structure members, the
+	    name will be in the form of
+	    <structname/structure name/.<structfield/member name/.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>Dependent Functions</term>
+	<listitem>
+	  <para>Functions that can only be called if this mutex is
+	    held.</para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+
+    <table frame="all" colsep="1" rowsep="1" pgwide="1">
+      <title>Mutex List</title>
+      
+      <tgroup cols="5">
+	<thead>
+	  <row>
+	    <entry>Variable Name</entry>
+	    <entry>Logical Name</entry>
+	    <entry>Type</entry>
+	    <entry>Protectees</entry>
+	    <entry>Dependent Functions</entry>
+	  </row>
+	</thead>
+	
+	<!-- The scheduler lock -->
+	<tbody>
+	  <row>
+	    <entry>sched_lock</entry>
+	    <entry><quote>sched lock</quote></entry>
+	    <entry>
+	      <constant>MTX_SPIN</constant> |
+	      <constant>MTX_COLD</constant>
+	    </entry>
+	    <entry>
+	      <varname>_gmonparam</varname>,
+	      <varname>cnt.v_swtch</varname>,
+	      <varname>cp_time</varname>,
+	      <varname>curpriority</varname>,
+	      <structname/mtx/.<structfield/mtx_blocked/,
+	      <structname/mtx/.<structfield/mtx_contested/,
+	      <structname/proc/.<structfield/p_contested/,
+	      <structname/proc/.<structfield/p_blocked/,
+	      <structname/proc/.<structfield/p_flag/
+		(<constant>P_PROFIL</constant> XXX,
+		 <constant>P_INMEM</constant>,
+	         <constant>P_SINTR</constant>,
+	         <constant>P_TIMEOUT</constant>,
+	         <constant>P_SWAPINREQ</constant> XXX,
+	         <constant>P_INMEN</constant> XXX),
+	      <structname/proc/.<structfield/p_nice/,
+	      <structname/proc/.<structfield/p_procq/,
+	      <structname/proc/.<structfield/p_blocked/,
+	      <structname/proc/.<structfield/p_estcpu/,
+	      <structname/proc/.<structfield/p_nativepri/,
+	      <structname/proc/.<structfield/p_priority/,
+	      <structname/proc/.<structfield/p_usrpri/,
+	      <structname/proc/.<structfield/p_rtprio/,
+	      <structname/proc/.<structfield/p_rqindex/,
+	      <structname/proc/.<structfield/p_stats->p_prof/,
+	      <structname/proc/.<structfield/p_stats->p_ru/,
+	      <structname/proc/.<structfield/p_stat/,
+	      <structname/proc/.<structfield/p_cpticks/
+	      <structname/proc/.<structfield/p_iticks/,
+	      <structname/proc/.<structfield/p_uticks/,
+	      <structname/proc/.<structfield/p_sticks/,
+	      <structname/proc/.<structfield/p_swtime/,
+	      <structname/proc/.<structfield/p_slptime/,
+	      <structname/proc/.<structfield/p_runtime/,
+	      <structname/proc/.<structfield/p_pctcpu/,
+	      <structname/proc/.<structfield/p_oncpu/,
+	      <structname/proc/.<structfield/p_asleep/,
+	      <structname/proc/.<structfield/p_wchan/,
+	      <structname/proc/.<structfield/p_wmesg/,
+	      <structname/proc/.<structfield/p_slpq/,
+	      <structname/proc/.<structfield/p_vmspace/
+		(XXX - in <function>statclock</function>),
+	      <varname>pscnt</varname>,
+	      <varname>slpque</varname>,
+	      <varname>itqueuebits</varname>,
+	      <varname>itqueues</varname>,
+	      <varname>rtqueuebits</varname>,
+	      <varname>rtqueues</varname>,
+	      <varname>queuebits</varname>,
+	      <varname>queues</varname>,
+	      <varname>idqueuebits</varname>,
+	      <varname>idqueues</varname>,
+	      <varname>callwheel</varname>,
+	      <varname>nextsoftcheck</varname>,
+	      <varname>switchtime</varname>,
+	      <varname>softticks</varname>,
+	      <varname>ticks</varname>
+	    </entry>
+	    <entry>
+	      <function>setrunqueue</function>,
+	      <function>remrunqueue</function>,
+	      <function>mi_switch</function>,
+	      <function>chooseproc</function>,
+	      <function>schedclock</function>,
+	      <function>resetpriority</function>,
+	      <function>updatepri</function>,
+	      <function>maybe_resched</function>,
+	      <function>cpu_switch</function>,
+	      <function>cpu_throw</function>
+	    </entry>
+	  </row>
+
+	  <!-- The vm86 pcb lock -->
+	  <row>
+	    <entry>vm86pcb_lock</entry>
+	    <entry><quote>vm86pcb lock</quote></entry>
+	    <entry>
+	      <constant>MTX_DEF</constant> |
+	      <constant>MTX_COLD</constant>
+	    </entry>
+	    <entry>
+	      <varname>vm86pcb</varname>
+	    </entry>
+	    <entry>
+	      <function>vm86_bioscall</function>
+	    </entry>
+	  </row>
+
+	  <!-- Giant -->
+	  <row>
+	    <entry>Giant</entry>
+	    <entry><quote>Giant</quote></entry>
+	    <entry>
+	      <constant>MTX_DEF</constant> |
+	      <constant>MTX_COLD</constant>
+	    </entry>
+	    <entry>nearly everything</entry>
+	    <entry>lots</entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </table>
+  </sect1>
+
+  <sect1>
+    <title>Lock Manager Locks</title>
+
+    <para>Locks that are provided via the &man.lockmgr.9; interface
+      are lock manager locks.  These locks are reader-writer locks and
+      may be held by a sleeping process.</para>
+
+    <table>
+      <title>&man.lockmgr.9; Lock List</title>
+
+      <tgroup cols="2">
+	<thead>
+	  <row>
+	    <entry>Variable Name</entry>
+	    <entry>Protectees</entry>
+	  </row>
+	</thead>
+	<tbody>
+	  <row>
+	    <entry><varname>allproc_lock</varname></entry>
+	    <entry>
+	      <varname>allproc</varname>
+	      <varname>zombproc</varname>
+	      <varname>pidhashtbl</varname>
+	      <structname/proc/.<structfield/p_list/
+	      <structname/proc/.<structfield/p_hash/
+	      <varname>nextpid</varname>
+	    </entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </table>
+  </sect1>
+
+  <sect1>
+    <title>Atomically Protected Variables</title>
+
+    <para>An atomically protected variable is a special variable that
+      is not protected by an explicit lock.  Instead, all data
+      accesses to the variables use special atomic operations as
+      described in &man.atomic.9;.  Very few variables are treated
+      this way, although other synchronization primitives such as
+      mutexes are implemented with atomically protected
+      variables.</para>
+
+    <itemizedlist>
+      <listitem>
+	<para><varname>astpending</varname></para>
+      </listitem>
+
+      <listitem>
+	<para><structname/mtx/.<structfield/mtx_lock/</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+</chapter>