spinlocks - adjust man pages and *_quick_* routines
authorAlex Hornung <ahornung@gmail.com>
Mon, 30 Aug 2010 12:20:49 +0000 (13:20 +0100)
committerAlex Hornung <ahornung@gmail.com>
Mon, 30 Aug 2010 12:20:49 +0000 (13:20 +0100)
* Adjust man pages to reflect the recent changes (removal of shared
  spinlocks, renaming of exclusive spinlocks).

* Remove old man page symlinks and adjust new ones.

* Rename the spin_{un,}lock_wr_quick ro spin_{un,}lock_quick.

Makefile_upgrade.inc
share/man/man9/Makefile
share/man/man9/spinlock.9
sys/kern/kern_spinlock.c
sys/kern/kern_synch.c
sys/sys/spinlock2.h

index 8b767d7..cbf6dfc 100644 (file)
@@ -1500,6 +1500,15 @@ TO_REMOVE+=/usr/share/man/cat4/i386/amdpm.4.gz
 TO_REMOVE+=/usr/share/man/man4/i386/amdpm.4.gz
 TO_REMOVE+=/usr/include/machine/iic.h
 TO_REMOVE+=/usr/include/machine/smb.h
+TO_REMOVE+=/usr/share/man/man9/spin_lock_rd.9.gz
+TO_REMOVE+=/usr/share/man/man9/spin_lock_rd_quick.9.gz
+TO_REMOVE+=/usr/share/man/man9/spin_lock_wr.9.gz
+TO_REMOVE+=/usr/share/man/man9/spin_lock_wr_quick.9.gz
+TO_REMOVE+=/usr/share/man/man9/spin_trylock_wr.9.gz
+TO_REMOVE+=/usr/share/man/man9/spin_unlock_rd.9.gz
+TO_REMOVE+=/usr/share/man/man9/spin_unlock_rd_quick.9.gz
+TO_REMOVE+=/usr/share/man/man9/spin_unlock_wr.9.gz
+TO_REMOVE+=/usr/share/man/man9/spin_unlock_wr_quick.9.gz
 
 # XXX Remove when adjusted to the new 802.11 framework
 TO_REMOVE+=/boot/modules/if_acx.ko
index cfd40bb..17e2687 100644 (file)
@@ -739,16 +739,12 @@ MLINKS+=sleep.9 lksleep.9 \
        sleep.9 wakeup_one.9 \
        sleep.9 zsleep.9
 MLINKS+=spinlock.9 spin_init.9 \
-       spinlock.9 spin_lock_rd.9 \
-       spinlock.9 spin_lock_rd_quick.9 \
-       spinlock.9 spin_lock_wr.9 \
-       spinlock.9 spin_lock_wr_quick.9 \
-       spinlock.9 spin_trylock_wr.9 \
+       spinlock.9 spin_lock.9 \
+       spinlock.9 spin_lock_quick.9 \
+       spinlock.9 spin_trylock.9 \
        spinlock.9 spin_uninit.9 \
-       spinlock.9 spin_unlock_rd.9 \
-       spinlock.9 spin_unlock_rd_quick.9 \
-       spinlock.9 spin_unlock_wr.9 \
-       spinlock.9 spin_unlock_wr_quick.9
+       spinlock.9 spin_unlock.9 \
+       spinlock.9 spin_unlock_quick.9
 MLINKS+=store.9 casuword.9 \
        store.9 subyte.9 \
        store.9 susword.9 \
index cc60f3a..2befcdc 100644 (file)
 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd April 10, 2010
+.Dd August 30, 2010
 .Os
 .Dt SPINLOCK 9
 .Sh NAME
 .Nm spin_init ,
-.Nm spin_lock_rd ,
-.Nm spin_lock_rd_quick ,
-.Nm spin_lock_wr ,
-.Nm spin_lock_wr_quick ,
-.Nm spin_trylock_wr ,
+.Nm spin_lock ,
+.Nm spin_lock_quick ,
+.Nm spin_trylock ,
 .Nm spin_uninit ,
