Skip to content

File Systems

Jump to bottom
NtinosTheGamer2324 edited this page Feb 11, 2026 · 4 revisions

File Systems

Paths and namespaces

ModuOS uses the following path namespaces:

  • /... – real filesystem paths on the currently selected mount (boot drive by default)
  • $/mnt/vDriveN/... – explicit mount views (e.g. $/mnt/vDrive0/, $/mnt/vDrive1/)
  • $/dev/... – DevFS device nodes (e.g. $/dev/input/kbd0, $/dev/graphics/video0)

Examples:

# dir /
# dir $/mnt/vDrive0/
# dir $/dev

ModuOS supports multiple file systems through a unified Virtual File System (VFS) layer.

MDFS (ModularFS)

ModuOS also includes a native filesystem called MDFS (ModularFS).

  • Read/write filesystem designed for ModuOS
  • EXT2-inspired metadata (inodes + bitmaps + inode table)
  • exFAT-inspired directories (entry sets + checksums)

See: MDFS Documentation for comprehensive documentation:

ModuOS uses two path namespaces:

  • Real filesystem paths: /... (resolved against the process' current mount slot; boot drive is selected by default)
  • Virtual namespace router: $/...
    • $/dev/... maps to DevFS devices
    • $/mnt/... exposes mount/slot views (implementation-defined)

Overview

┌────────────────────────────────────────────────────┐
│         Application Layer                          │
│    fs_read_file() / fs_list_directory()           │
└────────────────┬───────────────────────────────────┘
                 │
┌────────────────▼───────────────────────────────────┐
│         Virtual File System (VFS)                  │
|    - Mount slots (vDrive-backed)                  |
│    - Unified file operations                       │
│    - Path resolution                               │
└────┬──────────────────────┬────────────────────────┘
     │                      │
┌────▼──────┐        ┌──────▼─────┐
│   FAT32   │        │  ISO9660   │
│  Driver   │        │   Driver   │
└────┬──────┘        └──────┬─────┘
     │                      │
     └──────────┬───────────┘
                │
┌───────────────▼────────────────────────────────────┐
│         Storage Layer                              │
│    ATA/ATAPI  |  AHCI/SATA  |  vDrive             │
└────────────────────────────────────────────────────┘

Virtual File System (VFS)

File: src/fs/fs.c

Mount Table

Historically some docs referred to DOS-like drive letters. These do not exist in current ModuOS userland paths. In the current implementation, the kernel VFS stores mounts in slots (0..N), and each process has a current_slot used to resolve normal /... paths.

Drive-letter style UIs may still exist in tools, but userland syscalls typically operate on /... (current slot) and $/... (virtual router).

typedef struct {
    fs_type_t type;           // Filesystem type
    int handle;               // FS-specific handle
    int valid;                // Is this mount valid?
} fs_mount_t;

static fs_mount_t mount_table[FS_MAX_MOUNTS];  // mount slots

Filesystem Types

typedef enum {
    FS_TYPE_UNKNOWN = 0,
    FS_TYPE_FAT32   = 1,
    FS_TYPE_ISO9660 = 2
} fs_type_t;

FAT32 File System

Location: src/fs/DOS/FAT32/

Overview

FAT32 (File Allocation Table, 32-bit) is the MS-DOS/Windows file system used for compatibility.

Features:

  • Maximum file size: 4GB
  • Maximum partition size: 2TB
  • Long filename support (LFN)
  • Read/Write support

Data Structures

Boot Sector:

typedef struct {
    uint8_t  jmp[3];
    char     oem_name[8];
    uint16_t bytes_per_sector;
    uint8_t  sectors_per_cluster;
    uint16_t reserved_sectors;
    uint8_t  num_fats;
    uint16_t root_entries;        // 0 for FAT32
    uint16_t total_sectors_16;    // 0 for FAT32
    uint8_t  media_type;
    uint16_t sectors_per_fat_16;  // 0 for FAT32
    // ... FAT32 specific fields
    uint32_t sectors_per_fat_32;
    uint32_t root_cluster;
    // ...
} __attribute__((packed)) fat32_boot_sector_t;

Directory Entry

typedef struct {
    char     name[11];           // 8.3 format
    uint8_t  attributes;
    uint8_t  reserved;
    uint8_t  creation_time_ms;
    uint16_t creation_time;
    uint16_t creation_date;
    uint16_t access_date;
    uint16_t cluster_high;       // High 16 bits
    uint16_t modified_time;
    uint16_t modified_date;
    uint16_t cluster_low;        // Low 16 bits
    uint32_t file_size;
} __attribute__((packed)) fat32_dir_entry_t;

File Operations

int fat32_read_file(int handle, const char *path, void *buffer, 
                    size_t buffer_size, size_t *bytes_read);
int fat32_list_directory(int handle, const char *path);
int fat32_stat(int handle, const char *path, fs_file_info_t *info);

ISO9660 File System

Location: src/fs/ISOFS/

Overview

ISO9660 is the standard file system for CD-ROMs and DVD-ROMs.

Features:

  • Read-only
  • Rock Ridge extensions support (Unix permissions)
  • Joliet extensions (Unicode filenames)
  • Maximum file size: 4GB

Primary Volume Descriptor

typedef struct {
    uint8_t  type;               // 1 = Primary Volume
    char     identifier[5];      // "CD001"
    uint8_t  version;
    // ... volume info
    uint32_t volume_space_size;  // Total sectors
    uint32_t root_directory_extent;
    uint32_t root_directory_size;
    // ...
} __attribute__((packed)) iso9660_pvd_t;

Directory Record

typedef struct {
    uint8_t  length;
    uint8_t  extended_length;
    uint32_t extent_lba;         // Data location
    uint32_t extent_lba_msb;
    uint32_t data_length;
    uint32_t data_length_msb;
    uint8_t  recording_date[7];
    uint8_t  file_flags;
    uint8_t  file_unit_size;
    uint8_t  interleave_gap;
    uint16_t volume_sequence;
    uint16_t volume_sequence_msb;
    uint8_t  name_length;
    char     name[0];            // Variable length
} __attribute__((packed)) iso9660_dir_record_t;

VFS API

File: include/moduos/fs/fs.h

Mount Operations

// Initialize VFS
void fs_init(void);

// Mount a drive to a slot (implementation-defined slot index)
int fs_mount_drive(int drive_index, uint32_t partition_lba, fs_type_t type);

// Unmount slot
int fs_unmount_slot(int slot);

// Get mount handle
fs_mount_t* fs_get_mount(int slot);

// List all mounts
void fs_list_mounts(void);

Example:

// Mount examples (slots are implementation-defined)
fs_mount_drive(0, 0, FS_TYPE_FAT32);
fs_mount_drive(1, 0, FS_TYPE_ISO9660);

// User-facing paths are typically:
// - /... (current slot)
// - $/mnt/vDriveN/... (explicit mount view)

File Operations

// Read entire file
int fs_read_file(fs_mount_t* mount, const char* path, 
                 void* buffer, size_t buffer_size, size_t* bytes_read);

// Get file info
int fs_stat(fs_mount_t* mount, const char* path, fs_file_info_t* info);

// Check if file exists
int fs_file_exists(fs_mount_t* mount, const char* path);

Directory Operations

// List directory
int fs_list_directory(fs_mount_t* mount, const char* path);

// Check if directory exists
int fs_directory_exists(fs_mount_t* mount, const char* path);

File Descriptors

File: src/fs/fd.c

File Descriptor Table

Each process has up to 16 open files:

typedef struct {
    int used;                    // 1 if in use
    fs_mount_t *mount;          // Mounted filesystem
    char path[260];             // File path
    uint32_t position;          // Current read/write position
    uint32_t size;              // File size
    int flags;                  // Open flags (read/write)
} file_descriptor_t;

Operations

// Open file
int fd_open(const char *path, int flags);

// Close file
int fd_close(int fd);

// Read from file
int fd_read(int fd, void *buffer, size_t count);

// Write to file (if supported)
int fd_write(int fd, const void *buffer, size_t count);

// Seek position
int fd_seek(int fd, uint32_t offset, int whence);

Path Resolution

Path Format

Real filesystem absolute path: /ModuOS/System64/mdsys.sqr

  • Resolved against the current mount slot (boot drive by default)
  • Path separator: /

Virtual namespace path: $/dev/input/kbd0

  • Routed to DevFS

Relative path: Not fully supported yet

Path Parsing

// Parse real filesystem path "\/dir/file.txt" (resolved against current slot)
fs_mount_t *mount = fs_get_mount(current_slot);
const char *file_path = path; // "/dir/file.txt"

// Virtual namespace paths "$/..." are handled by a separate router layer.

Next Steps

Clone this wiki locally