Update this manpage:

- Remove references to cpu_critical_*() as they no longer exist.
- Explain that any preemptions that occur during a critical section are
  deferred until the current thread exits the section.
- Remove a bogus example usage of a critical section.
- Note that one can interlock critical sections with spin mutexes in
  certain situations.

MFC after:	3 days

2 files changed, 9 insertions, 49 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index df4eacf..4a8531a 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -420,9 +420,7 @@ MLINKS+=copy.9 copyin.9 \
 	copy.9 copyinstr.9 \
 	copy.9 copyout.9 \
 	copy.9 copystr.9
-MLINKS+=critical_enter.9 cpu_critical_enter.9 \
-	critical_enter.9 cpu_critical_exit.9 \
-	critical_enter.9 critical.9 \
+MLINKS+=critical_enter.9 critical.9 \
 	critical_enter.9 critical_exit.9
 MLINKS+=crypto.9 crypto_dispatch.9 \
 	crypto.9 crypto_done.9 \
diff --git a/share/man/man9/critical_enter.9 b/share/man/man9/critical_enter.9
index 84f64ca..a1d63fc 100644
--- a/share/man/man9/critical_enter.9
+++ b/share/man/man9/critical_enter.9
@@ -24,24 +24,16 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd March 22, 2001
+.Dd October 5, 2005
 .Dt CRITICAL_ENTER 9
 .Os
 .Sh NAME
-.Nm cpu_critical_enter ,
-.Nm cpu_critical_exit ,
 .Nm critical_enter ,
 .Nm critical_exit
 .Nd enter and exit a critical region
 .Sh SYNOPSIS
 .In sys/param.h
-.In sys/proc.h
 .In sys/systm.h
-.In machine/critical.h
-.Ft void
-.Fn cpu_critical_enter "void"
-.Ft void
-.Fn cpu_critical_exit "void"
 .Ft void
 .Fn critical_enter "void"
 .Ft void
@@ -56,20 +48,14 @@ The current CPU may still trigger faults and exceptions during a critical
 section; however, these faults are usually fatal.
 .Pp
 The
-.Fn cpu_critical_enter
-and
-.Fn cpu_critical_exit
-functions provide the machine dependent disabling of preemption, normally
-by disabling interrupts on the local CPU.
-.Pp
-The
 .Fn critical_enter
 and
 .Fn critical_exit
-functions provide a machine independent wrapper around the machine dependent
-API.
-This wrapper currently saves state regarding nested critical sections.
-Nearly all code should use these versions of the API.
+functions manage a per-thread counter to handle nested critical sections.
+If a thread is made runnable that would normally preempt the current thread
+while the current thread is in a critical section,
+then the preemption will be deferred until the current thread exits the
+outermost critical section.
 .Pp
 Note that these functions are not required to provide any inter-CPU
 synchronization, data protection, or memory ordering guarantees and thus
@@ -81,32 +67,8 @@ These functions should be used with care as an infinite loop within a
 critical region will deadlock the CPU.
 Also, they should not be interlocked with operations on mutexes, sx locks,
 semaphores, or other synchronization primitives.
-.Sh EXAMPLES
-This example demonstrates the use of
-.Fn critical_enter
-and
-.Fn critical_exit
-to guarantee atomic access to the DMA controller.
-.Bd -literal -offset indent
-int
-isa_dmastatus(int chan)
-{
-        u_long  cnt = 0;
-        int     ffport, waport;
-        u_long  low1, high1, low2, high2;
-
-	...
-        critical_enter();
-        outb(ffport, 0);
-        low1 = inb(waport);
-        high1 = inb(waport);
-        outb(ffport, 0);
-        low2 = inb(waport);
-        high2 = inb(waport);
-        critical_exit();
-	...
-}
-.Ed
+One exception to this is that spin mutexes include a critical section,
+so in certain cases critical sections may be interlocked with spin mutexes.
 .Sh HISTORY
 These functions were introduced in
 .Fx 5.0 .