VFS, filesystems, and storage I/O

Guide index · Architecture

The virtual filesystem layer connects BSD file operations, pathname resolution, filesystem implementations, VM-backed file contents and device I/O. Its central object is the vnode: an in-memory handle for a filesystem object, with an operation vector and filesystem-private state. A vnode can represent a regular file, directory, device, FIFO, socket or other supported object; it is not synonymous with an on-disk inode.

Read vnodes, mounts and dispatch first. Then follow pathname lookup and authorization, file data and I/O completion, and the in-tree filesystems and NFS survey. The VM chapter covers the other side of file-backed mappings and page faults.

The mapped-file worked operation connects these paths: descriptor lookup and release, vnode/UBC/pager identity, a cold read fault, private COW write, ARM64 translation and unmapping. Its file coordinate remains explicit across clustered page-in and changing VM object offsets.

Continue into the detailed implementation chapters:

For signed files, continue from those caches into signature format and structural checks → attachment to the vnode's UBC state → exec and mapping policy → page hashing and cached validation. A name-cache hit, a resident data page, an accepted cs_blob, and an executable mapping are separate results.

The file structure route connects descriptor tables and fileproc/fileglob storage to vnode identity, UBC/pager allocation and lifetime, and RO signature attachments. Use these companions for field access, references, publication and final storage release.

The main boundaries

Mermaid source

flowchart TD
    SYS[BSD open/read/write/mmap] --> FD[fileproc / fileglob]
    SYS --> NAME[namei / lookup / name cache]
    NAME --> VN[vnode and filesystem vnode operations]
    FD --> VN
    VN --> AUTH[Vnode authorization / MAC checks]
    VN --> FS[Filesystem implementation]
    MOUNT[mount / VFS operations] --> FS
    FS --> UBC[UBC / VM object / clustered I/O]
    VM[VM fault and pageout] --> UBC
    UBC --> BUF[buf I/O descriptions]
    FS --> BUF
    BUF --> DEV[Device strategy / storage stack]
    NET[NFS server RPC] --> VN

The filesystem decides whether and how to use clustered I/O. A generic VNOP_READ wrapper does not automatically invoke the buffer cache, and a read can finish entirely from resident UBC pages. Device and network-backed objects take different routes.

What this tree contains

The checkout supplies the generic VFS infrastructure and small filesystems/layers under bsd/miscfs. It does not supply the APFS filesystem implementation or a complete physical storage-driver stack. Calls through registered vfsops, vnode operation vectors and block/character device switches cross those boundaries. The presence of APFS-specific integration or ioctl names elsewhere in XNU does not expose APFS's allocation, transaction or on-disk algorithms.

Likewise, the available bsd/nfs implementation is chiefly the NFS server, RPC and GSS support. There is no client nfs_vfsops.c or nfs_vnops.c here. nfs_register_hooks exposes integration hooks for externally supplied behavior. The final chapter distinguishes what can actually be traced from this checkout from those missing implementations.

Useful reading routes

• Opening /a/b: openat_internal → open1at/open1 → vn_open_auth → namei/lookup → cache or VNOP_LOOKUP → authorization/open → a vnode-backed fileglob.
• Reading an open file: read_internal → readv_internal → fp_readv → fo_read → vn_read → VNOP_READ → the selected filesystem's read method.
• Reading missing file data: a filesystem using cluster_read obtains UPL pages, maps file extents, sends strategy requests and commits completed pages. A mapping fault arrives through the vnode pager and VNOP_PAGEIN instead.
• Reclaiming a vnode: drain active I/O references → clean buffers/UBC as required → VNOP_INACTIVE/VNOP_RECLAIM → remove cached identity and replace operations with dead-vnode behavior.

These are reading routes, not exhaustive call graphs: compound operations, retries, cached fast paths and configuration branches alter the sequence.

Sources inspected and limits

“Deep” means the named structures and selected multi-stage paths were read; it does not mean every branch of these large files was audited.

Useful adjacent originals are the VM pageout description and startup description. The devfs README explicitly identifies itself as inherited FreeBSD 3.1 commentary: use current source, rather than that historical feature list, for this version's behavior.