Phase 08

Storage And VFS

Expose files through userspace services so programs can read named resources instead of relying on embedded data or ad hoc kernel hooks.

Complete

Learning goal

Understand how a microkernel can provide filesystem access through servers.

Why this phase matters

Expose files through userspace services so programs can read named resources instead of relying on embedded data or ad hoc kernel hooks.

How it works in m3OS

Phase 8 adds the first file-access layer to m³OS. The additions are:

Why route file access through IPC?

The same policy/mechanism argument from Phase 7 applies here. The kernel should own only the mechanism — endpoint delivery, scheduling, memory protection. Policy questions (which process can read which path, how to handle missing files, what backends exist) belong in userspace servers. Routing through vfs_server instead of letting clients call fat_server directly also creates the ownership boundary needed for Phase 9+: adding a second backend (tmpfs, network share) only requires changing vfs_server’s routing table, not every client.

How it builds on earlier phases

This phase builds on Core Servers and turns that foundation into Storage And VFS.

Implementation outline

Define a small file-oriented IPC protocol.
Build vfs_server as a router instead of a full filesystem implementation.
Add one filesystem backend with a narrow scope.
Place a few test files in the boot media and verify they can be read.
Keep caching and mutation out of the first milestone.

Task progress snapshot

14 of 14 tracked tasks are complete.

Documentation targets

Documentation deliverables have not been listed yet.

Deferred follow-on work

Writable filesystems
Page cache and buffering
Permissions and access control

Source materials

Important code

Code spotlight cards

Define a file-oriented IPC contract for open and read. Why it matters: A stable IPC contract decouples file consumers from filesystem implementation details. Focus on `kernel/src/fs/protocol.rs` while you trace the snippet.

View on GitHub

Implement vfs_server as a path router. Why it matters: The VFS layer routes path requests to the correct backend, keeping filesystem-specific logic isolated. Focus on `kernel/src/fs/vfs.rs` while you trace the snippet.

View on GitHub

Implement a read-only filesystem backend. Why it matters: A real filesystem backend lets the OS read files from the boot media rather than only embedded data. Focus on `Fat32Volume` and `mount_fat32` in `kernel/src/fs/fat32.rs` while you trace the snippet.

/// A mounted FAT32 volume backed by virtio-blk sectors.
pub struct Fat32Volume {
    pub bpb: Fat32Bpb,
    /// Absolute LBA of the partition start on the block device.
    base_lba: u64,
    /// Absolute LBA of the first FAT sector.
    fat_start_lba: u64,
    /// Absolute LBA of the first data cluster (cluster 2).
    data_start_lba: u64,
    /// Hint for next free cluster search.
    alloc_hint: u32,
}

/// Global mounted FAT32 volume (set by mount_fat32).

View on GitHub

Key files

kernel/src/fs/protocol.rs — Phase 8 defines three label numbers in kernel/src/fs/protocol.rs. All use the existing
kernel/initrd/hello.txt — The paths kernel/initrd/hello.txt and kernel/initrd/readme.txt must exist in the repository
kernel/initrd/readme.txt — The paths kernel/initrd/hello.txt and kernel/initrd/readme.txt must exist in the repository

How real OSes differ

Mature operating systems add caching, writeback, permissions, journaling, block-layer abstractions, and many filesystem drivers.
A toy OS starts with read-only access because it teaches layering and naming without dragging in crash consistency problems.
Production VFS layers (Linux, BSD) support dozens of filesystem types, mount namespaces, and complex permission models.

Success criteria

A userspace program can open a file by path and read its contents.
The VFS and filesystem backend have clear ownership boundaries.
Failures such as missing files are reported predictably.
The disk-image content used for demos is documented.

Related phases

Keep exploring the roadmap

Core Servers

Use IPC to assemble the first useful userspace services and prove that the system can be structured as cooperating servers rather than one large kernel.

Framebuffer And Shell

Make the OS pleasant to interact with by adding on-screen text output and a very small shell for manual exploration.