Vnode identity, references, and reclamation

Identity and dispatch

A vnode provides a common identity and operation vector for a filesystem object. Its mount association, type, filesystem-private data, lock, and references describe different aspects of its state. An inode is one filesystem’s representation; code using VFS should not assume that every vnode’s private data has an inode layout.

VOP_* operations dispatch through the vnode operation vector. VFS_* operations are filesystem/mount-level interfaces. A filesystem implements the relevant operations, while the common layer supplies helpers, defaults, dispatch interfaces, and shared lifecycle machinery.

vnode_if.src describes vnode-operation arguments and locking annotations. Its generated interfaces should be read together with the implementation’s contract when deciding whether a particular vnode must be locked on entry or is returned locked on success.

Creation and acquisition

getnewvnode() allocates and initializes common vnode state for an operation vector and mount. Filesystem-specific initialization and insertion into an identity cache are additional work. Allocation does not itself create a pathname or an open file descriptor.

An existing vnode can be found through a filesystem’s identity mechanism or the namecache. Obtaining a pointer from such a structure is not sufficient to use the object indefinitely. The lookup must establish the relevant reference, and a caller that needs a lock must also obtain it.

vget() combines reference-acquisition machinery with locking. Its preparation and finish paths handle races with reclamation; the source documents cases where a vnode becomes doomed before the lock is acquired. The returned status and lock flags are part of the caller’s contract.

Use references and holds

v_usecount tracks use references. vref() adds a reference to a vnode whose lifetime the caller has already established. It is not a general recovery operation for a stale pointer.

v_holdcnt serves a different lifetime role. vhold() and vdrop() manipulate holds used by internal users and caches. A hold does not guarantee that the vnode continues to represent the same usable filesystem object: reclamation and dooming remain relevant.

The source’s atomic reference operations allow many common paths to avoid the vnode interlock, but the last-reference cases need additional coordination. A reference-count decrement that looks simple at its call site can enter inactive or reclamation-related processing.

Release interfaces are not interchangeable

Release contracts in vfs_subr.c

Interface

Lock and reference behavior

vrele()

Drops a use reference and preserves the caller’s incoming vnode-lock state; the vnode interlock must not be held.

vput()

Requires a locked vnode, drops a use reference, and returns unlocked.

vunref()

Drops a use reference while keeping the vnode locked.

vdrop()

Drops a hold reference, rather than a use reference.

Use the interface matching the state actually returned by lookup or acquisition. Do not add an independent unlock after an operation that has already consumed the lock, or replace a use-reference release with a hold release because both appear to decrease a counter.

Inactive, doomed, and freed

Releasing the last use reference can trigger inactive processing. It does not imply that the vnode allocation is immediately freed: cached identity, holds, and filesystem state can keep it around.

Reclamation tears down the filesystem association and dooms the vnode. Final allocation release depends on the remaining lifetime state. vfs_subr.c contains the corresponding transitions and assertions, while the vnode reclamation worker manages pressure on the vnode cache.

When reviewing a vnode user, trace creation/acquisition, use references, holds, vnode locking, and mount protection separately. A counter or lock protecting one lifetime should not be assumed to protect all the others.