Add discussion of Giant, the MPSAFE flag, and NDHASGIANT() to namei(9).

Add a VFS_LOCK_GIANT(9)/VFS_UNLOCK_GIANT(9) man page.

Discussed with:	jeff
MFC after:	3 days

3 files changed, 124 insertions, 1 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index f1f14e1..0afeb43 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -231,6 +231,7 @@ MAN=	accept_filter.9 \
 	VFS_FHTOVP.9 \
 	vfs_getnewfsid.9 \
 	vfs_getvfs.9 \
+	VFS_LOCK_GIANT.9 \
 	VFS_MOUNT.9 \
 	vfs_mount.9 \
 	vfs_mountedon.9 \
@@ -973,6 +974,7 @@ MLINKS+=vcount.9 count_dev.9
 MLINKS+=vfsconf.9 vfs_modevent.9 \
 	vfsconf.9 vfs_register.9 \
 	vfsconf.9 vfs_unregister.9
+MLINKS+=VFS_LOCK_GIANT.9 VFS_UNLOCK_GIANT.9
 MLINKS+=vgone.9 vgonel.9
 MLINKS+=vhold.9 vdrop.9
 MLINKS+=vm_map_lock.9 vm_map_lock_downgrade.9 \
diff --git a/share/man/man9/VFS_LOCK_GIANT.9 b/share/man/man9/VFS_LOCK_GIANT.9
new file mode 100644
index 0000000..11aee93
--- /dev/null
+++ b/share/man/man9/VFS_LOCK_GIANT.9
@@ -0,0 +1,90 @@
+.\"
+.\" Copyright (c) 2005 Robert N. M. Watson
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice(s), this list of conditions and the following disclaimer as
+.\"    the first lines of this file unmodified other than the possible
+.\"    addition of one or more copyright notices.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice(s), this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
+.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+.\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
+.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+.\" DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd September 21, 2005
+.Dt VFS_LOCK_GIANT 9
+.Os
+.Sh NAME
+.Nm VFS_LOCK_GIANT ,
+.Nm VFS_UNLOCK_GIANT
+.Nd "Conditionally lock and unlock Giant around entry into VFS"
+.Sh SYNOPSIS
+.In sys/param.h
+.In sys/vnode.h
+.Ft int
+.Fn VFS_LOCK_GIANT "struct mount *mp"
+.Ft void
+.Fn VFS_UNLOCK_GIANT "int vfslocked"
+.Sh DESCRIPTION
+.Fn VFS_LOCK_GIANT
+will conditionally acquire the
+.Dv Giant
+lock if the file system referenced by
+.Fa mp
+is marked as MPSAFE or not, returning a flag indicating whether Giant was
+set, which may later be passed to
+.Fn VFS_UNLOCK_GIANT .
+The value of
+.Fa mp
+will typically be derived from the mount pointer in a
+.Xr vnode
+on which a VFS operation will be performed.
+.Pp
+.Fn VFS_UNLOCK_GIANT
+conditionally releases the
+.Va Giant
+lock if the passed
+.Fa vfslocked
+argument is non-zero.
+It is expected that the argument will be derived from the return values of
+.Vn VFS_LOCK_GIANT
+or
+.Xr NDHASGIANT 9 .
+.Sh RETURN VALUES
+.Fn VFS_LOCK_GIANT
+returns a boolean indicating whether or not
+.Va Giant
+was acquired.
+.Sh SEE ALSO
+.Xr mutex 9 ,
+.Xr NDHASGIANT 9 ,
+.Xr vnode 9
+.Sh AUTHORS
+MPSAFE VFS support for
+.Fx
+was implemented by
+.An Jeff Roberson .
+.Pp
+This manual page was written by
+.An Robert Watson .
+.Sh BUGS
+.Pp
+Non-MPSAFE file systems exist, requiring callers conditional locking and
+unlocking of
+.Va Giant .
diff --git a/share/man/man9/namei.9 b/share/man/man9/namei.9
index 9ddf591..7429a27 100644
--- a/share/man/man9/namei.9
+++ b/share/man/man9/namei.9
@@ -1,6 +1,7 @@
 .\"
 .\" Copyright (c) 1998, 1999 Eivind Eklund
 .\" Copyright (c) 2003 Hiten M. Pandya
+.\" Copyright (c) 2005 Robert N. M. Watson
 .\"
 .\" All rights reserved.
 .\"
@@ -38,7 +39,8 @@
 .Sh NAME
 .Nm namei ,
 .Nm NDINIT ,
-.Nm NDFREE
+.Nm NDFREE ,
+.Nm NDHASGIANT
 .Nd pathname translation and lookup operations
 .Sh SYNOPSIS
 .In sys/param.h
@@ -53,6 +55,8 @@
 .Fc
 .Ft void
 .Fn NDFREE "struct nameidata *ndp" "const uint flags"
+.Ft int
+.Fn NDHASGIANT "struct nameidata *ndp"
 .Sh DESCRIPTION
 The
 .Nm
@@ -69,6 +73,16 @@ or
 depending on whether the
 .Dv LOCKLEAF
 flag was specified or not.
+If the
+.Va Giant
+lock is required,
+.Nm
+will acquire it if the caller indicates it is
+.Dv MPSAFE ,
+in which case the caller must later release
+.Va Giant
+based on the results of
+.Fn NDHASGIANT.
 .Pp
 The
 .Fn NDINIT
@@ -154,6 +168,19 @@ This flag allows the
 function to return the parent (directory) vnode in an unlocked state.
 The parent vnode must be released separately by using
 .Xr vrele 9 .
+.It Dv MPSAFE
+With this flag set,
+.Fn namei
+will conditionally acquire
+.Va Giant
+if it is required by a traversed file system.
+MPSAFE callers should pass the results of
+.Fn NDHASGIANT
+to
+.Xr VFS_UNLOCK_GIANT
+in order to conditionally release
+.Va Giant
+if necessary.
 .It Dv NOCACHE
 Avoid
 .Fn namei
@@ -296,6 +323,7 @@ function.
 .Xr uio 9 ,
 .Xr uma 9 ,
 .Xr VFS 9 ,
+.Xr VFS_UNLOCK_GIANT 9 ,
 .Xr vnode 9 ,
 .Xr vput 9 ,
 .Xr vref 9
@@ -317,3 +345,6 @@ In order to solve this for the cases where both
 and
 .Dv LOCKLEAF
 are used, it is necessary to resort to recursive locking.
+.Pp
+Non-MPSAFE file systems exist, requiring callers to conditionally unlock
+.Va Giant .