Filesystem
kernel/src/fs/ · VFS and the dcache, ext4/jbd2, bio/buffer cache, /proc derivation and file-ops declaration — mechanisms, data structures and measured numbers · Scale: ext4 17,486 lines + jbd2 3,899 lines · Sources: design-divergences.md (D-4/D-6/D-8/D-12/D-13), docs/development/f4-ext4-route-map.md
§1VFS: dentry / inode / mounts
- Dentry structure (dentry.rs): name/parent/children (BTreeMap)/inode under a Spinlock, plus atomic mirrors — ref_count, negative, is_mountpoint (AtomicBool: "one Relaxed load instead of the vfsmount spinlock"), and inode_ptr (a lock-free AtomicPtr mirror).
- The mount-point back pointer is Weak: the mount-point dentry holds the vfsmount, and the vfsmount strongly holds this dentry — a strong back edge would form an Arc cycle, so Weak breaks it.
- Second-level dcache: a 256-bucket FNV-1a hash table with LRU eviction (DCACHE_SIZE=256); path construction (build_path_rooted) mirrors Linux's prepend_path() including chroot semantics and getcwd ENOENT, with a depth cap of 256.
- Mount namespaces: the global MOUNT_TABLE handles only boot-time bookkeeping and init-ns seeding; the authoritative view is the per-namespace MountNamespace (sc98: private-namespace mounts once pumped dead rows into the global table — OH appspawn children issue ~50 sandbox binds per spawn). The MntFlags bit set covers MNT_READONLY/SHARED/SLAVE/UNBINDABLE/NOSYMFOLLOW; MS_* translation is concentrated in mount.rs; the global MOUNT_SEQ attach sequence guarantees MS_REC clones attach parents before children.
- fd table: get_file is an RCU-style reader — one raw slot load plus one RMW; get_file runs 130M+ times per boot, and the retired-slot drain handshake (the FdTable lever-B protocol) is where that protocol was first shaped, later generalized to the dentry reader banks.
§2WalkClaim reader bank: lock-free path walking
Every path component once paid two spinlock pairs (children + inode). The WalkClaim protocol eliminates them:
- Reader side: 16 cacheline-padded per-CPU reader-bank counters; WalkClaim::acquire is a SeqCst increment of this CPU's bank and Drop decrements; an out-of-range cpu id degrades to the DENTRY_SLOW_READ irqsave lock.
- Writer side: mutations bump children_ver and park the removed Arcs in the DENTRY_RET_DENTRY/RET_INODE retired lists; dentry_drain_if_quiescent adjudicates quiescence with a SeqCst fence plus a scan for all banks at zero (64-scan budget; past the budget it defers and counts DRAIN_DEFERS), and the release happens under the slow lock.
- Memo hit path: version check + a per-slot seqlock pair + one name compare — no lock, no refcount traffic; the miss path refills under the children lock.
- Measured: the two per-component spinlock pairs totaled ~39 ns + ~20 ns per component (fsw pathcost probe); A/B: stat 0.643→0.423 µs, open 1.128→0.889 µs. The first landing was reverted (724867a0) and re-landed after stale-memo routing was hardened (ea26d923).
Negative memo cache
- Negative dentries are stamped with the parent inode's content generation (neg_gen) — bind-mount aliases are separate dentries over one inode, so a mutation through ANY alias invalidates memos cached under every alias.
- A per-parent cap of 32 entries (NEG_MEMO_CAP, defending the one-Dentry-plus-String-per-ENOENT ALLOCTHROUGH family); eviction at the cap, positive children never replaced; enabled only for filesystems whose content changes exclusively through VFS mutations (ext4) — procfs/devfs/sysfs never memo.
- Oracle measurements: the negstorm probe (create/link/rename-in/mkdir/symlink churn, 8/16 workers, 180 s) accumulated 475k negative hits and 963k stale normalizations with zero stale-negative deliveries, ghost entries, or verification failures.
§3ext4 (12 files, 17,486 lines)
Mount feature gates
KNOWN_INCOMPAT = FILETYPE|RECOVER|EXTENTS|B64BIT|FLEX_BG|ENCRYPT— ENCRYPT is a filesystem capability flag and is accepted, not refused: refusing it once blocked the stock OH userdata partition with ENODEV (/data dead, the whole service mkdir storm failing err=2/5). The REJECTED set = COMPRESSION|JOURNAL_DEV|META_BG|MMP|EA_INODE|DIRDATA|CSUM_SEED|LARGEDIR|INLINE_DATA; unknown incompat features refuse the mount; BIGALLOC and METADATA_CSUM refuse outright (with sb checksum validation).- ext3 is the ext4 driver's alias (the Linux ≥ 4.3 form); the first ext4 mount is THE root instance (journal replay) and additional disks take separate instances; re-mounting a live ext4 is refused with EBUSY — journal recovery must not re-run on a live journal.
Read path: miss-window batch fill (D-12)
- On a page-cache miss, the whole miss window is filled in one round trip: fill_page_cache_batch resolves each uncached page's physical block, coalesces physically-contiguous runs into single multi-block device requests (bread_async_multi, ≤64 blocks / 128 KiB per request, ≤512 blocks per batch), and drains everything with one sleep/wake cycle.
- Quantified motivation: pre-fix, each page miss paid one synchronous submit/sleep/wake (~1.8 ms under TCG) — starting desktop-scale images in acceptable time requires this design. The coherency guard: block_cached splits runs at the first already-cached block ("the Xorg xkbcomp lesson").
- Known cost: the entire miss path sits under EXT4_BIG_LOCK (a registered correctness-first trade).
Write path: batched metadata publish + discard-on-free (D-13)
- Publication batching: bio::publication_batch_drain fires only at ext4_journal_stop close once the pending queue crosses PUB_BATCH=64 (PUB_HIGH_WATER=2 batches).
- Discard-on-free: free_block_run drops dirty, unreferenced buffer-cache entries and jbd2_journal_forget — dead blocks are never written back.
- Full-block overwrite skip read: getblk_overwrite eliminates the read-modify-write.
- Measured: p6_mkdrmdir median 29,796 → 3,742 (publication batching) → 2,107 µs (discard-on-free), p99 54 → 16.4 ms.
jbd2 direct-write commit (D-8)
- commit syncs the transaction's buffers through to their final on-disk locations and advances the log tail/head past the transaction's journal-area records in the same commit — a completed commit leaves nothing replayable (recovery starts at s_start); the revoke-cancel machinery (JBD2_FLAG_REVOKE_CANCEL) is therefore unnecessary in full.
- Benefit: the per-op synchronous journal commit (descriptor + copies + revoke + commit + superblock, 8–12 round trips) disappears, and delete-class operations batch like writes (p6_mkdrmdir 52–58 ms strong-median class → single-digit ms).
- The on-disk format is unchanged: journal image mount/replay = e2fsck, matching Linux's write-back mount; the checksum layer is verified bit-for-bit against mke2fs 1.47.2 output (crc32c at 0x3FC).
Crash-window consistency
- The map-before-free durability order (R108): punch frees are deferred until "the rebuilt mapping is published" — freeing against the stale on-disk map is the double-allocation poison window; crash ordering rides the bitmap/GD/SB deferred writes plus revoke records.
- e2fsck interop: inode creation stamps i_extra_isize = 32 (Linux's s_want_extra_isize); R109 maintains bg_itable_unused (refreshed from the group's inode bitmap; e2fsck validates the field); the first kernel-written image passed e2fsck -n with no problems.
fallocate
- PUNCH_HOLE full implementation (2026-11-16): writeback of unflushed buffered writes before the punch (LTP fallocate06 clear-check); "aligned interior + zeroed edges" — fully-covered blocks are freed, partially-covered edge blocks are zeroed in place; any depth via gather/classify/rebuild (indirect-block files covered); R108 deferred frees; an EFBIG guard fixing the EFBIG leak (~500 MB).
- tmpfs fallocate is a separate implementation that allocates and punches (shmem semantics); the fallocate epilogue keeps dirty delayed-allocation pages.
xattr / ACL / directory index
- security.* requires CAP_SYS_ADMIN (except security.capability, which takes CAP_SETFCAP — the commoncap rule); system.* (POSIX ACLs) is accepted for owner/CAP_FOWNER; security.selinux is never stored (labels are owned by the kernel).
- htree directories (EXT4_INDEX_FL) are readable; the write path refuses with EOPNOTSUPP — the capability boundary is exposed honestly rather than silently degraded.
§4bio / buffer cache
- BufferHead five states: BH_Uptodate/Dirty/Lock/Req/Mapped; hash-chained CacheEntry with LRU; documented lock order: bucket lock → LRU lock → per-buffer state lock. The 64→2048 bucket growth is on record.
- The 10-second device-stall discipline: WAIT_DEADLINE_JIFFIES = 10 s — past the deadline the buffers the device may still be DMAing into are leaked (never freed); leaking is preferred over post-write corruption.
- The write-planning closure: the fsync 1092 s incident (lb229: 252 identical 5 s TXN-HANG samples pinned one task inside WritePlan::push_entry for the whole window; the KV load crawled 550–1100 s vs the healthy ~40 s class) — fixed with a 3-round cap plus a conservative linear fallback; the index+worklist fixpoint closure was measured and reverted (it allocated from journal/eviction spinlock contexts).
- Async read batching: bread_async_multi (128 KiB requests); plugged span writeback: submit N requests without waiting, then wait once for the whole batch (the fsync flush wall, ~2048 serialized spans at 128 MB ≈ 6.2 s, becomes batched); MAX_WRITE_BATCH = 32 (32×64 KiB = 2 MiB private staging, DMA copy discipline, ordered by submission ordinal).
§5procfile!: declarative /proc formatters (D-4)
- One field-declaration table derives the renderer, the shape tests, and the byte snapshots — format and data can no longer drift; declaration forms are kv / pad (meminfo widths 16/8) / cols (the row function's argument list derives from the column list) / kvtab (/proc/[pid]/status, STATUS_FIELDS pinned against a live render) / kvtab_pad (/proc/cpuinfo).
- Converted files: vmstat (byte-identical), meminfo (column-exact), stat/schedstat (order unit-pinned), diskstats, status, cpuinfo. Dynamic-arity files (interrupts/intr/softirqs) stay explicit by design.
- Known costs: ~18 hand-written files remain; once, five byte-format defects survived review into a merged tree — shape and snapshot tests were institutionalized by that event.
§6The FileOps capability builder (D-6)
- One const builder method per slot; a duplicate install is a const panic = a compile error; the errno mapping for missing ops converges at the single point File::missing_op_errno (Read/Write → EINVAL, LSeek → ESPIPE, etc.).
- The incident it paid for: read() on a valid epoll fd returned EBADF because the read slot was NULL, and an OH event loop spun 155,991 iterations on the wrong errno — EBADF means "fd closed", while EINVAL steers the event loop into its correct error path.
- The migration is complete: every FileOps table in the tree is a capability declaration (including the last two drm tables); the first conversions were epoll/eventfd/timerfd/signalfd/pipe/inotify.
§7pipe / io_uring / inotify / epoll
- pipe: 64 KiB capacity (PIPE_BUF_SIZE, raised from 16 KiB per review 5.2), PIPE_BUF = 4096 atomic writes (matching the Linux default); the capacity+1 slot-allocation defect is fixed (LTP pipe2_04: a full 65536-byte write once returned 65535).
- io_uring: the Linux 5.1+ ABI; SQ/CQ ring mmap (IORING_FEAT_SINGLE_MMAP); operations execute synchronously in the enter context; op set NOP/FSYNC/CLOSE/READ/WRITE/FADVISE.
- inotify: fully implemented — queued events, watch table, max_queued_events, fdinfo watches, init1/add_watch.
- epoll: the interest set is an intrusive EpollEntry list (sentinel-headed) — replacing a Vec<EpollEntry> that allocated on the armed path (and on growth); the wake-registry shard is likewise an intrusive EpollWakeNode list; zero allocation on the armed path. The rux:epoll_* events are a registered rux: family of our own (Linux has no epoll events).
§8Benchmark numbers
| Metric (2026-11-01 board, main@afc41b8b, KVM) | Before re-anchor | After |
|---|---|---|
| stat | 200.9 µs | 71.1 µs |
| openclose | 512.9 µs | 156.3 µs |
| read_cached | 546.8 µs | 203.7 µs |
| append | 657.2 µs | 77.4 µs |
| mkdir+rmdir | 22.8 ms | 2.76 ms |
| unlink | 1,141 µs | 808 µs |
| buffer cache hit rate | 99.1% (gate ≥ baseline; pa29: bread 2.81M / device reads 25k) | |
Honest gaps on record: p6_mkdrmdir remains ~14× from the same-test platform Linux's 153 µs — the gap is attributed to the shared syscall and path-lookup fixed costs, not the filesystem itself; the write_fsync 14.2 ms median is the current gate anchor (to be re-evaluated after span-writeback batching).
Code:
kernel/src/fs/ (dentry / mount / file / fdreap / page_cache / bio / ext4/* / jbd2/* / procfs/* / pipe / inotify) and kernel/src/io_uring/. Divergences: D-4/D-6/D-8/D-12/D-13. Instruments: the fsw counters (fsw=1), the rux:epoll_* / ext4:* / jbd2:* trace families (see tracepoints).