Sat Feb 22 10:08:12 2014 UTC ()

Update arguments of vrecycle(), description of getnewvnode() and
the vnode flags.


(hannken)

diff -r1.57 -r1.58 src/share/man/man9/vnode.9

--- src/share/man/man9/vnode.9 2013/10/29 09:53:51	1.57
+++ src/share/man/man9/vnode.9 2014/02/22 10:08:12	1.58

 @@ -1,14 +1,14 @@
-.\"     $NetBSD: vnode.9,v 1.57 2013/10/29 09:53:51 hannken Exp $
+.\"     $NetBSD: vnode.9,v 1.58 2014/02/22 10:08:12 hannken Exp $
 .\"
 .\" Copyright (c) 2001, 2005, 2006 The NetBSD Foundation, Inc.
 .\" All rights reserved.
 .\"
 .\" This code is derived from software contributed to The NetBSD Foundation
 .\" by Gregory McGarry.
 .\"
 .\" 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, this list of conditions and the following disclaimer.
 .\" 2. Redistributions in binary form must reproduce the above copyright
 @@ -17,27 +17,27 @@
 .\"
 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
 .\" ``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 FOUNDATION OR CONTRIBUTORS
 .\" 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.
 .\"
-.Dd October 29, 2013
+.Dd February 22, 2014
 .Dt VNODE 9
 .Os
 .Sh NAME
 .Nm vnode ,
 .Nm vref ,
 .Nm vrele ,
 .Nm vrele_async ,
 .Nm vget ,
 .Nm vput ,
 .Nm vhold ,
 .Nm holdrele ,
 .Nm getnewvnode ,
 .Nm ungetnewvnode ,
 @@ -69,27 +69,27 @@
 .Fn vget "struct vnode *vp" "int lockflag"
 .Ft void
 .Fn vput "struct vnode *vp"
 .Ft void
 .Fn vhold "struct vnode *vp"
 .Ft void
 .Fn holdrele "struct vnode *vp"
 .Ft int
 .Fn getnewvnode "enum vtagtype tag" "struct mount *mp" "int (**vops)(void *)" \
 "kmutex_t *slock" "struct vnode **vpp"
 .Ft void
 .Fn ungetnewvnode "struct vnode *vp"
 .Ft int
-.Fn vrecycle "struct vnode *vp" "struct simplelock *inter_lkp"
+.Fn vrecycle "struct vnode *vp" "struct kmutex_t *inter_lkp"
 .Ft void
 .Fn vgone "struct vnode *vp"
 .Ft void
 .Fn vgonel "struct vnode *vp" "struct lwp *l"
 .Ft int
 .Fn vflush "struct mount *mp" "struct vnode *skipvp" "int flags"
 .Ft int
 .Fn vaccess "enum vtype type" "mode_t file_mode" "uid_t uid" "gid_t gid" "mode_t acc_mode" "kauth_cred_t cred"
 .Ft int
 .Fn bdevvp "dev_t dev" "struct vnode **vpp"
 .Ft int
 .Fn cdevvp "dev_t dev" "struct vnode **vpp"
 .Ft int
 @@ -173,78 +173,81 @@ There are some rather common exceptions
 .Pp
 Files and file systems are inextricably linked with the virtual memory
 system and
 .Em v_uobj
 contains the data maintained by the virtual memory system.
 For compatibility with code written before the integration of
 .Xr uvm 9
 into
 .Nx ,
 C-preprocessor directives are used to alias the members of
 .Em v_uobj .
 .Pp
 Vnode flags are recorded by
-.Em v_flag .
+.Em v_iflag ,
 .Em v_vflag
 and
 .Em v_uflag .
 Valid flags are:
 .Pp
 .Bl -tag -offset indent -width VONWORKLST -compact
-.It VROOT
+.It VV_ROOT
 This vnode is the root of its file system.
-.It VTEXT
+.It VV_SYSTEM
 This vnode is a pure text prototype.
 .It VSYSTEM
 This vnode is being used by the kernel; only used to skip quota files in
 .Fn vflush .
-.It VISTTY
+.It VV_ISTTY
 This vnode represents a tty; used when reading dead vnodes.
