Project Structure

Project Structure

Overview of the ModuOS source code organization.

Directory Layout

ModuOS/
├── buildenv/              # Docker build environment
│   └── Dockerfile
├── include/               # Header files
│   └── moduos/
│       ├── arch/          # Architecture-specific headers
│       ├── drivers/       # Driver headers
│       ├── fs/            # Filesystem headers
│       └── kernel/        # Kernel headers
├── src/                   # Source code
│   ├── arch/              # Architecture-specific code
│   ├── drivers/           # Hardware drivers
│   ├── fs/                # Filesystem implementations
│   └── kernel/            # Core kernel
├── targets/               # Build targets
│   └── AMD64/
│       ├── iso/           # ISO filesystem layout
│       └── linker.ld      # Linker script
├── userland/              # User-space programs
├── LICENSES/              # Third-party licenses
├── Makefile               # Build system
├── run.bat                # Build and run script
└── readme.md              # Project README

Source Organization

Architecture Layer (src/arch/AMD64/)

arch/AMD64/
├── boot/                  # Boot code
│   ├── header.asm         # Multiboot2 header
│   ├── main.asm           # 32-bit bootstrap
│   └── main64.asm         # 64-bit entry
├── interrupts/            # Interrupt handling
│   ├── fault.asm          # CPU exception handlers
│   ├── idt.c              # IDT setup
│   ├── irq.c              # Hardware interrupts
│   ├── isr.asm            # Interrupt service routines
│   ├── pic.c              # PIC driver
│   └── timer.c            # PIT timer
└── syscall/               # System call handling
    ├── context_switch.asm # Process switching
    └── syscall_entry.asm  # Syscall entry point

Kernel Core (src/kernel/)

kernel/
├── kernel.c               # Main kernel entry
├── panic.c                # Kernel panic handler
├── exec.c                 # Program execution
├── fault.c                # Fault handling
├── md64api.c              # System API
├── memory/                # Memory management
│   ├── kheap.c            # Kernel heap
│   ├── memory.c           # Memory initialization
│   ├── multiboot2.c       # Multiboot2 parsing
│   ├── paging.c           # Virtual memory
│   ├── phys.c             # Physical allocator
│   └── string.c           # String operations
├── process/               # Process management
│   └── process.c          # Scheduler and processes
├── syscall/               # System calls
│   └── syscall.c          # Syscall dispatcher
├── shell/                 # Built-in shell
│   ├── zenith4.c          # Main shell
│   ├── helpers.c          # Shell utilities
│   ├── art.c              # ASCII art
│   └── legacy/
│       └── MSDOS.c        # Legacy DOS commands
├── applications/          # Built-in apps
│   └── rl-clock.c         # Real-time clock app
├── games/                 # Built-in games
│   ├── game_menu.c        # Game selector
│   ├── eatfruit.c         # Snake game
│   ├── mine_sweep.c       # Minesweeper
│   ├── RaycasterFPS.c     # FPS game
│   ├── stackblocks.c      # Puzzle game
│   └── verticalpingpong.c # Pong game
├── COM/                   # Serial port
│   └── com.c              # COM driver
├── events/                # Event system
│   └── events.c           # Event handling
├── io/                    # I/O operations
│   └── io.c               # Port I/O
└── loader/                # Program loader
    └── elf.c              # ELF loader

Drivers (src/drivers/)

drivers/
├── Drive/                 # Storage drivers
│   ├── vDrive.c           # Virtual drive layer
│   ├── ATA/
│   │   ├── ata.c          # ATA/IDE driver
│   │   └── atapi.c        # ATAPI (CD-ROM)
│   └── SATA/
│       ├── AHCI.c         # AHCI controller
│       └── SATA.c         # SATA driver
├── graphics/              # Built-in graphics drivers
│   ├── VGA.c              # VGA text mode
│   └── fb_console.c       # Framebuffer console (text on pixel framebuffer)

modules/
├── QXL/                    # QXL SQRM GPU driver
├── VMSVGA/                 # VMware SVGA SQRM GPU driver
└── md_vga_compatible_display_sqrm.c  # VGA-compatible SQRM GPU driver (fallback)
├── input/                 # Input drivers
│   ├── input.c            # Input abstraction
│   └── ps2/
│       └── ps2.c          # PS/2 keyboard/mouse
├── PCI/                   # PCI subsystem
│   └── pci.c              # PCI enumeration
├── power/                 # Power management
│   └── ACPI.c             # ACPI driver
├── Time/                  # Time/clock
│   └── RTC.c              # Real-time clock
└── USB/                   # USB subsystem
    ├── usb.c              # USB core
    ├── Classes/
    │   ├── hid.c          # HID devices
    │   └── hub.c          # USB hubs
    └── Controllers/
        ├── uhci.c         # UHCI controller
        ├── ohci.c         # OHCI controller
        └── ehci.c         # EHCI controller

File Systems (src/fs/)

fs/
├── fs.c                   # VFS layer
├── fd.c                   # File descriptors
├── hvfs.c                 # High-level VFS
├── DOS/
│   └── FAT32/
│       └── fat32.c        # FAT32 implementation
└── ISOFS/
    └── iso9660.c          # ISO9660 (CD-ROM)

Header Organization

Headers follow the same structure as source files:

include/moduos/
├── arch/AMD64/interrupts/
├── drivers/
│   ├── Drive/
│   ├── graphics/
│   ├── input/
│   ├── PCI/
│   ├── power/
│   ├── Time/
│   └── USB/
├── fs/
└── kernel/
    ├── memory/
    ├── process/
    ├── shell/
    └── syscall/

Naming Conventions

Files

• C files: lowercase with underscores (memory.c, fat32.c)
• Assembly: lowercase with underscores (main.asm, isr.asm)
• Headers: lowercase matching C file (memory.h)

Functions

• Public API: subsystem_operation() format
  • Example: process_create(), fs_mount_drive()
• Private/Static: _internal_function() or static
• Assembly: asm_function_name

Types

• Structs: name_t suffix
  • Example: process_t, fs_mount_t
• Enums: name_t suffix
  • Example: process_state_t, fs_type_t

Constants

• Macros: UPPER_CASE_SNAKE
  • Example: MAX_PROCESSES, PAGE_SIZE

Build Targets

ISO Layout

targets/AMD64/iso/
├── boot/grub/
│   ├── grub.cfg           # GRUB configuration
│   └── *.pf2              # Fonts
├── Apps/                  # User programs
│   ├── cat.sqr
│   ├── echo.sqr
│   └── sh.sqr
├── ModuOS/
│   ├── System64/
│   │   ├── mdsys.sqr      # Kernel binary
│   │   └── pcname.txt     # PC name
│   ├── bin/               # Future system binaries
│   ├── Modules/           # Future kernel modules
│   └── usr/               # User directories
└── Users/                 # User home directories

Code Dependencies

Dependency Graph

Applications/Games
        ↓
    Syscalls
        ↓
   Kernel Core
        ↓
  Memory Manager ←→ Process Manager
        ↓                 ↓
   File Systems      Scheduler
        ↓                 ↓
     Drivers        Context Switch
        ↓                 ↓
    Hardware         Interrupts

Next Steps

• Coding Standards - Style guide
• Building ModuOS - Build process
• System Architecture - Design overview