11. Files: VFS & FAT32

FlashOS presents one path namespace backed by two fixed mount slots. crates/kernel/src/fs/vfs.rs dispatches by path:

The /mnt/ prefix includes its trailing slash, so /mnt2/file stays on the root backend. There is no general mount syscall or longest-prefix mount tree.

Open files and descriptors

A descriptor is a small tagged task-table entry. An open file is a refcounted kernel object with backend identity, path/inode information, and an offset cursor. fork inherits references; close and task reaping drop them; the last reference frees the backing page.

Unified read, write, close, and dup2 dispatch across console, pipe, and file descriptor kinds.

Read-only initramfs

The deterministic newc archive is generated by xtask, embedded in the kernel image, parsed by crates/kernel/src/fs/initramfs.rs, and exposed through crates/kernel/src/fs/initramfs_backend.rs.

It contains PID 1, shell and utilities, account configuration, and test fixtures. Its order, metadata, and bytes are reproducible across equivalent builds.

Mutable FAT32

crates/kernel/src/drivers/platform/rpi4b/emmc2.rs provides polled single-block I/O to the BCM2711 Arasan controller. crates/kernel/src/fs/fat32.rs parses MBR, BPB, FAT, cluster chains, and directory entries. crates/kernel/src/fs/fat32_backend.rs connects that logic to the VFS.

The current mutable surface supports:

• regular-file open, read, write, and seek;
• create and unlink for files;
• same-directory rename;
• indexed directory reads.

Names are FAT 8.3 only. Long filenames, writable subdirectory management, and general truncation are not implemented.

Why QEMU skips the real card path

QEMU's Raspberry Pi model does not expose a usable EMMC2/SD route for this driver. FAT32 runtime scenarios therefore report explicit passing skips under QEMU. The real read/write, persistence, create, rename, and unlink acceptance runs on Pi hardware.

Host tests still cover pure FAT32 parsing and mutation logic through an in-memory backend seam. They do not claim to validate controller timing or physical media behavior.

Unix permissions on FAT

Because FAT32 lacks UID/GID/mode fields, PERMS.TAB supplies an overlay by basename. The kernel also hardens the password database: SHADOW cannot become more permissive than 0600 root:root even if the overlay is absent or invalid.

[!NOTE] The editor saves by unlinking, creating, and rewriting because the current write path does not truncate an existing file. That behavior is a known filesystem constraint, not a generic POSIX guarantee.

Next, we see how the pager and editor build full-screen behavior above this small file and console API.