# Introduction to ModuOS

## What is ModuOS?

**ModuOS** is a hobby operating system project designed for educational purposes and experimentation. It's a 64-bit operating system written primarily in C with x86-64 assembly for low-level operations.

## Project Goals

- **Learning**: Understand OS fundamentals through hands-on implementation
- **Experimentation**: Test OS design concepts and algorithms
- **Modularity**: Clean separation between kernel, drivers, and userland
- **Simplicity**: Keep code readable and well-documented

## Key Features

### Core Kernel
- **64-bit Long Mode**: Full x86-64 support with Multiboot2 boot protocol
- **Memory Management**: 
  - Physical memory allocator with bitmap tracking
  - Virtual memory with 4-level paging (PML4)
  - Kernel heap allocator (malloc/free)
- **Process Management**:
  - Preemptive multitasking
  - Round-robin scheduler with priority support
  - Context switching with full register preservation
  - ELF executable loading

### Hardware Support
- **Storage**: ATA/ATAPI (IDE), AHCI/SATA controllers
- **Graphics**: VGA text mode (80x25)
- **Input**: PS/2 keyboard and mouse
- **System**: PCI enumeration, ACPI power management, RTC

### File Systems
- **FAT32**: Full read support for MS-DOS compatible file systems
- **ISO9660**: CD-ROM file system (read-only)
- **VFS**: Virtual file system abstraction layer
  - `/...` paths resolve against the current mount slot
  - `$/dev/...` is DevFS
  - `$/mnt/vDriveN/...` exposes per-vDrive mount views

### Userland
- **System Calls**: Unix-like syscall interface
- **ELF Support**: Load and execute user programs
- **Standard Programs**: cat, echo, shell, memtest, zsfetch
- **Games**: Raycaster FPS, Snake, Stack Blocks, Ping Pong, Minesweeper

## System Requirements

### Development Environment
- **Docker Desktop**: For cross-compilation toolchain
- **QEMU**: For testing and emulation (x86_64)
- **1GB Disk Image**: FAT32 formatted virtual disk

### Target Hardware (Virtual)
- **CPU**: x86-64 compatible processor
- **RAM**: Minimum 256MB (recommended 1GB)
- **Storage**: IDE or AHCI controller
- **BIOS**: Multiboot2 compatible bootloader (GRUB2)

## Design Philosophy

### Monolithic Kernel
ModuOS uses a monolithic kernel architecture where drivers and core services run in kernel space. This simplifies development and provides direct hardware access.

### Modular Components
Despite being monolithic, the code is organized into clear subsystems:
- **arch/**: Architecture-specific code (AMD64)
- **kernel/**: Core kernel services
- **drivers/**: Hardware drivers
- **fs/**: File system implementations
- **userland/**: User-space programs

### Educational Focus
The code prioritizes clarity and documentation over performance. This makes it ideal for learning but not suitable for production use.

## What ModuOS is NOT

- **Not production-ready**: This is a hobby/learning project
- **Not POSIX compliant**: Uses custom syscall interface
- **Not multi-user**: Single-user environment
- **Not network-capable**: No networking support yet

## Technology Stack

- **Language**: C (C99/C11) and x86-64 NASM assembly
- **Bootloader**: GRUB2 (Multiboot2 protocol)
- **Compiler**: GCC cross-compiler (x86_64-elf-gcc)
- **Build System**: GNU Make
- **Emulator**: QEMU (qemu-system-x86_64)
- **Container**: Docker (for reproducible builds)

## Project History

ModuOS is developed by **New Technologies Software** as an educational project to explore operating system internals, x86-64 architecture, and low-level system programming.

## Next Steps

- [Quick Start Guide](Quick-Start-Guide.md) - Get ModuOS running
- [System Architecture](System-Architecture.md) - Understand the design
- [Building ModuOS](Building-ModuOS.md) - Build from source