-.It VEXECMAP
+.It VV_MAPPED
 This vnode might have user mappings.
 .It VV_MPSAFE
 This file system is MP safe.
 .It VV_LOCKSWORK
 This vnode's file system supports locking.
 .It VI_TEXT
 This vnode is a pure text prototype.
 .It VI_EXECMAP
 This vnode has executable mappings.
-.It VWRITEMAP
+.It VI_WRMAP
 This vnode might have PROT_WRITE user mappings.
-.It VWRITEMAPDIRTY
+.It VI_WRMAPDIRTY
 This vnode might have dirty pages due to VWRITEMAP
-.It VLOCKSWORK
+.It VI_XLOCK
 This vnode's file system supports locking.
 .It VXLOCK
 This vnode is currently locked to change underlying type.
-.It VXWANT
+.It VI_ONWORKLST
-A process is waiting for this vnode.
+This vnode is on syncer work-list.
-.It VBWAIT
+.It VI_MARKER
-Waiting for output associated with this vnode to complete.
+A dummy marker vnode.
-.It VALIASED
+.It VI_LAYER
-This vnode has an alias.
+This vnode is on a layered file system.
-.It VDIROP
+.It VI_LOCKSHARE
 This vnode shares its
 .Em v_interlock
 with other vnodes.
 .It VI_CLEAN
 This vnode has been reclaimed and is no longer attached to a file system.
 .It VU_DIROP
 This vnode is involved in a directory operation.
 This flag is used exclusively by LFS.
 .It VLAYER
 This vnode is on a layered file system.
 .It VONWORKLST
 This vnode is on syncer work-list.
 .It VFREEING
 This vnode is being freed.
 .It VMAPPED
 This vnode might have user mappings.
 .El
 .Pp
-The VXLOCK flag is used to prevent multiple processes from entering
+The VI_XLOCK flag is used to prevent multiple processes from entering
 the vnode reclamation code.
 It is also used as a flag to indicate that reclamation is in progress.
 The VXWANT flag is set by threads that wish to be awakened when
 reclamation is finished.
 Before
-.Em v_flag
+.Em v_iflag
 can be modified, the
 .Em v_interlock
-simplelock must be acquired.
+mutex must be acquired.
 See
 .Xr lock 9
 for details on the kernel locking API.
 .Pp
 Each vnode has three reference counts:
 .Em v_usecount ,
 .Em v_writecount
 and
 .Em v_holdcnt .
 The first is the number of active references within the
 kernel to the vnode.
 This count is maintained by
 .Fn vref ,
 @@ -262,38 +265,37 @@ system calls.
 The third is the number of references within the kernel
 requiring the vnode to remain active and not be recycled.
 This count is maintained by
 .Fn vhold
 and
 .Fn holdrele .
 When both the
 .Em v_usecount
 and
 .Em v_holdcnt
 reach zero, the vnode is recycled to the freelist and may be reused
 for another file.
 The transition to and from the freelist is handled by
-.Fn getnewvnode ,
+a kernel thread
 .Fn ungetnewvnode
 and
 .Fn vrecycle .
 Access to
 .Em v_usecount ,
 .Em v_writecount
 and
 .Em v_holdcnt
 is also protected by the
 .Em v_interlock
-simplelock.
+mutex.
 .Pp
 The number of pending synchronous and asynchronous writes on the
 vnode are recorded in
 .Em v_numoutput .
 It is used by
 .Xr fsync 2
 to wait for all writes to complete before returning to the user.
 Its value must only be modified at splbio (see
 .Xr spl 9 ) .
 It does not track the number of dirty buffers attached to the
 vnode.
 .Pp
 .Em v_dnclist
 @@ -324,28 +326,27 @@ See
 .Xr vnodeops 9
 for a description of vnode operations.
 .Pp
 When not in use, vnodes are kept on the freelist through
 .Em v_freelist .
 The vnodes still reference valid files but may be reused to refer to a
 new file at any time.
 When a valid vnode which is on the freelist is used again, the user
 must call
 .Fn vget
 to increment the reference count and retrieve it from the freelist.
 When a user wants a new vnode for another file,
 .Fn getnewvnode
