Mount lifetime and VFS locking

Mount state and references

A mount represents an instance of a filesystem and its filesystem-level operations. Vnodes associated with it, covered mount points, root vnodes, and global mount-list membership link it into the namespace.

vfs_mount.c implements mount and unmount paths together with mount reference operations. vfs_ref() and vfs_rel() protect mount allocation lifetime. A mount reference alone should not be interpreted as permission to start an operation that must exclude unmounting.

vfs_busy() and vfs_unbusy() provide a separate form of protection for operations that need to coordinate with unmount. The busy path supports flags that affect waiting and mount-list lock handling. A failure to busy the mount must be handled before relying on that protection.

Mount traversal and vnode locks

Crossing a mount point can require dropping vnode locks, busying a mount, obtaining a root vnode, and reacquiring the next required lock. Stacked filesystems can make apparently different vnode identities share a lock.

The extensive comment before vfs_busy() in vfs_subr.c explains the ordering problem with mount-point traversal and unmount. Preserve the established protocol rather than keeping an extra vnode lock solely to avoid a retry. An extra held lock can create an ordering reversal.

The vnode lock, vnode interlock, mount interlock, and mount-list lock protect different state. Lookup’s lockless fast path additionally relies on its own lifetime and sequence checks. No one of these mechanisms is a substitute for identifying the complete operation’s lock protocol.

Write suspension

Filesystem operations that participate in write suspension coordinate with the mount’s write accounting. vn_start_write() obtains the appropriate write mount and begins that protocol; successful participation must be paired with vn_finished_write() as required by the calling path.

The helper has blocking and nonblocking behavior controlled by flags, and VOP_GETWRITEMOUNT can identify a write mount different from the vnode’s immediate mount. This matters for layered filesystems. Error paths must respect the returned mount and reference state rather than blindly applying the successful-path cleanup.

An ordinary mount reference, a busy mount, and a write-suspension count are three different protections. Match the release operation to the protection that was actually acquired.

Interaction with VM and I/O

Filesystem and VM code can both need the vnode and its backing object. An operation that may fault user memory or wait for pager I/O must respect that interaction. vfs_vnops.c contains explicit handling to avoid problematic faults while performing vnode I/O.

Consult VM locking and lifetime rules when a filesystem path starts VM work. In particular, retaining a vnode reference does not make an arbitrary lock safe to hold while faulting or sleeping.

Reviewing an operation

For each entry and exit path, identify:

  • The vnode use references and holds, and which helper consumes each.

  • Whether the leaf and parent vnode locks are held or may be the same lock.

  • The mount references, busy protection, and write-suspension participation.

  • The points where locks are dropped and lookup or mount state is revalidated.

  • The cleanup after a failed lookup, interrupted wait, or unmount race.

Use the operation annotations in vnode_if.src, source assertions, and WITNESS/INVARIANTS checks to validate the protocol. A successful single-threaded operation is not enough to establish correctness against rename, reclamation, and unmount activity.