#	$NetBSD: vnode_if.src,v 1.44 2005/02/26 22:14:39 perry Exp $
#
# Copyright (c) 1992, 1993
#	The Regents of the University of California.  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, this list of conditions and the following disclaimer.
# 2. Redistributions in binary form must reproduce the above copyright
#    notice, this list of conditions and the following disclaimer in the
#    documentation and/or other materials provided with the distribution.
# 3. All advertising materials mentioning features or use of this software
#    must display the following acknowledgement:
#	This product includes software developed by the University of
#	California, Berkeley and its contributors.
# 4. Neither the name of the University nor the names of its contributors
#    may be used to endorse or promote products derived from this software
#    without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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.
#
#	@(#)vnode_if.src	8.14 (Berkeley) 8/6/95
#
#

# 
# Above each of the vop descriptors is a specification of the locking
# protocol used by each vop call.  The first column is the name of
# the variable, the remaining three columns are in, out and error
# respectively.  The "in" column defines the lock state on input,
# the "out" column defines the state on successful return, and the
# "error" column defines the locking state on error exit.
#     
# The locking value can take the following values:
# L: locked.
# U: unlocked.
# -: not applicable.  vnode does not yet (or no longer) exists.
# =: the same on input and output, may be either L or U.
# X: locked if not nil.
#
# For operations other than VOP_LOOKUP which require a component name
# parameter, the flags required for the initial namei() call are listed.
# Additional flags may be added to the namei() call, but these are required.
#     
 
#
#% lookup     dvp     L ? ?
#% lookup     vpp     - L -
#
# XXX - the lookup locking protocol defies simple description and depends
#     on the flags and operation fields in the (cnp) structure.  Note
#     especially that *vpp may equal dvp and both may be locked.
#
#    More details:
#     There are three types of lookups: ".", ".." (ISDOTDOT), and other.
#     On successful lookup of ".", a reference is added to dvp, and it
#          is returned in *vpp.
#     To look up ISDOTDOT, dvp is unlocked, the ".." node is locked, and
#          then dvp is relocked iff LOCKPARENT is set and this is the last
#          component name (ISLASTCN set). This preserves the
#          protocol of always locking nodes from root ("/") downward and
#          prevents deadlock.
#     Other lookups find the named node (creating the vnode if needed) and
#          return it, locked, in *vpp.
#     For non-"." lookups, if LOCKPARENT is not set or this was not the
#          last component name, dvp is returned unlocked on a successful
#          lookup.
#     On failure, *vpp is NULL, and *dvp is left locked. If there was
#          an error re-locking dvp (for instance in the ISDOTDOT case),
#          the error is returned with PDIRUNLOCK set.
#	
#     *vpp is always locked on return if the operation succeeds.
#     typically, if *vpp == dvp, you need to release twice, but unlock once.
#
#     The PDIRUNLOCK flag is set when dvp is unlocked in the lookup routine.
#          It signals the caller that dvp's lock state changed. It will
#          be set on exit if either a successful lookup unlocked the
#          parrent, or there was an error re-locking dvp in the ISDOTDOT case.
#
#     See sys/sys/namei.h for a description of the SAVENAME and SAVESTART
#          flags.
#
vop_lookup {
	IN struct vnode *dvp;
	INOUT struct vnode **vpp;
	IN struct componentname *cnp;
};

#
#% create     dvp     L U U
#% create     vpp     - L -
#
#! create cnp	CREATE, LOCKPARENT
#
vop_create {
	IN LOCKED=YES WILLPUT struct vnode *dvp;
	OUT struct vnode **vpp;
	IN struct componentname *cnp;
	IN struct vattr *vap;
};

#
#% mknod      dvp     L U U
#% mknod      vpp     - L -
#
#! mknod cnp	CREATE, LOCKPARENT
#
vop_mknod {
	IN LOCKED=YES WILLPUT struct vnode *dvp;
	OUT struct vnode **vpp;
	IN struct componentname *cnp;
	IN struct vattr *vap;
};

