View source for 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 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.