# 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](MDFS/) for comprehensive documentation: - [MDFS Overview](MDFS/Overview.md) - Architecture and design - [ACL Permissions](MDFS/ACL-Permissions.md) - NTFS-like access control - [How to Replicate](MDFS/How-To-Replicate.md) - Porting guide 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). ```c 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 ```c 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**: ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c // 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**: ```c // 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 ```c // 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 ```c // 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**: ```c 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 ```c // 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 ```c // 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 - [Storage Drivers](Storage-Drivers.md) - Hardware access - [Syscall Reference](Syscall-Reference.md) - File I/O syscalls - [Shell Commands](Shell-Commands.md) - File operations