#
#% open               vp      L L L
#
vop_open {
	IN LOCKED=YES struct vnode *vp;
	IN int mode;
	IN struct ucred *cred;
	IN struct proc *p;
};

#
#% close      vp      L L L
#
vop_close {
	IN LOCKED=YES struct vnode *vp;
	IN int fflag;
	IN struct ucred *cred;
	IN struct proc *p;
};

#
#% access     vp      L L L
#
vop_access {
	IN LOCKED=YES struct vnode *vp;
	IN int mode;
	IN struct ucred *cred;
	IN struct proc *p;
};

#
#% getattr    vp      = = =
#
vop_getattr {
	IN struct vnode *vp;
	IN struct vattr *vap;
	IN struct ucred *cred;
	IN struct proc *p;
};

#
#% setattr    vp      L L L
#
vop_setattr {
	IN LOCKED=YES struct vnode *vp;
	IN struct vattr *vap;
	IN struct ucred *cred;
	IN struct proc *p;
};

#
#% read               vp      L L L
#
vop_read {
	IN LOCKED=YES struct vnode *vp;
	INOUT struct uio *uio;
	IN int ioflag;
	IN struct ucred *cred;
};

#
#% write      vp      L L L
#
vop_write {
	IN LOCKED=YES struct vnode *vp;
	INOUT struct uio *uio;
	IN int ioflag;
	IN struct ucred *cred;
};

#
#% ioctl      vp      U U U
#
vop_ioctl {
	IN LOCKED=NO struct vnode *vp;
	IN u_long command;
	IN void *data;
	IN int fflag;
	IN struct ucred *cred;
	IN struct proc *p;
};

#
#% fcntl      vp      L L L
#
vop_fcntl {
	IN LOCKED=YES struct vnode *vp;
	IN u_int command;
	IN void *data;
	IN int fflag;
	IN struct ucred *cred;
	IN struct proc *p;
};

#
#% poll     vp      U U U
#
vop_poll {
	IN LOCKED=NO struct vnode *vp;
	IN int events;
	IN struct proc *p;
};

#
#% kqfilter     vp      U U U
#
vop_kqfilter {
	IN LOCKED=NO struct vnode *vp;
	IN struct knote *kn;
};

#
#% revoke     vp      U U U
#
vop_revoke {
	IN LOCKED=NO struct vnode *vp;
	IN int flags;
};

#     
#% mmap      vp      = = =
#
vop_mmap {
	IN struct vnode *vp;
	IN int fflags;
	IN struct ucred *cred;
	IN struct proc *p;
};

#
#% fsync      vp      L L L
#
vop_fsync {
	IN LOCKED=YES struct vnode *vp;
	IN struct ucred *cred;
	IN int flags;
	IN off_t offlo;
	IN off_t offhi;
	IN struct proc *p;
};

#
# Needs work: Is newoff right?  What's it mean?
# XXX Locking prototocl?
#
vop_seek {
	IN struct vnode *vp;
	IN off_t oldoff;
	IN off_t newoff;
	IN struct ucred *cred;
};

#
#% remove     dvp     L U U
#% remove     vp      L U U
#
#! remove cnp	DELETE, LOCKPARENT | LOCKLEAF
#
vop_remove {
	IN LOCKED=YES WILLPUT struct vnode *dvp;
	IN LOCKED=YES WILLPUT struct vnode *vp;
	IN struct componentname *cnp;
};

#
#% link               vp      U U U
#% link               dvp     L U U
#
#! link	 cnp	CREATE, LOCKPARENT
#
vop_link {
	IN LOCKED=YES WILLPUT struct vnode *dvp;
	IN LOCKED=NO struct vnode *vp;
	IN struct componentname *cnp;
};

