d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update this manpage:

Browse Source 
- 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
This commit is contained in:
John Baldwin 2005-10-05 19:48:21 +00:00
parent 031469eb27
commit eefd941ba2
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=150978
2 changed files with 9 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
share/man/man9/Makefile
View File

@ -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 \

54
share/man/man9/critical_enter.9
View File

@ -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 .