-.Nm spin_unlock_rd ,
-.Nm spin_unlock_rd_quick ,
-.Nm spin_unlock_wr ,
-.Nm spin_unlock_wr_quick
+.Nm spin_unlock ,
+.Nm spin_unlock_quick
 .Nd core spinlocks
 .Sh SYNOPSIS
 .In sys/spinlock.h
 .Ft void
 .Fn spin_uninit "struct spinlock *mtx"
 .Ft void
-.Fn spin_lock_rd "struct spinlock *mtx"
+.Fn spin_lock "struct spinlock *mtx"
 .Ft void
-.Fn spin_lock_rd_quick "globaldata_t gd" "struct spinlock *mtx"
-.Ft void
-.Fn spin_unlock_rd "struct spinlock *mtx"
-.Ft void
-.Fn spin_unlock_rd_quick "globaldata_t gd" "struct spinlock *mtx"
-.Ft void
-.Fn spin_lock_wr "struct spinlock *mtx"
-.Ft void
-.Fn spin_lock_wr_quick "globaldata_t gd" "struct spinlock *mtx"
+.Fn spin_lock_quick "globaldata_t gd" "struct spinlock *mtx"
 .Ft boolean_t
-.Fn spin_trylock_wr "struct spinlock *mtx"
+.Fn spin_trylock "struct spinlock *mtx"
 .Ft void
-.Fn spin_unlock_wr "struct spinlock *mtx"
+.Fn spin_unlock "struct spinlock *mtx"
 .Ft void
-.Fn spin_unlock_wr_quick "globaldata_t gd" "struct spinlock *mtx"
+.Fn spin_unlock_quick "globaldata_t gd" "struct spinlock *mtx"
 .Sh DESCRIPTION
 The
 .Fa spinlock
@@ -88,50 +76,14 @@ The structure is cleaned up with
 when it is no longer needed.
 .Pp
 The
-.Fn spin_lock_rd
-function obtains a shared
-.Em read-only
-spinlock.
-A thread may hold only one shared lock at a time, and may not acquire any
-new exclusive locks while holding a shared lock (but may already be holding
-some).
-A shared spinlock can be held by multiple CPUs concurrently.
-If a thread attempts to obtain an exclusive spinlock while shared
-references from other CPUs exist it will spin until the shared references
-go away.
-No new shared references will be allowed (that is, new shared requests
-will also spin) while the exclusive spinlock is being acquired.
-If you have the current CPU's
-.Fa globaldata
-pointer in hand you can call
-.Fn spin_lock_rd_quick ,
-but most code will just call the normal version.
-Shared spinlocks reserve a bit in the spinlock's memory for each CPU
-and do not clear the bit once set.
-This means that once set, a shared spinlock does not need to issue a
-locked read-modify-write bus cycle to the spinlock's memory, which in
-turn greatly reduces conflicts between CPU caches.
-The bit is cleared via a different mechanism only when an exclusive
-spinlock is acquired.
-The result is extremely low overheads even when a shared spinlock is
-being operated upon concurrently by multiple CPUs.
-.Pp
-A previously obtained shared spinlock is released by calling either
-.Fn spin_unlock_rd
-or
-.Fn spin_unlock_rd_quick .
-.Pp
-The
-.Fn spin_lock_wr
+.Fn spin_lock
 function obtains an exclusive
 .Em read-write
 spinlock.
 A thread may hold any number of exclusive spinlocks but should always
 be mindful of ordering deadlocks.
-Exclusive spinlocks can only be safely
-acquired if no shared spinlocks are held.
 The
-.Fn spin_trylock_wr
+.Fn spin_trylock
 function will return
 .Dv TRUE
 if the spinlock was successfully obtained and
@@ -140,23 +92,15 @@ if it wasn't.
 If you have the current CPU's
 .Fa globaldata
 pointer in hand you can call
-.Fn spin_lock_wr_quick ,
+.Fn spin_lock_quick ,
 but most code will just call the normal version.
 A spinlock used only for exclusive access has about the same overhead
 as a mutex based on a locked bus cycle.
