Kernel: vfile

Overview

The vfile (virtual file) object in the IRIX kernel represents an open file description — the kernel-side structure that corresponds to an open file shared across processes (via fork, dup, etc.). It holds per-open state such as reference count, open flags, credentials, associated vnode or vsocket, and a behavior chain head for stacked behaviors (notably the pfile behavior for offset management). The vfile layer sits between the per-process file descriptor table (fdt) and lower-level objects (vnode for files, vsocket for sockets). It manages reference counting, close semantics (including double-close protocol for races), credential handling, and integration with distributed (Cellular IRIX) features. The implementation emphasizes thread/sproc safety via spinlocks and careful race avoidance during close.

Key Functions

Initialization (vfile_init) Initializes the file_zone for efficient allocation of vfile_t structures, sets up debugging lists/locks, calls vfile_cell_init() (distributed support) and pfile_init(). Creation (vfile_create) Allocates a vfile_t from the zone, initializes:

Spinlock (vf_lock) Reference count = 1 Flags and credential hold Behavior chain head (vf_bh) Links into debug active list Increments global SYSINFO.filecnt

Allocation for Open (vfile_alloc) Creates a vfile (with FINPROGRESS flag), allocates an fd via fdt_alloc, creates associated pfile behavior. Returns file pointer and fd; caller must call vfile_ready after successful VOP_OPEN. Activation (vfile_ready) Clears FINPROGRESS, sets associated vnode/vsocket pointer. Undo on Failed Open (vfile_alloc_undo) Reverses vfile_alloc when VOP_OPEN fails: removes fd, drops refcount, tears down pfile, destroys vfile. Close Protocol (vfile_close, vfile_close_common, vfile_ref_release) Implements a two-phase close to handle races between multiple threads/sprocs closing the same fd:

vfile_close: Calls VFILE_CLOSE with VFILE_FIRSTCLOSE to probe if last reference. vfile_close_common: Performs actual cleanup: Cleans locks if present Calls VOP_CLOSE (or VSOP_CLOSE) with appropriate lastclose flag Handles double-call race by potentially issuing extra VOP_CLOSE On true last close: flushes/invalidates if requested, releases vnode, removes GRIO reservations, tears down behaviors, destroys vfile

vfile_ref_release: Used for non-close reference drops (e.g., rfork cleanup); only performs full close if last reference.

Assignment Helper (vfile_assign) Convenience wrapper: allocates vfile/fd, performs VOP_OPEN (updating vnode pointer if changed), readies vfile on success, undoes on failure.

Undocumented or IRIX-Specific Interfaces and Behaviors

Critical Structures (from ksys/vfile.h)

vfile_t: int vf_count — reference count (shared opens) int vf_flag — open flags (FREAD, FWRITE, etc.) + internal (FINPROGRESS, FLCINVAL, FLCFLUSH, FPRIORITY) cred_t *vf_cred — held credentials of opener spinlock_t vf_lock — protects structure bhv_head_t vf_bh — head of behavior chain (pfile inserted here) void *vf_data — pointer to vnode_t or vsock_t (via VF_TO_VNODE/VF_TO_VSOCK) Debug links (vf_next, vf_prev) for active list

Macros: VFLOCK / VFUNLOCK — spinlock wrappers VFILE_CLOSE(fp, phase, info) — behavior chain dispatch for close VFILE_TEARDOWN(fp) — behavior chain teardown dispatch VF_IS_VNODE, VF_SET_DATA

Double-Close Protocol IRIX uses a two-call close pattern (VFILE_FIRSTCLOSE, VFILE_SECONDCLOSE) via behavior chain to safely determine last close in multiprocessor/shared-process environments. Prevents race where one thread tears down structure while another assumes it still exists. Flags and Special Handling

FINPROGRESS: Set during open until vfile_ready FLCINVAL / FLCFLUSH: Trigger VOP_FSYNC with invalidate or flush on last close FPRIORITY: Indicates GRIO (Guaranteed Rate I/O) reservation VFRLOCKS: Vnode has record locks → clean on close

Distributed Support References to DC/DS (Distributed Coordinator/Server) and VFILE_SKIPCLOSE indicate special handling in Cellular IRIX: last close may be deferred or coordinated remotely.

Similarities to illumos and BSD Kernel Implementations

illumos (Solaris-derived) Moderate similarity:

Per-open state in struct file (referenced by filedesc table) Reference counting and close races handled via closef() Vnode ops with VOP_CLOSE(last) Credential holding No behavior chaining; vnode ops direct No explicit pfile separation — offset in uio or per-read/write

Porting: illumos file closer to vfile than BSD, but lacks behavior chain and double-close protocol. BSD (FreeBSD, NetBSD, OpenBSD) Closer in some aspects:

struct file with reference count, flags, credential, pointer to fileops and data (vnode/socket) Double-close avoidance via careful refcounting closef() performs fdrop() → ops → free No behavior chaining; direct fops dispatch Offset not stored in file — managed per-I/O via uio

Porting: BSD struct file semantically similar to vfile. Main differences: no bhv chain, no explicit pfile layer, different lock strategy. Overall, IRIX vfile is unique due to bhv_desc_t behavior chaining and Kernel: pfile offset separation, designed for extensibility and Cellular IRIX distributed coherence. No direct equivalent in illumos/BSD for easy porting; closest analogs are struct file in both, but require adding behavior dispatch and double-close logic for fidelity.