#
#% rename     fdvp    U U U
#% rename     fvp     U U U
#% rename     tdvp    L U U
#% rename     tvp     X U U
#
#! rename fcnp	DELETE,	WANTPARENT | SAVESTART
#! rename tcnp	RENAME, LOCKPARENT | LOCKLEAF | NOCACHE | SAVESTART
#
# XXX the vop_rename routines should REALLY NOT be depending on SAVESTART!
#
vop_rename {
	IN LOCKED=NO WILLRELE struct vnode *fdvp;
	IN LOCKED=NO WILLRELE struct vnode *fvp;
	IN struct componentname *fcnp;
	IN LOCKED=YES WILLPUT struct vnode *tdvp;
	IN WILLPUT struct vnode *tvp;
	IN struct componentname *tcnp;
};

#
#% mkdir      dvp     L U U
#% mkdir      vpp     - L - 
#
#! mkdir cnp	CREATE, LOCKPARENT
#
vop_mkdir {
	IN LOCKED=YES WILLPUT struct vnode *dvp;
	OUT struct vnode **vpp;
	IN struct componentname *cnp;
	IN struct vattr *vap;
};

#
#% rmdir      dvp     L U U
#% rmdir      vp      L U U
#
#! rmdir cnp	DELETE, LOCKPARENT | LOCKLEAF
#
vop_rmdir {
	IN LOCKED=YES WILLPUT struct vnode *dvp;
	IN LOCKED=YES WILLPUT struct vnode *vp;
	IN struct componentname *cnp;
};

#
#% symlink    dvp     L U U
#% symlink    vpp     - L -
#
#! symlink cnp	CREATE, LOCKPARENT
#
vop_symlink {
	IN LOCKED=YES WILLPUT struct vnode *dvp;
	OUT struct vnode **vpp;
	IN struct componentname *cnp;
	IN struct vattr *vap;
	IN char *target;
};

#
#% readdir    vp      L L L   
#
vop_readdir {
	IN LOCKED=YES struct vnode *vp;
	INOUT struct uio *uio;
	IN struct ucred *cred;
	OUT int *eofflag;
	OUT off_t **cookies;
	IN int *ncookies;
};

#
#% readlink   vp      L L L
#
vop_readlink {
	IN LOCKED=YES struct vnode *vp;
	INOUT struct uio *uio;
	IN struct ucred *cred;
};

#
#% abortop    dvp     = = =
#
#! abortop cnp	as appropriate.
#
vop_abortop {
	IN struct vnode *dvp;
	IN struct componentname *cnp;
};

#
#% inactive   vp      L U U  
#
vop_inactive {
	IN LOCKED=YES WILLUNLOCK struct vnode *vp;
	IN struct proc *p;
};

#
#% reclaim    vp      U U U
#
vop_reclaim {
	IN LOCKED=NO struct vnode *vp;
	IN struct proc *p;
};

#
#% lock               vp      U L U
#
vop_lock {
	IN LOCKED=NO struct vnode *vp;
	IN int flags;
};

#
#% unlock     vp      L U L
#
vop_unlock {
	IN LOCKED=YES struct vnode *vp;
	IN int flags;
};

#
#% bmap               vp      = = =
#% bmap               vpp     - U -
#
vop_bmap {
	IN LOCKED=YES struct vnode *vp;
	IN daddr_t bn;
	OUT struct vnode **vpp;
	IN daddr_t *bnp;
	OUT int *runp;
};

#
#% strategy   vp      = = =
#
vop_strategy {
	IN struct vnode *vp;
	IN struct buf *bp;
};

#
#% print      vp      = = =
#
vop_print {
	IN struct vnode *vp;
};

#
#% islocked   vp      = = =
#
vop_islocked {
	IN struct vnode *vp;
};

#
#% pathconf   vp      L L L
#
vop_pathconf {
	IN LOCKED=YES struct vnode *vp;
	IN int name;
	OUT register_t *retval;
};

#
#% advlock    vp      U U U
#
vop_advlock {
	IN LOCKED=NO struct vnode *vp;
	IN void *id;
	IN int op;
	IN struct flock *fl;
	IN int flags;
};