-is invoked to remove a vnode from the freelist and initialize it for
+is invoked to allocate a vnode and initialize it for the new file.
 the new file.
 .Pp
 The type of object the vnode represents is recorded by
 .Em v_type .
 It is used by generic code to perform checks to ensure operations are
 performed on valid file system objects.
 Valid types are:
 .Pp
 .Bl -tag -offset indent -width VFIFO -compact
 .It VNON
 The vnode has no type.
 .It VREG
 The vnode represents a regular file.
 .It VDIR
 @@ -519,36 +520,38 @@ and
 are zero, the vnode is placed on the freelist.
 .It Fn vrele_async "vp"
 Will asychronously release the vnode in different context than the caller,
 sometime after the call.
 .It Fn vget "vp" "lockflags"
 Reclaim vnode
 .Fa vp
 from the freelist, increment its reference count and lock it.
 The argument
 .Fa lockflags
 specifies the
 .Xr rwlock 9
 flags used to lock the vnode.
-If the VXLOCK is set in
+If the
 .Em VI_XLOCK
 is set in
 .Fa vp Ns 's
 .Em v_flag ,
 vnode
 .Fa vp
 is being recycled in
 .Fn vgone
 and the calling thread sleeps until the transition is complete.
 When it is awakened, an error is returned to indicate that the vnode is
-no longer usable (possibly having been recycled to a new file system type).
+no longer usable.
 .It Fn vput "vp"
 Unlock vnode
 .Fa vp
 and decrement its
 .Em v_usecount .
 Depending on the reference counts, move the vnode to the holdlist or
 the freelist.
 This operation is functionally equivalent to calling
 .Xr VOP_UNLOCK 9
 followed by
 .Fn vrele .
 .It Fn vhold "vp"
 Mark the vnode
 @@ -558,34 +561,27 @@ as active by incrementing
 and moving the vnode from the freelist to the holdlist.
 Once on the holdlist, the vnode will not be recycled until it is
 released with
 .Fn holdrele .
 .It Fn holdrele "vp"
 Mark the vnode
 .Fa vp
 as inactive by decrementing
 .Em vp-\*[Gt]v_holdcnt
 and moving the vnode from the holdlist to the freelist.
 .It Fn getnewvnode "tag" "mp" "vops" "slock" "vpp"
 Retrieve the next vnode from the freelist.
 .Fn getnewvnode
-must choose whether to allocate a new vnode or recycle an existing
+allocates a new vnode.
 one.
 The criterion for allocating a new one is that the total number of
 vnodes is less than the number desired or there are no vnodes on either
 free list.
 Generally only vnodes that have no buffers associated with them are
 recycled and the next vnode from the freelist is retrieved.
 If the freelist is empty, vnodes on the holdlist are considered.
 The new vnode is returned in the address specified by
 .Fa vpp .
 .Pp
 The argument
 .Fa mp
 is the mount point for the file system requested the new vnode.
 Before retrieving the new vnode, the file system is checked if it is
 busy (such as currently unmounting).
 An error is returned if the file system is unmounted.
 .Pp
 The argument
 .Fa tag
 is the vnode tag assigned to
 @@ -610,27 +606,27 @@ If
 .It Fn ungetnewvnode "vp"
 Undo the operation of
 .Fn getnewvnode .
 The argument
 .Fa vp
 is the vnode to return to the freelist.
 This function is needed for
 .Xr VFS_VGET 9
 which may need to push back a vnode in case of a locking race
 condition.
 .It Fn vrecycle "vp" "inter_lkp"
 Recycle the unused vnode
 .Fa vp
-to the front of the freelist.
+from the front of the freelist.
 .Fn vrecycle
 is a null operation if the reference count is greater than zero.
 .It Fn vgone "vp"
 Eliminate all activity associated with the unlocked vnode
 .Fa vp
 in preparation for recycling.
 .It Fn vgonel "vp" "p"
 Eliminate all activity associated with the locked vnode
 .Fa vp
 in preparation for recycling.
 .It Fn vflush "mp" "skipvp" "flags"
 Remove any vnodes in the vnode table belonging to mount point
 .Fa mp .