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. :c:func:`vfs_ref` and :c:func:`vfs_rel` protect mount allocation lifetime. A mount reference alone should not be interpreted as permission to start an operation that must exclude unmounting. :c:func:`vfs_busy` and :c:func:`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. :c:func:`vn_start_write` obtains the appropriate write mount and begins that protocol; successful participation must be paired with :c:func:`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 :doc:`../vm/locking` 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.