Index: article.sgml
===================================================================
RCS file: /home/ncvs/doc/en_US.ISO8859-1/articles/smp/article.sgml,v
retrieving revision 1.3
diff -u -r1.3 article.sgml
--- article.sgml	2002/12/07 14:25:25	1.3
+++ article.sgml	2002/12/12 19:26:27
@@ -4,6 +4,8 @@
 
 <!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN">
 %authors;
+<!ENTITY % misc PUBLIC "-//FreeBSD//ENTITIES DocBook Miscellaneous FreeBSD Entities//EN">
+%misc;
 
 <!--ENTITY % mailing-lists PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//EN"-->
 <!--
@@ -52,7 +54,7 @@
   <sect1>
     <title>Introduction</title>
 
-    <para> This document is a work-in-progress, and will be updated to
+    <para>This document is a work-in-progress, and will be updated to
       reflect on-going design and implementation activities associated
       with the SMPng Project.  Many sections currently exist only in
       outline form, but will be fleshed out as work proceeds.  Updates or
@@ -63,9 +65,9 @@
       The kernel is basically one rather large and complex program. To
       make the kernel multi-threaded we use some of the same tools used
       to make other programs multi-threaded.  These include mutexes,
-      shared/exclusive locks, semaphores, and condition variables.  For
-      definitions of many of the terms, please see
-      <xref linkend="defs">.</para>
+      shared/exclusive locks, semaphores, and condition variables.  Please
+      see the <xref linkend="glossary"> section of this article, to acquaint
+      yourself with SMP and related terminology.</para>
   </sect1>
 
   <sect1>
@@ -347,7 +349,7 @@
       <sect3>
 	<title>Design Tradeoffs</title>
 
-	<para>As mentioned earlier, a couple of tradeoffs have been
+	<para>As mentioned earlier, a couple of trade-offs have been
 	  made to sacrifice cases where perfect preemption may not
 	  always provide the best performance.</para>
 
@@ -366,7 +368,7 @@
 	  position as CPU B is executing a thread of priority 1 rather
 	  than a thread of priority 2.</para>
 
-	<para>The second tradeoff limits immediate kernel preemption
+	<para>The second trade-off limits immediate kernel preemption
 	  to real-time priority kernel threads.  In the simple case of
 	  preemption defined above, a thread is always preempted
 	  immediately (or as soon as a critical section is exited) if
@@ -493,12 +495,12 @@
     <sect2>
       <title>Credentials</title>
 
-      <para><structname>struct ucred</structname> is the system
+      <para><structname>struct ucred</structname> is the system's
 	internal credential structure, and is generally used as the
-	basis for process-driven access control.  BSD-derived systems
-	use a "copy-on-write" model for credential data: multiple
-	references may exist for a credential structure, and when a
-	change needs to be made, the structure is duplicated,
+	basis for process-driven access control within the kernel.  
+	BSD-derived systems use a "copy-on-write" model for credential 
+	data: multiple references may exist for a credential structure, 
+	and when a change needs to be made, the structure is duplicated,
 	modified, and then the reference replaced.  Due to wide-spread
 	caching of the credential to implement access control on open,
 	this results in substantial memory savings.  With a move to
@@ -512,7 +514,7 @@
 	considered mutable; shared credential structures must not be  
 	modified or a race condition is risked.  A mutex,
 	<structfield>cr_mtxp</structfield> protects the reference 
-	count of the <structname>struct ucred</structname> so as to
+	count of <structname>struct ucred</structname> so as to
 	maintain consistency.  Any use of the structure requires a
 	valid reference for the duration of the use, or the structure
 	may be released out from under the illegitimate
@@ -521,6 +523,21 @@
       <para>The <structname>struct ucred</structname> mutex is a leaf
 	mutex, and for performance reasons, is implemented via a mutex
 	pool.</para>
+
+      <para>Usually, credentials are used in a read-only manner for access
+        control decisions, and in this case <structfield>td_ucred</structfield>
+	is used because it requires no locking.  When a process' credential is
+	updated the <literal>proc</literal> lock must be held across the check
+	and update operations thus avoid races.  The process credential
+	<structfield>p_ucred</structfield> must be used for check and update
+	operations.</para>
+
+      <para>System calls will need to refresh <structname>td_ucred</structname>
+       if the credentials are going to change; the system call handler
+       automatically refreshes on entry to the system call for other
+       situations.  Functions such as &man.suser.9; use
+       <structfield>td_ucred</structfield> unless explicitly specified by
+       using <function>suser_cred()</function>.</para>
     </sect2>
 
     <sect2>
@@ -544,7 +561,7 @@
 	when the jail is created, and a valid reference to the
 	<structname>struct prison</structname> is sufficient to read
 	these values.  The precise locking of each entry is documented
-	via comments in jail.h.</para>
+	via comments in <filename>sys/jail.h</filename>.</para>
     </sect2>
 
     <sect2>
@@ -607,9 +624,10 @@
       <title>Newbus Device Tree</title>
 
       <para>The newbus system will have one sx lock.  Readers will
-	lock it &man.sx.slock.9; and writers will lock it
-	&man.sx.xlock.9;.  Internal only functions will not do locking
-	at all.  The externally visible ones will lock as needed.
+	hold a shared (read) lock (&man.sx.slock.9;) and writers will hold
+	an exclusive (write) lock (&man.sx.xlock.9;).  Internal functions 
+	will not do locking at all.  Externally visible ones will lock as 
+	needed.
 	Those items that don't matter if the race is won or lost will
 	not be locked, since they tend to be read all over the place
 	(e.g. &man.device.get.softc.9;).  There will be relatively few
@@ -807,8 +825,8 @@
     </sect2>
   </sect1>
 
-  <glossary id="defs">
-    <title>Definitions</title>
+  <glossary id="glossary">
+    <title>Glossary</title>
 
     <glossentry id="atomic">
       <glossterm>atomic</glossterm>