Manual page for the mutex set of functions. Okay jmc@ and art@.

2 files changed, 92 insertions, 2 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 3381bb989c0..5ada26e4aba 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.88 2004/12/18 14:26:03 grange Exp $
+#	$OpenBSD: Makefile,v 1.89 2005/02/18 16:15:32 pedro Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -12,7 +12,7 @@ MAN=	altq.9 audio.9 autoconf.9 boot.9 buffercache.9 bus_dma.9 bus_space.9 \
 	hardclock.9 hook_establish.9 hz.9 hzto.9 iic.9 intro.9 inittodr.9 \
 	kern.9 knote.9 kthread.9 ktrace.9 loadfirmware.9 lock.9 log.9 \
 	malloc.9 mbuf.9 mbuf_tags.9 md5.9 microtime.9 \
-	mountroothook_establish.9 namei.9 \
+	mountroothook_establish.9 mutex.9 namei.9 \
 	panic.9 pfind.9 physio.9 pmap.9 \
 	pool.9 powerhook_establish.9 ppsratecheck.9 printf.9 psignal.9 \
 	radio.9 random.9 rasops.9 ratecheck.9 resettodr.9 \
@@ -147,6 +147,7 @@ MLINKS+=microtime.9 getmicrotime.9 microtime.9 microuptime.9 \
 	microtime.9 getnanouptime.9 microtime.9 bintime.9 \
 	microtime.9 getbintime.9 microtime.9 binuptime.9 \
 	microtime.9 getbinuptime.9
+MLINKS+=mutex.9 mtx_init.9 mutex.9 mtx_enter.9 mutex.9 mtx_leave.9
 MLINKS+=namei.9 lookup.9 namei.9 relookup.9 namei.9 NDINIT.9
 MLINKS+=random.9 add_true_randomness.9 \
 	random.9 add_timer_randomness.9 \
diff --git a/share/man/man9/mutex.9 b/share/man/man9/mutex.9
new file mode 100644
index 00000000000..a6d4c7c7360
--- /dev/null
+++ b/share/man/man9/mutex.9
@@ -0,0 +1,89 @@
+.\" $OpenBSD: mutex.9,v 1.1 2005/02/18 16:15:32 pedro Exp $
+.\"
+.\" Copyright (c) 2005 Pedro Martelletto <pedro@openbsd.org>
+.\" All rights reserved.
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd February 9, 2005
+.Dt MUTEX 9
+.Os
+.Sh NAME
+.Nm mutex ,
+.Nm mtx_init ,
+.Nm mtx_enter ,
+.Nm mtx_leave
+.Nd interface to CPU mutexes
+.Sh SYNOPSIS
+.Fd #include <sys/mutex.h>
+.Ft void
+.Fn mtx_init "struct mutex *mtxp" "int wantipl"
+.Ft void
+.Fn mtx_enter "struct mutex *mtxp"
+.Ft void
+.Fn mtx_leave "struct mutex *mtxp"
+.Sh DESCRIPTION
+The
+.Nm
+set of functions provides a non-recursive, interrupt-aware spinning mechanism
+to ensure mutual exclusion between different CPUs.
+.Pp
+The
+.Fn mtx_init
+function is used to initiate the mutex pointed to by
+.Fa mtxp .
+When acquired, the mutex will cause the processor interrupt level to be changed
+to
+.Fa wantipl .
+.Pp
+The
+.Fn mtx_enter
+function acquires a mutex, spinning if necessary.
+.Pp
+The
+.Fn mtx_leave
+function releases a mutex.
+In case the acquisition of the mutex caused the interrupt level to be changed,
+it is then restored.
+.Sh SEE ALSO
+.Xr lockmgr 9 ,
+.Xr spl 9
+.Sh HISTORY
+The
+.Nm
+functions first appeared in
+.Ox 3.6 .
+.Sh AUTHORS
+The
+.Nm
+functions were written by
+.An Artur Grabowski
+.Aq art@openbsd.org .
+.Sh CAVEATS
+Multiple mutexes may be nested, but not interleaved.
+This is okay:
+.Bd -literal -offset indent
+mtx_enter(foo);
+mtx_enter(bar);
+mtx_leave(bar);
+mtx_leave(foo);
+.Ed
+.Pp
+While this is
+.Fa not :
+.Bd -literal -offset indent
+mtx_enter(foo);
+mtx_enter(bar);
+mtx_leave(foo);
+mtx_leave(bar);
+.Ed