diff options
| -rw-r--r-- | share/man/man9/Makefile | 2 | ||||
| -rw-r--r-- | share/man/man9/critical_enter.9 | 52 |
2 files changed, 43 insertions, 11 deletions
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 3f644de..04d1f85 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -120,6 +120,8 @@ MLINKS+=condvar.9 cv_waitq_empty.9 MLINKS+=condvar.9 cv_wmesg.9 MLINKS+=copy.9 copyin.9 copy.9 copyinstr.9 copy.9 copyout.9 copy.9 copystr.9 MLINKS+=critical_enter.9 critical_exit.9 +MLINKS+=critical_enter.9 cpu_critical_enter.9 +MLINKS+=critical_enter.9 cpu_critical_exit.9 MLINKS+=device_ids.9 major.9 device_ids.9 minor.9 MLINKS+=device_ids.9 umajor.9 device_ids.9 uminor.9 MLINKS+=devstat.9 devicestat.9 devstat.9 devstat_add_entry.9 diff --git a/share/man/man9/critical_enter.9 b/share/man/man9/critical_enter.9 index 1a14d13..673be96 100644 --- a/share/man/man9/critical_enter.9 +++ b/share/man/man9/critical_enter.9 @@ -1,4 +1,4 @@ -.\" Copyright (c) 2001 John H. Baldwin <jhb@FreeBSD.org> +.\" Copyright (c) 2001,2002 John H. Baldwin <jhb@FreeBSD.org> .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -28,30 +28,57 @@ .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/types.h .In sys/systm.h +.Ft critical_t +.Fn cpu_critical_enter "void" +.Ft void +.Fn cpu_critical_exit "critical_t savecrit" .Ft void .Fn critical_enter "void" .Ft void .Fn critical_exit "void" .Sh DESCRIPTION These functions are used to prevent preemption in a critcal region of code. -All that is guaranteed is that the current CPU will not be preempted by an -external interrupt. +All that is guaranteed is that the thread currently executing on a CPU will +not be preempted. +Specifically, a thread in a critical region will not migrate to another +CPU while it is in a critical region. The current CPU may still trigger faults and exceptions during a critical -section. +section; however, these faults are usually fatal. +.Pp The -.Fn critical_enter +.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. +The +.Fn cpu_critical_enter function returns an opaque value of type .Vt critical_t . This value must be passed to the -.Fn critical_exit +.Fn cpu_critical_exit function when leaving the critical region. .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 as +well as the +.Vt critical_t +value inside of a critical region in per-thread variables. +Nearly all code should use these versions of the API. +.Pp Note that these functions are not required to provide any inter-CPU synchronization, data protection, or memory ordering guarantees and thus should @@ -60,11 +87,15 @@ be used to protect shared data structures. .Pp These functions should be used with care as an infinite loop within a critical region will deadlock the CPU. +Also, the machine dependent and machine independent functions should not +be interlocked, and neither pair of functions should be interlocked with +operations on mutexes, sx locks, semaphores, or other synchronization +primitives. .Sh RETURN VALUES The -.Fn critical_enter +.Fn cpu_critical_enter function returns an opaque value that must be passed to a corresponding call to -.Fn critical_exit . +.Fn cpu_critical_exit . .Sh EXAMPLES This example demonstrates the use of .Fn critical_enter @@ -78,17 +109,16 @@ isa_dmastatus(int chan) u_long cnt = 0; int ffport, waport; u_long low1, high1, low2, high2; - critical_t savecrit; ... - savecrit = critical_enter(); + critical_enter(); outb(ffport, 0); low1 = inb(waport); high1 = inb(waport); outb(ffport, 0); low2 = inb(waport); high2 = inb(waport); - critical_exit(savecrit); + critical_exit(); ... } .Ed |
