ahrightos-fs

ahrightos-fs contains portable filesystem components for AhRightOS: file traits, inode metadata, descriptor tables, RamFS, BlkFS, VFS path resolution, block-device abstractions, LRU block cache behavior, and pipe IPC endpoints.

The crate is no_std outside tests. Host tests validate the public contracts before the QEMU-backed kernel system tests run.

BlkFS mount contract

FileSystemManager::mount_blkfs(path, dev) remains the compatibility API: it opens an existing AhRightOS BlkFS superblock or formats a blank teaching device. It now refuses obvious unsupported on-disk formats instead of overwriting them. New code can call mount_blkfs_with_options with BlkFsMountOptions:

• OpenOrCreate — old behavior; safe for classroom dummy devices.
• OpenOnly — mount only if the device already contains BlkFS; useful for QEMU virtio disk images where accidental formatting must be avoided.
• Format — explicitly reformat as AhRightOS-native BlkFS.

Kernel sys_mount adds one more safety rule above this crate-level API: if the selected backend is a real VirtIO block device, non-explicit modes are treated as OpenOnly. In other words, a blank virtio-blk image is not auto-formatted by /mnt or mode=open-or-create; use mode=format / format=always only when the class exercise intentionally initializes an AhRightOS BlkFS image. Dummy teaching devices keep the compatibility open-or-create behavior.

The crate does not implement ext4/FAT/GPT mounting. A "real disk" in this contract means a block device presented to AhRightOS (for example a QEMU virtio-blk raw image) that contains the AhRightOS BlkFS layout.

detect_disk_format performs non-mutating signature checks for:

• valid or invalid AhRightOS BlkFS superblocks,
• blank block devices,
• MBR/GPT partition-table signatures,
• FAT and ext-family signatures,
• unknown non-empty devices.

Blank detection is intentionally bounded. If a large device has an all-zero prefix beyond the classroom scan limit, it is classified as Unknown rather than scanning the whole image or implicitly formatting it; use explicit Format only when overwriting is intended.

flowchart LR
    Kernel[ahrightos-kernel] --> FS[ahrightos-fs]
    FS --> File[File trait]
    FS --> Inode[Inode metadata]
    FS --> FD[FileDescriptorTable]
    FS --> RamFS[RamFS]
    FS --> BlkFS[BlkFS]
    FS --> VFS[VFS path operations]
    FS --> Block[BlockDevice]
    FS --> Cache[BlockCache]
    FS --> Pipe[Pipe IPC]