Update. from csapuntz@

1 files changed, 67 insertions, 56 deletions

diff --git a/share/man/man9/vnode.9 b/share/man/man9/vnode.9
index 0d7d43a0c98..9d9a71b7468 100644
--- a/share/man/man9/vnode.9
+++ b/share/man/man9/vnode.9
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: vnode.9,v 1.12 2002/12/20 06:21:09 art Exp $
+.\"     $OpenBSD: vnode.9,v 1.13 2003/01/27 09:19:30 art Exp $
 .\"
 .\" Copyright (c) 2001 Constantine Sapuntzakis
 .\" All rights reserved.
@@ -30,9 +30,10 @@
 .Nm vnode
 .Nd an overview of vnodes
 .Sh DESCRIPTION
-A vnode is an object that speaks the UNIX file interface (open,
-read, write, close, readdir, etc.). Vnodes can represent files, 
-directories, FIFOs, domain sockets, block devices, character devices.
+A vnode is an object in kernel memory that speaks the UNIX file
+interface (open, read, write, close, readdir, etc.). Vnodes can
+represent files, directories, FIFOs, domain sockets, block devices,
+character devices.
 .Pp
 Each vnode has a set of methods which start with string 'VOP_'.
 These methods include VOP_OPEN, VOP_READ, VOP_WRITE, VOP_RENAME, VOP_CLOSE,
@@ -44,40 +45,39 @@ Each file system (FFS, NFS, etc.) provides implementations for these methods.
 The Virtual File System (VFS) library maintains a pool of vnodes.
 File systems cannot allocate their own vnodes; they must use the functions
 provided by the VFS to create and manage vnodes.
-.Ss Vnode state
-Vnodes have a reference count which corresponds to the number of kernel
-objects that hold references to the vnode.
-A positive reference count keeps
-the vnode off of the free list, which prevents the vnode from being recycled
-to refer to a different file.
-.Pp
-Vnodes that refer to a valid file and have a reference count of 1 or
-greater are "active".
-When a vnodes reference count drops to zero, it
-is "inactivated" and becomes "inactive".
-Inactive vnodes are placed on the
-free list, to be re-used to represent other files.
-.Pp
-Before a struct vnode can be re-used to refer to another file, it must
-be cleaned out of all information pertaining to the old file.
-A vnode that doesn't refer to any file is called a "reclaimed" vnode.
-.Pp
-The VFS may "reclaim" a vnode with a positive reference count.
-This is done when the underlying file is revoked, as happens with the
-revoke system call or through a forceable unmount.
-Such a vnode is given
-to the dead file system, which returns errors for most operations.
-The vnode will not be re-used for another file until its reference count
-hits zero.
-.Pp
-There are three states then for a vnode: active, inactive, and reclaimed.
-All transitions are meaningful except reclaimed to inactive.
+.Ss Vnode life cycle
+When a client of the VFS requests a new vnode, the vnode allocation
+code can reuse an old vnode object that is no longer in use.  Whether
+a vnode is in use is tracked by the vnode reference count
+(v_usecount). By convention, each open file handle holds a reference
+as do VM objects backed by files. A vnode with a reference count of 1
+or more will not be de-allocated or re-used to point to a different
+file. So, if you want to ensure that your vnode doesn't become a different
+file under you, you better be sure you have a reference to it. A vnode
+that points to a valid file and has a reference count of 1 or more is called
+"active".
+.Pp
+When a vnode's reference count drops to zero, it becomes "inactive",
+that is, a candidate for reuse. An "inactive" vnode still refers to a
+valid file and one can try to reactivate it using vget (this is used a
+lot by caches).
+.Pp
+Before the VFS can reuse an inactive vnode to refer to another file,
+it must clean all information pertaining to the old file. A cleaned
+out vnode is called a "reclaimed" vnode.
+.Pp
+To support forceable unmounts and the 
+.Xr revoke 2
+system call, the VFS may "reclaim" a vnode with a positive reference
+count. The "reclaimed" vnode is given to the dead file system, which
+returns errors for most operations.  The reclaimed vnode will not be
+re-used for another file until its reference count hits zero.
 .Ss Vnode pool
 The
 .Xr getnewvnode 9 
