os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Minor documentation tweaks:

Browse source 
Remove some excess whitespace. (hmp)
Hyphenate trade-off. (hmp)
Rename "Definitions" to "Glossary. (hmp)
Mark up file names and structure fields better. (hmp)
Improve documentation of credential handling semantics. (rwatson)

Portions submitted by:	Hiten Pandya <hiten@unixdaemons.com>
This commit is contained in:
Robert Watson 2002-12-19 02:21:12 +00:00
parent 5fb7901b07
commit 5b857d074e
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=15383
2 changed files with 80 additions and 34 deletions
en_US.ISO8859-1
articles/smp
article.sgml
books/arch-handbook/smp
chapter.sgml

57
en_US.ISO8859-1/articles/smp/article.sgml
View file

@ -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
@ -64,8 +66,8 @@
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>
the definitions of these and other SMP-related terms, please see
the <xref linkend="glossary"> section of this article.</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 kernels'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,26 @@
<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 generally preferred 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 to prevent
time-of-check, time-of-use races.</para>
<para>If system call invocations will perform access control after
an update to the process credential, the value of
<structfield>td_ucred</structfield> must also be refreshed to
the current process value. This will prevent use of a stale
credential following a change. The kernel automatically
refreshes the <structfield>td_ucred</structfield> pointer in
the thread structure from the process
<structfield>p_ucred</structfield> whenever a process enters
the kernel, permitting use of a fresh credential for kernel
access control.</para>
</sect2>
<sect2>
@ -544,7 +566,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 +629,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 +830,8 @@
</sect2>
</sect1>
<glossary id="defs">
<title>Definitions</title>
<glossary id="glossary">
<title>Glossary</title>
<glossentry id="atomic">
<glossterm>atomic</glossterm>

57
en_US.ISO8859-1/books/arch-handbook/smp/chapter.sgml
View file

@ -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
@ -64,8 +66,8 @@
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>
the definitions of these and other SMP-related terms, please see
the <xref linkend="glossary"> section of this article.</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 kernels'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,26 @@
<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 generally preferred 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 to prevent
time-of-check, time-of-use races.</para>
<para>If system call invocations will perform access control after
an update to the process credential, the value of
<structfield>td_ucred</structfield> must also be refreshed to
the current process value. This will prevent use of a stale
credential following a change. The kernel automatically
refreshes the <structfield>td_ucred</structfield> pointer in
the thread structure from the process
<structfield>p_ucred</structfield> whenever a process enters
the kernel, permitting use of a fresh credential for kernel
access control.</para>
</sect2>
<sect2>
@ -544,7 +566,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 +629,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 +830,8 @@
</sect2>
</sect1>
<glossary id="defs">
<title>Definitions</title>
<glossary id="glossary">
<title>Glossary</title>
<glossentry id="atomic">
<glossterm>atomic</glossterm>