#
#% blkatoff   vp      L L L
#
vop_blkatoff {
	IN LOCKED=YES struct vnode *vp;
	IN off_t offset;
	OUT char **res;
	OUT struct buf **bpp;
};

#
#% valloc     pvp     L L L
#
vop_valloc {
	IN LOCKED=YES struct vnode *pvp;
	IN int mode;
	IN struct ucred *cred;
	OUT struct vnode **vpp;
};

#
#% balloc     vp      L L L
#
vop_balloc {
	IN LOCKED=YES struct vnode *vp;
	IN off_t startoffset;
	IN int size;
	IN struct ucred *cred;	
	IN int flags;
	OUT struct buf **bpp;
};

#
#% reallocblks        vp      L L L
#
vop_reallocblks {
	IN LOCKED=YES struct vnode *vp;
	IN struct cluster_save *buflist;
};

#
#% vfree      pvp     L L L
#
vop_vfree {
	IN LOCKED=YES struct vnode *pvp;
	IN ino_t ino;
	IN int mode;
};

#
#% truncate   vp      L L L
#
vop_truncate {
	IN LOCKED=YES struct vnode *vp;
	IN off_t length;
	IN int flags;
	IN struct ucred *cred;
	IN struct proc *p;
};

#
#% update     vp      L L L
#
vop_update {
	IN LOCKED=YES struct vnode *vp;
	IN struct timespec *access;
	IN struct timespec *modify;
	IN int flags;
};

# 
#% lease      vp      = = =
# 
vop_lease {
	IN struct vnode *vp;
	IN struct proc *p;
	IN struct ucred *cred;
	IN int flag;
};

#
#% whiteout   dvp     L L L
#% whiteout   cnp     - - -
#% whiteout   flag    - - -
#
#! whiteout cnp	CREATE, LOCKPARENT
# 
vop_whiteout {
	IN LOCKED=YES struct vnode *dvp;
	IN struct componentname *cnp;
	IN int flags;
};

#
# Needs work: no vp?
#
#vop_bwrite {
#	IN struct buf *bp;
#};

#
#% getpages	vp = = =
#
vop_getpages {
	IN struct vnode *vp;
	IN voff_t offset;
	IN struct vm_page **m;
	IN int *count;
	IN int centeridx;
	IN vm_prot_t access_type;
	IN int advice;
	IN int flags;
};

#
#% putpages	vp = = =
#
vop_putpages {
	IN struct vnode *vp;
	IN voff_t offlo;
	IN voff_t offhi;
	IN int flags;
};

#
#% closeextattr	vp L L L
#
vop_closeextattr {
	IN LOCKED=YES struct vnode *vp;
	IN int commit;
	IN struct ucred *cred;
	IN struct proc *p;
};

#
#% getextattr	vp L L L
#
vop_getextattr {
	IN LOCKED=YES struct vnode *vp;
	IN int attrnamespace;
	IN const char *name;
	INOUT struct uio *uio;
	OUT size_t *size;
	IN struct ucred *cred;
	IN struct proc *p;
};

#
#% listextattr	vp L L L
#
vop_listextattr {
	IN LOCKED=YES struct vnode *vp;
	IN int attrnamespace;
	INOUT struct uio *uio;
	OUT size_t *size;
	IN struct ucred *cred;
	IN struct proc *p;
};

#
#% openextattr	vp L L L
#
vop_openextattr {
	IN LOCKED=YES struct vnode *vp;
	IN struct ucred *cred;
	IN struct proc *p;
};

#
#% deleteextattr vp L L L
#
vop_deleteextattr {
	IN LOCKED=YES struct vnode *vp;
	IN int attrnamespace;
	IN const char *name;
	IN struct ucred *cred;
	IN struct proc *p;
};

#
#% setextattr	vp L L L
#
vop_setextattr {
	IN LOCKED=YES struct vnode *vp;
	IN int attrnamespace;
	IN const char *name;
	INOUT struct uio *uio;
	IN struct ucred *cred;
	IN struct proc *p;
};