-system call returns a fresh active vnode from the vnode
-pool assigned to the file system specified in its arguments.
-The vnode returned has a reference count (v_usecount) of 1.
+system call allocates a vnode from the pool, possible reusing an
+"inactive" vnode, and returns it to the caller. The vnode returned has
+a reference count (v_usecount) of 1.
 .Pp
 The 
 .Xr vref 9 
@@ -107,7 +107,7 @@ and
 orchestrate the reclamation of a vnode.
 They can be called on both active and inactive vnodes.
 .Pp
-While transitioning a vnode to the "reclaimed" state, the VFS will call
+When transitioning a vnode to the "reclaimed" state, the VFS will call
 .Xr vop_reclaim 9 
 method.
 File systems use this method to free any file-system specific data
@@ -116,32 +116,42 @@ they attached to the vnode.
 The vnode actually has three different types of lock: the vnode lock,
 the vnode interlock, and the vnode reclamation lock (VXLOCK).
 .Ss The vnode lock
-The most general lock is the vnode lock.
-This lock is acquired by calling 
+The vnode lock and its consistent use accomplishes the following:
+.Bl -bullet
+.It
+It keeps a locked vnode from changing across certain pairs of VOP_ calls,
+thus preserving cached data. For example, it keeps the directory from
+changing between a VOP_LOOKUP call and a VOP_CREATE. The VOP_LOOKUP
+call makes sure the name doesn't already exist in the directory and
+finds free room in the directory for the new entry. The VOP_CREATE can
+then go ahead and create the file without checking if it already
+exists or looking for free space.
+.It
+Some file systems rely on it to ensure that only one "thread" at a time
+is calling VOP_ vnode operations on a given file or directory. Otherwise,
+the file system's behavior is undefined.
+.It
+On rare occasions, code will hold the vnode lock so that a series of
+VOP_ operations occurs as an atomic unit. (Of course, this doesn't
+work with network file systems like NFSv2 that don't have any notion
+of bundling a bunch of operations into an atomic unit)
+.It
+While the vnode lock is held, the vnode will not be reclaimed.
+.El
+.Pp
+There is a discipline to using the vnode lock. Some VOP_ operations
+require that the vnode lock is held before being called. A description
+of this rather arcane locking discipline is in sys/kern/vnode_if.src.
+.Pp
+The vnode lock is acquired by calling 
 .Xr vn_lock 9 
 and released by calling 
 .Xr vn_unlock 9 .
-The vnode lock is used to serialize operations through the file system for
-a given file when there are multiple concurrent requests on the same file. 
-Many file system functions require that the vnode lock is held on entry.
-The vnode lock may be held when sleeping.
 .Pp
-A vnode will not be reclaimed as long as the vnode lock is held by some 
-other process.
-.Pp
-The vnode lock is a multiple-reader or single-writer lock.
-An exclusive vnode lock may be acquired multiple times by the same
-process.
-.Pp
-The vnode lock is somewhat messy because it is used for many purposes.
-Some clients of the vnode interface use it to try to bundle a series
-of VOP_ method calls into an atomic group.
-Many file systems rely on it to prevent race conditions in updating file
-system specific data structures (as opposed to having their own locks). 
+A process is allowed to sleep while holding the vnode lock.
 .Pp
 The implementation of the vnode lock is the responsibility of the individual
-file systems.
-Not all file system implement it.
+file systems. Not all file systems implement it.
 .Pp
 To prevent deadlocks, when acquiring locks on multiple vnodes, the lock
 of parent directory must be acquired before the lock on the child directory.
@@ -225,3 +235,4 @@ Any accesses to these fields should be protected by splbio.
 .Sh HISTORY
 This document first appeared in
 .Ox 2.9 .
+