FUSE-based SysV Filesystem

Project Overview

Atheon is a teaching filesystem that demonstrates how a handcrafted block layout can backstop FUSE's low-level API. A CLI bootstrapper accepts a mountpoint and optional backing store before composing the disk layer, buffer cache, inode manager, data block manager, and file manager. With debug builds it runs entirely in-memory for safe experimentation; release builds target a 40 GB device with 4 KiB blocks so students can inspect allocation internals without reformatting real disks.

Core Layout & Metadata

• Global constants fix block size, direct pointer counts, and multi-level indirection, keeping the ROOT_INODE in parity with FUSE while enabling ~16 TiB theoretical file sizes.
• Mkfs writes a superblock to block 0, zeroes the inode list, threads a freelist across the remaining blocks, and seeds the root directory with permissive "."/".." entries.
• Each inode records POSIX metadata, timestamps, multi-tier block pointers, and an allocated guard so the file manager can distinguish live-but-unlinked files.
• Directory entries store inode numbers, file types, occupancy, and inline names up to 243 characters with constructor checks to maintain bounds safety.

Persistence Stack

• DiskLayer abstracts storage, opening an O_RDWR descriptor when debug is off or allocating an in-memory buffer otherwise, enforcing 4 KiB span I/O.
• A templated BufferCache tracks hash buckets plus an LRU-style free list; misses recycle the head entry, flush dirty blocks, and move the refreshed slot to the tail.
• DataBlockManager consumes freelist entries, zeroes new blocks, and reinserts freed blocks either into spare slots or by prepending the freelist head.

File Operations & FUSE Integration

• INodeManager maps inode IDs to (block, offset) pairs and allocates the first free slot by toggling the allocated guard and refreshing timestamps.
• _get_data_block_idx and its allocating sibling walk direct, single, double, and triple-indirect trees to grow files while updating st_blocks.
• Directory traversals reuse templated DirentOperations for lookup, unlink, rmdir, and slot allocation, keeping traversal logic generic and reusable.
• Low-level FUSE callbacks (lookup, create, mkdir, read, write, setattr, forget, destroy, rename, link) translate domain exceptions to errno values, honor append/truncate flags, and emit spdlog diagnostics for debugging.
• Forget/destroy flows decrement lookup counts, truncate orphaned inodes, and clear the buffer cache so the block device stays consistent across sessions.

Tooling, Testing & Lifecycle

• CMake targets C++20, links against FUSE 3, argparse, and spdlog, and produces both the runtime atheon binary and a googletest-based test_runner.
• tests/test_runner.cpp initialises the singleton stack against /dev/vdb, mirroring production startup before running buffer cache, mkfs, data block manager, and file manager suites.
• build.sh configures a Release build in one step, while CLI flags support --debug for in-memory testing and --load-from-disk to skip mkfs when reusing a device.

Notable Lessons

Rich instrumentation, disciplined freelist accounting, and templated directory operations make it easy to trace bugs, reason about refcounts, and extend the teaching stack toward production-grade behaviors.