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-anchorAfter
stat200.9 µs71.1 µs
openclose512.9 µs156.3 µs
read_cached546.8 µs203.7 µs
append657.2 µs77.4 µs
mkdir+rmdir22.8 ms2.76 ms
unlink1,141 µs808 µs
buffer cache hit rate99.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).