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¶
Interface |
Lock and reference behavior |
|---|---|
Drops a use reference and preserves the caller’s incoming vnode-lock state; the vnode interlock must not be held. |
|
Requires a locked vnode, drops a use reference, and returns unlocked. |
|
|
Drops a use reference while keeping the vnode locked. |
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.