From 31516e899fdd4d901d70e2fd4ec2843b8731027d Mon Sep 17 00:00:00 2001 From: Pedro Martelletto Date: Fri, 18 Feb 2005 16:15:33 +0000 Subject: Manual page for the mutex set of functions. Okay jmc@ and art@. --- share/man/man9/Makefile | 5 +-- share/man/man9/mutex.9 | 89 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 92 insertions(+), 2 deletions(-) create mode 100644 share/man/man9/mutex.9 (limited to 'share/man') 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 +.\" 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 +.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 -- cgit v1.2.3