svn commit: r203825 - head/share/man/man9

[Edward Tomasz Napierala]

Author: trasz
Date: Sat Feb 13 12:03:03 2010
New Revision: 203825
URL: http://svn.freebsd.org/changeset/base/203825

Log:
  Remove list of locking primitives, which is kind of redundant, move
  information about witness(9) to the section about interactions, and
  expand 'contexts' table.

Modified:
  head/share/man/man9/locking.9

Modified: head/share/man/man9/locking.9
==============================================================================
--- head/share/man/man9/locking.9	Sat Feb 13 11:54:01 2010	(r203824)
+++ head/share/man/man9/locking.9	Sat Feb 13 12:03:03 2010	(r203825)
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd February 10, 2010
+.Dd February 13, 2010
 .Dt LOCKING 9
 .Os
 .Sh NAME
@@ -36,41 +36,9 @@ The
 kernel is written to run across multiple CPUs and as such requires
 several different synchronization primitives to allow the developers
 to safely access and manipulate the many data types required.
-.Pp
-These include:
-.Bl -enum
-.It
-Mutexes
-.It
-Spin mutexes
-.It
-Pool mutexes
-.It
-Shared/exclusive locks
-.It
-Reader/writer locks
-.It
-Read-mostly locks
-.It
-Counting semaphores
-.It
-Condition variables
-.It
-Sleep/wakeup
-.It
-Giant
-.It
-Lockmanager locks
-.El
-.Pp
-The primitives interact and have a number of rules regarding how
-they can and can not be combined.
-Many of these rules are checked using the
-.Xr witness 4
-code.
-.Pp
 .Ss Mutexes
-Mutexes are the most commonly used synchronization primitive in the kernel.
+Mutexes (also called "sleep mutexes") are the most commonly used
+synchronization primitive in the kernel.
 Thread acquires (locks) a mutex before accessing data shared with other
 threads (including interrupt threads), and releases (unlocks) it afterwards.
 If the mutex cannot be acquired, the thread requesting it will sleep.
@@ -85,12 +53,10 @@ the two is that spin mutexes never sleep
 for the thread holding the lock, which runs on another CPU, to release it.
 Differently from ordinary mutex, spin mutexes disable interrupts when acquired.
 Since disabling interrupts is expensive, they are also generally slower.
-Spin mutexes should only be used to protect data shared with primary
-(INTR_FILTER) interrupt code.
-You 
-.Em must not
-do anything that deschedules the thread while you
-are holding a spin mutex.
+Spin mutexes should be used only when neccessary, e.g. to protect data shared
+with interrupt filter code (see
+.Xr bus_setup_intr 9
+for details).
 .Ss Pool mutexes
 With most synchronisaton primitives, such as mutexes, programmer must
 provide a piece of allocated memory to hold the primitive.
@@ -284,6 +250,11 @@ See
 .Xr lock 9
 for details.
 .Sh INTERACTIONS
+The primitives interact and have a number of rules regarding how
+they can and can not be combined.
+Many of these rules are checked using the
+.Xr witness 4
+code.
 .Ss Bounded vs. unbounded sleep
 The following primitives perform bounded sleep: mutexes, pool mutexes,
 reader/writer locks and read-mostly locks.
@@ -320,21 +291,23 @@ rwlock, your sleep, will cause a panic.
 If the sleep only happens rarely it may be years before the 
 bad code path is found.
 .Pp
+It is an error to do any operation that could result in any kind of sleep when
+running inside an interrupt filter.
+.Pp
 It is an error to do any operation that could result in unbounded sleep when
 running inside an interrupt thread.
 .Ss Interaction table
-The following table shows what you can and can not do if you hold
-one of the synchronization primitives discussed here:
-(someone who knows what they are talking about should write this table)
+The following table shows what you can and can not do while holding
+one of the synchronization primitives discussed:
 .Bl -column ".Ic xxxxxxxxxxxxxxxxxxx" ".Xr XXXXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXX" -offset indent
 .It Xo
 .Em "You have: You want:" Ta spin mtx Ta mutex Ta sx Ta rwlock Ta rmlock Ta sleep
 .Xc
-.It Ic spin mtx  Ta \&ok-1 Ta \&no Ta \&no Ta \&no Ta \&no Ta \&no-3
-.It Ic mutex     Ta \&ok Ta \&ok-1 Ta \&no Ta \&ok Ta \&ok Ta \&no-3
-.It Ic sx        Ta \&ok Ta \&ok Ta \&ok-2 Ta \&ok Ta \&ok Ta \&ok-4
-.It Ic rwlock    Ta \&ok Ta \&ok Ta \&no Ta \&ok-2 Ta \&ok Ta \&no-3
-.It Ic rmlock    Ta \&ok Ta \&ok Ta \&no Ta \&ok Ta \&ok-2 Ta \&no
+.It spin mtx  Ta \&ok-1 Ta \&no Ta \&no Ta \&no Ta \&no Ta \&no-3
+.It mutex     Ta \&ok Ta \&ok-1 Ta \&no Ta \&ok Ta \&ok Ta \&no-3
+.It sx        Ta \&ok Ta \&ok Ta \&ok-2 Ta \&ok Ta \&ok Ta \&ok-4
+.It rwlock    Ta \&ok Ta \&ok Ta \&no Ta \&ok-2 Ta \&ok Ta \&no-3
+.It rmlock    Ta \&ok Ta \&ok Ta \&no Ta \&ok Ta \&ok-2 Ta \&no
 .El
 .Pp
 .Em *1
@@ -364,10 +337,12 @@ The next table shows what can be used in
 At this time this is a rather easy to remember table.
 .Bl -column ".Ic Xxxxxxxxxxxxxxxxxxx" ".Xr XXXXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXX" -offset indent
 .It Xo
-.Em "Context:" Ta spin mtx Ta mutex Ta sx Ta rwlock Ta rmlock Ta sleep
+.Em "Context:"  Ta spin mtx Ta mutex Ta sx Ta rwlock Ta rmlock Ta sleep
 .Xc
-.It interrupt:  Ta \&ok Ta \&no Ta \&no Ta \&no Ta \&no Ta \&no 
-.It idle:  Ta \&ok Ta \&no Ta \&no Ta \&no Ta \&no Ta \&no 
+.It interrupt filter:  Ta \&ok Ta \&no Ta \&no Ta \&no Ta \&no Ta \&no 
+.It ithread:    Ta \&ok Ta \&ok Ta \&no Ta \&ok Ta \&ok Ta \&no 
+.It callout:    Ta \&ok Ta \&ok Ta \&no Ta \&ok Ta \&no Ta \&no 
+.It syscall:    Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok 
 .El
 .Sh SEE ALSO
 .Xr condvar 9 ,