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
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -4,6 +4,8 @@
<!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN"> <!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN">
%authors; %authors;
<!ENTITY % misc PUBLIC "-//FreeBSD//ENTITIES DocBook Miscellaneous FreeBSD Entities//EN">
%misc;
<!--ENTITY % mailing-lists PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//EN"--> <!--ENTITY % mailing-lists PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//EN"-->
<!-- <!--
@ -52,7 +54,7 @@
<sect1> <sect1>
<title>Introduction</title> <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 reflect on-going design and implementation activities associated
with the SMPng Project. Many sections currently exist only in with the SMPng Project. Many sections currently exist only in
outline form, but will be fleshed out as work proceeds. Updates or 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 make the kernel multi-threaded we use some of the same tools used
to make other programs multi-threaded. These include mutexes, to make other programs multi-threaded. These include mutexes,
shared/exclusive locks, semaphores, and condition variables. For shared/exclusive locks, semaphores, and condition variables. For
definitions of many of the terms, please see the definitions of these and other SMP-related terms, please see
<xref linkend="defs">.</para> the <xref linkend="glossary"> section of this article.</para>
</sect1> </sect1>
<sect1> <sect1>
@ -347,7 +349,7 @@
<sect3> <sect3>
<title>Design Tradeoffs</title> <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 made to sacrifice cases where perfect preemption may not
always provide the best performance.</para> always provide the best performance.</para>
@ -366,7 +368,7 @@
position as CPU B is executing a thread of priority 1 rather position as CPU B is executing a thread of priority 1 rather
than a thread of priority 2.</para> 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 to real-time priority kernel threads. In the simple case of
preemption defined above, a thread is always preempted preemption defined above, a thread is always preempted
immediately (or as soon as a critical section is exited) if immediately (or as soon as a critical section is exited) if
@ -493,12 +495,12 @@
<sect2> <sect2>
<title>Credentials</title> <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 internal credential structure, and is generally used as the
basis for process-driven access control. BSD-derived systems basis for process-driven access control within the kernel.
use a "copy-on-write" model for credential data: multiple BSD-derived systems use a "copy-on-write" model for credential
references may exist for a credential structure, and when a data: multiple references may exist for a credential structure,
change needs to be made, the structure is duplicated, and when a change needs to be made, the structure is duplicated,
modified, and then the reference replaced. Due to wide-spread modified, and then the reference replaced. Due to wide-spread
caching of the credential to implement access control on open, caching of the credential to implement access control on open,
this results in substantial memory savings. With a move to this results in substantial memory savings. With a move to
@ -512,7 +514,7 @@
considered mutable; shared credential structures must not be considered mutable; shared credential structures must not be
modified or a race condition is risked. A mutex, modified or a race condition is risked. A mutex,
<structfield>cr_mtxp</structfield> protects the reference <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 maintain consistency. Any use of the structure requires a
valid reference for the duration of the use, or the structure valid reference for the duration of the use, or the structure
may be released out from under the illegitimate may be released out from under the illegitimate
@ -521,6 +523,26 @@
<para>The <structname>struct ucred</structname> mutex is a leaf <para>The <structname>struct ucred</structname> mutex is a leaf
mutex, and for performance reasons, is implemented via a mutex mutex, and for performance reasons, is implemented via a mutex
pool.</para> 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>
<sect2> <sect2>
@ -544,7 +566,7 @@
when the jail is created, and a valid reference to the when the jail is created, and a valid reference to the
<structname>struct prison</structname> is sufficient to read <structname>struct prison</structname> is sufficient to read
these values. The precise locking of each entry is documented 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>
<sect2> <sect2>
@ -607,9 +629,10 @@
<title>Newbus Device Tree</title> <title>Newbus Device Tree</title>
<para>The newbus system will have one sx lock. Readers will <para>The newbus system will have one sx lock. Readers will
lock it &man.sx.slock.9; and writers will lock it hold a shared (read) lock (&man.sx.slock.9;) and writers will hold
&man.sx.xlock.9;. Internal only functions will not do locking an exclusive (write) lock (&man.sx.xlock.9;). Internal functions
at all. The externally visible ones will lock as needed. 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 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 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 (e.g. &man.device.get.softc.9;). There will be relatively few
@ -807,8 +830,8 @@
</sect2> </sect2>
</sect1> </sect1>
<glossary id="defs"> <glossary id="glossary">
<title>Definitions</title> <title>Glossary</title>
<glossentry id="atomic"> <glossentry id="atomic">
<glossterm>atomic</glossterm> <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"> <!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN">
%authors; %authors;
<!ENTITY % misc PUBLIC "-//FreeBSD//ENTITIES DocBook Miscellaneous FreeBSD Entities//EN">
%misc;
<!--ENTITY % mailing-lists PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//EN"--> <!--ENTITY % mailing-lists PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//EN"-->
<!-- <!--
@ -52,7 +54,7 @@
<sect1> <sect1>
<title>Introduction</title> <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 reflect on-going design and implementation activities associated
with the SMPng Project. Many sections currently exist only in with the SMPng Project. Many sections currently exist only in
outline form, but will be fleshed out as work proceeds. Updates or 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 make the kernel multi-threaded we use some of the same tools used
to make other programs multi-threaded. These include mutexes, to make other programs multi-threaded. These include mutexes,
shared/exclusive locks, semaphores, and condition variables. For shared/exclusive locks, semaphores, and condition variables. For
definitions of many of the terms, please see the definitions of these and other SMP-related terms, please see
<xref linkend="defs">.</para> the <xref linkend="glossary"> section of this article.</para>
</sect1> </sect1>
<sect1> <sect1>
@ -347,7 +349,7 @@
<sect3> <sect3>
<title>Design Tradeoffs</title> <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 made to sacrifice cases where perfect preemption may not
always provide the best performance.</para> always provide the best performance.</para>
@ -366,7 +368,7 @@
position as CPU B is executing a thread of priority 1 rather position as CPU B is executing a thread of priority 1 rather
than a thread of priority 2.</para> 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 to real-time priority kernel threads. In the simple case of
preemption defined above, a thread is always preempted preemption defined above, a thread is always preempted
immediately (or as soon as a critical section is exited) if immediately (or as soon as a critical section is exited) if
@ -493,12 +495,12 @@
<sect2> <sect2>
<title>Credentials</title> <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 internal credential structure, and is generally used as the
basis for process-driven access control. BSD-derived systems basis for process-driven access control within the kernel.
use a "copy-on-write" model for credential data: multiple BSD-derived systems use a "copy-on-write" model for credential
references may exist for a credential structure, and when a data: multiple references may exist for a credential structure,
change needs to be made, the structure is duplicated, and when a change needs to be made, the structure is duplicated,
modified, and then the reference replaced. Due to wide-spread modified, and then the reference replaced. Due to wide-spread
caching of the credential to implement access control on open, caching of the credential to implement access control on open,
this results in substantial memory savings. With a move to this results in substantial memory savings. With a move to
@ -512,7 +514,7 @@
considered mutable; shared credential structures must not be considered mutable; shared credential structures must not be
modified or a race condition is risked. A mutex, modified or a race condition is risked. A mutex,
<structfield>cr_mtxp</structfield> protects the reference <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 maintain consistency. Any use of the structure requires a
valid reference for the duration of the use, or the structure valid reference for the duration of the use, or the structure
may be released out from under the illegitimate may be released out from under the illegitimate
@ -521,6 +523,26 @@
<para>The <structname>struct ucred</structname> mutex is a leaf <para>The <structname>struct ucred</structname> mutex is a leaf
mutex, and for performance reasons, is implemented via a mutex mutex, and for performance reasons, is implemented via a mutex
pool.</para> 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>
<sect2> <sect2>
@ -544,7 +566,7 @@
when the jail is created, and a valid reference to the when the jail is created, and a valid reference to the
<structname>struct prison</structname> is sufficient to read <structname>struct prison</structname> is sufficient to read
these values. The precise locking of each entry is documented 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>
<sect2> <sect2>
@ -607,9 +629,10 @@
<title>Newbus Device Tree</title> <title>Newbus Device Tree</title>
<para>The newbus system will have one sx lock. Readers will <para>The newbus system will have one sx lock. Readers will
lock it &man.sx.slock.9; and writers will lock it hold a shared (read) lock (&man.sx.slock.9;) and writers will hold
&man.sx.xlock.9;. Internal only functions will not do locking an exclusive (write) lock (&man.sx.xlock.9;). Internal functions
at all. The externally visible ones will lock as needed. 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 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 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 (e.g. &man.device.get.softc.9;). There will be relatively few
@ -807,8 +830,8 @@
</sect2> </sect2>
</sect1> </sect1>
<glossary id="defs"> <glossary id="glossary">
<title>Definitions</title> <title>Glossary</title>
<glossentry id="atomic"> <glossentry id="atomic">
<glossterm>atomic</glossterm> <glossterm>atomic</glossterm>