-When used in a mixed shared/exclusive environment, however, additional
-overhead may be incurred to obtain the exclusive spinlock.
-Because shared spinlocks are left intact even after released (to
-optimize shared spinlock performance), the exclusive spinlock code
-must run through any shared bits it finds in the spinlock, clear them,
-and check the related CPU's
-.Fa globaldata
-structure to determine whether it needs to spin or not.
 .Pp
 A previously obtained exclusive spinlock is released by calling either
-.Fn spin_unlock_wr
+.Fn spin_unlock
 or
-.Fn spin_unlock_wr_quick .
+.Fn spin_unlock_quick .
 .Sh IMPLEMENTATION NOTES
 A thread may not hold any spinlock across a blocking condition or
 thread switch.
@@ -193,9 +137,7 @@ Currently, FAST interrupts, including IPI messages, are not allowed to
 acquire any spinlocks.
 It is possible to work around this if
 .Va mycpu->gd_spinlocks_wr
-and
-.Va mycpu->gd_spinlocks_rd
-are both 0.
+is 0.
 If one
 or the other is not zero, the FAST interrupt or IPI cannot acquire
 any spinlocks without risking a deadlock, even if the spinlocks in
@@ -204,16 +146,6 @@ question are not related.
 A thread may hold any number of exclusive
 .Em read-write
 spinlocks.
-However, a thread may only hold one shared
-.Em read-only
-spinlock, and may not acquire any new exclusive locks while it is holding
-that one shared lock.
-This requirement is due to the method exclusive
-spinlocks use to determine when they can clear cached shared bits in
-the lock.
-If an exclusive lock is acquired while holding shared locks,
-a deadlock can occur even if the locks are unrelated.
-Always be mindful of potential deadlocks.
 .Pp
 Spinlocks spin.
 A thread will not block, switch away, or lose its critical section
index 540055a..fb785ba 100644 (file)
@@ -272,8 +272,8 @@ sysctl_spin_lock_test(SYSCTL_HANDLER_ARGS)
 
                spin_init(&mtx);
                for (i = spin_test_count; i > 0; --i) {
-                   spin_lock_wr_quick(gd, &mtx);
-                   spin_unlock_wr_quick(gd, &mtx);
+                   spin_lock_quick(gd, &mtx);
+                   spin_unlock_quick(gd, &mtx);
                }
        }
 
index a739ad2..193821b 100644 (file)
@@ -710,9 +710,9 @@ ssleep(const volatile void *ident, struct spinlock *spin, int flags,
        int error;
 
        _tsleep_interlock(gd, ident, flags);
-       spin_unlock_wr_quick(gd, spin);
+       spin_unlock_quick(gd, spin);
        error = tsleep(ident, flags | PINTERLOCKED, wmesg, timo);
-       spin_lock_wr_quick(gd, spin);
+       spin_lock_quick(gd, spin);
 
        return (error);
 }
index 57960c9..a31556e 100644 (file)
@@ -103,7 +103,7 @@ spin_trylock(struct spinlock *mtx)
  * Obtain an exclusive spinlock and return.
  */
 static __inline void
-spin_lock_wr_quick(globaldata_t gd, struct spinlock *mtx)
+spin_lock_quick(globaldata_t gd, struct spinlock *mtx)
 {
 #ifdef SMP
        int value;
@@ -121,7 +121,7 @@ spin_lock_wr_quick(globaldata_t gd, struct spinlock *mtx)
 static __inline void
 spin_lock(struct spinlock *mtx)
 {
-       spin_lock_wr_quick(mycpu, mtx);
+       spin_lock_quick(mycpu, mtx);
 }
 
 /*
@@ -130,7 +130,7 @@ spin_lock(struct spinlock *mtx)
  * cleared.
  */
 static __inline void
-spin_unlock_wr_quick(globaldata_t gd, struct spinlock *mtx)
+spin_unlock_quick(globaldata_t gd, struct spinlock *mtx)
 {
 #ifdef SMP
        mtx->lock = 0;
@@ -144,7 +144,7 @@ spin_unlock_wr_quick(globaldata_t gd, struct spinlock *mtx)
 static __inline void
 spin_unlock(struct spinlock *mtx)
 {
-       spin_unlock_wr_quick(mycpu, mtx);
+       spin_unlock_quick(mycpu, mtx);
 }
 
 static __inline void