svn commit: r348463 - stable/12/sys/kern

[Alan Somers]

Author: asomers
Date: Fri May 31 16:22:29 2019
New Revision: 348463
URL: https://svnweb.freebsd.org/changeset/base/348463

Log:
  MFC r346078:
  
  fix cache_lookup's documentation
  
  cache_lookup's documentation got dislocated by r324378. Relocate and expand
  it.
  
  Reviewed by:	jhb, kib
  Sponsored by:	The FreeBSD Foundation

Modified:
  stable/12/sys/kern/vfs_cache.c
Directory Properties:
  stable/12/   (props changed)

Modified: stable/12/sys/kern/vfs_cache.c
==============================================================================
--- stable/12/sys/kern/vfs_cache.c	Fri May 31 16:21:38 2019	(r348462)
+++ stable/12/sys/kern/vfs_cache.c	Fri May 31 16:22:29 2019	(r348463)
@@ -150,7 +150,7 @@ struct	namecache_ts {
  * Names found by directory scans are retained in a cache
  * for future reference.  It is managed LRU, so frequently
  * used names will hang around.  Cache is indexed by hash value
- * obtained from (vp, name) where vp refers to the directory
+ * obtained from (dvp, name) where dvp refers to the directory
  * containing name.
  *
  * If it is a "negative" entry, (i.e. for a name that is known NOT to
@@ -1129,23 +1129,6 @@ cache_lookup_dot(struct vnode *dvp, struct vnode **vpp
 	return (-1);
 }
 
-/*
- * Lookup an entry in the cache
- *
- * Lookup is called with dvp pointing to the directory to search,
- * cnp pointing to the name of the entry being sought. If the lookup
- * succeeds, the vnode is returned in *vpp, and a status of -1 is
- * returned. If the lookup determines that the name does not exist
- * (negative caching), a status of ENOENT is returned. If the lookup
- * fails, a status of zero is returned.  If the directory vnode is
- * recycled out from under us due to a forced unmount, a status of
- * ENOENT is returned.
- *
- * vpp is locked and ref'd on return.  If we're looking up DOTDOT, dvp is
- * unlocked.  If we're looking up . an extra ref is taken, but the lock is
- * not recursively acquired.
- */
-
 static __noinline int
 cache_lookup_nomakeentry(struct vnode *dvp, struct vnode **vpp,
     struct componentname *cnp, struct timespec *tsp, int *ticksp)
@@ -1229,6 +1212,42 @@ out_no_entry:
 	return (0);
 }
 
+/**
+ * Lookup a name in the name cache
+ *
+ * # Arguments
+ *
+ * - dvp:	Parent directory in which to search.
+ * - vpp:	Return argument.  Will contain desired vnode on cache hit.
+ * - cnp:	Parameters of the name search.  The most interesting bits of
+ *   		the cn_flags field have the following meanings:
+ *   	- MAKEENTRY:	If clear, free an entry from the cache rather than look
+ *   			it up.
+ *   	- ISDOTDOT:	Must be set if and only if cn_nameptr == ".."
+ * - tsp:	Return storage for cache timestamp.  On a successful (positive
+ *   		or negative) lookup, tsp will be filled with any timespec that
+ *   		was stored when this cache entry was created.  However, it will
+ *   		be clear for "." entries.
+ * - ticks:	Return storage for alternate cache timestamp.  On a successful
+ *   		(positive or negative) lookup, it will contain the ticks value
+ *   		that was current when the cache entry was created, unless cnp
+ *   		was ".".
+ *
+ * # Returns
+ *
+ * - -1:	A positive cache hit.  vpp will contain the desired vnode.
+ * - ENOENT:	A negative cache hit, or dvp was recycled out from under us due
+ *		to a forced unmount.  vpp will not be modified.  If the entry
+ *		is a whiteout, then the ISWHITEOUT flag will be set in
+ *		cnp->cn_flags.
+ * - 0:		A cache miss.  vpp will not be modified.
+ *
+ * # Locking
+ *
+ * On a cache hit, vpp will be returned locked and ref'd.  If we're looking up
+ * .., dvp is unlocked.  If we're looking up . an extra ref is taken, but the
+ * lock is not recursively acquired.
+ */
 int
 cache_lookup(struct vnode *dvp, struct vnode **vpp, struct componentname *cnp,
     struct timespec *tsp, int *ticksp)