MeniOS

Current release: 0.0.4

Mastodon

A hobby operating system kernel written in C and Assembly, targeting x86-64 architecture. The ultimate goal is to run Doom in userland! 🎯

If you are tracking the steps toward a usable shell, see Road to Shell Readiness for the current checklist.

Current Status

MeniOS has made significant progress with core kernel functionality now solidly implemented. The system boots with Limine bootloader and provides:

✅ Completed Core Infrastructure

• ✅ Memory Management: Physical memory mapping, virtual memory allocation, and kernel heap management (Issues #35, #57)
• ✅ Process Scheduling: Preemptive userland scheduler with kernel threads and time slicing (Issue #34)
• ✅ Synchronization: Blocking mutexes, condition variables, semaphores, and read-write locks with scheduler integration (Issues #36, #37, #39, #40)
• Console System: ANSI escape sequence support with scrolling and color output
• Input/Output: PS/2 keyboard driver with buffered input
• Debugging: Page fault and GPF handlers for system diagnostics
• Testing: Unit test framework using Unity for kernel components
• Privilege Setup: Ring 3 GDT selectors, 64-bit TSS, and user-mode entry trampoline
• Syscalls: INT 0x80 dispatcher with initial write(1, …) and exit(status) support
• User Demo: Kernel launches Ring 3 thread with ELF loader exercising full syscall path
• Memory Protection: Kernel/user separation with per-process page tables

🚧 Next Major Milestones

With the strong foundation now in place, the next high-priority developments are:

1. File Descriptor Management (Issue #96) - Foundation for all I/O operations
2. Memory Mapping Syscalls (Issue #89) - mmap/munmap for userspace allocators
3. Fork/Exec Process Creation (Issue #93) - Full process lifecycle management
4. Threading Support (Issues #108-#113) - Complete multithreading infrastructure
5. Advanced IPC (Issues #102-#107) - Pipes, signals, shared memory, and microkernel IPC

🆕 Threading Support Added

A complete threading roadmap has been designed with 6 new issues:

• #108: Kernel threading infrastructure
• #109: pthread API and POSIX threading support
• #110: Thread-safe C library (libc)
• #111: Advanced pthread synchronization primitives
• #112: Thread debugging and profiling support
• #113: Thread-aware system calls and kernel integration

Quick Start

Prerequisites

Linux:

• gcc
• ld
• make
• qemu

MacOS:

• Docker
• make
• qemu

Building and Running

make build run

This will build the kernel, create a bootable image, and launch it in QEMU. All generated artifacts now live under build/ (build/bin for boot assets, build/obj for intermediates), keeping the repository tree clean. When the kernel reaches halt() the QEMU instance exits automatically via the debug-exit device, so make run returns to your shell without manual intervention. The default QEMU_OPTS wire an AHCI controller (-device ahci) with the disk attached to ahci.0, ensuring the kernel exercises its SATA/AHCI path during every run.

Verify the User Demo

During boot, meniOS schedules the embedded user_demo ELF immediately after hardware probing. The program now:

• forces the stack to grow across an 8 KiB boundary (exercising lazy stack paging),
• emits three write(1, …) syscalls with status messages, and
• exits with status 42 via SYS_exit.

Expect the log to show the [user_demo] messages on screen and in com1.log, confirming that the INT 0x80 path, lazy stack allocation, and non-zero exit codes work. If you need quieter serial output, toggle the verbose syscall traces in src/kernel/syscall/syscall.c (search for serial_printf inside syscall_write_handler).

Development Progress

✅ Major Milestones Completed

• Foundation Complete: Memory management, scheduling, and synchronization (Issues #34, #35, #36, #40, #57)
• Integration with Limine bootloader v10
• Physical memory mapping and management with virtual memory allocation
• Kernel malloc implementation with heap management
• Preemptive scheduler with kernel threads and time slicing
• Mutex implementation with blocking and scheduler integration
• Condition variables for advanced synchronization
• ANSI console with scrolling and color support
• Complete vsprintk function with all format specifiers
• PS/2 keyboard driver with proper input handling
• Virtual-to-physical address translation (page table walking)
• Ring 3 user mode infrastructure with syscall interface
• ELF loader for user programs
• Per-process virtual memory with kernel/user separation
• Kernel block device abstraction layer (Issue #114)
• SATA/AHCI DMA block driver with interrupt completion (Issue #62)
• DMA-friendly allocation helpers (Issue #115)
• Global block cache for block devices (Issue #63)
• Kernel VFS layer backed by FAT32 filesystem (Issue #65)
• GPT-aware FAT32 filesystem mounting and file access (Issue #64)
• Filesystem syscalls (open/read/write/lseek/close) (Issue #60)

🔥 Ready to Implement (Dependencies Met)

• File descriptor management and pipes (Issue #96)
• Stdin routed through descriptor table for interactive user input
• Memory mapping syscalls (mmap/munmap) (Issue #89) - Enabled by completed VM work
• Kernel threading infrastructure (Issue #108)
• Fork/exec process creation (Issue #93) - Enabled by VM and file descriptor work

🚧 In Progress & Planned

• Threading Support: Complete pthread API and multithreading (Issues #108-#113)
• Advanced IPC: Signals, shared memory, microkernel IPC (Issues #102-#107)
• Filesystem: Block cache and write support (Issues #60, #63)
• Networking: Complete TCP/IP stack (Issues #67-#73)
• Graphics: Framebuffer interface and input subsystem (Issues #31-#33)

Road to Doom 🎮

Foundation ✅ COMPLETE: The core kernel infrastructure needed for userspace applications is now solid!

Remaining major components for Doom:

• File System: VFS layer, write support, file I/O syscalls
• Graphics: Framebuffer interface, double buffering, palette control
• Input: Userspace keyboard/mouse drivers and event system
• Audio: PCM output, mixing, streaming syscalls
• Toolchain: Cross-compiler, libc subset, build system

See road_to_doom.md for the complete roadmap and tasks.json for detailed task tracking.

📊 Progress Assessment: With 5 major foundation issues completed and 64 remaining issues, meniOS is now positioned for rapid feature development. The completed memory management and synchronization work enables parallel development of process management, threading, and I/O systems.

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    USERLAND (In Development)                │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────────────┐ │
│  │  Doom   │  │ Shell   │  │ Games   │  │  Applications   │ │
│  └─────────┘  └─────────┘  └─────────┘  └─────────────────┘ │
│                              │                             │
│                        ┌─────────┐                        │
│                        │  libc   │  (Threading Support)   │
│                        └─────────┘                        │
└─────────────────────────────┬───────────────────────────────┘
                              │ Syscall Interface ✅
┌─────────────────────────────┴───────────────────────────────┐
│                      KERNEL SPACE ✅                       │
│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │
│  │ Process Mgmt ✅ │  │ Memory Mgmt ✅  │  │ I/O Subsys   │ │
│  │ • Scheduler ✅  │  │ • Virtual Mem ✅│  │ • Console ✅ │ │
│  │ • Kernel Threads│  │ • Physical Mem ✅│  │ • PS/2 Input │ │
│  │ • Sync Prims ✅ │  │ • Page Tables ✅│  │ • Framebuffer│ │
│  └─────────────────┘  └─────────────────┘  └──────────────┘ │
│                              │                             │
│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │
│  │ Debug/Diag      │  │ File System     │  │ Hardware     │ │
│  │ • Page Faults ✅│  │ • VFS (Planned) │  │ • Interrupts │ │
│  │ • GPF Handler ✅│  │ • Block Drivers │  │ • Timers     │ │
│  │ • Unit Tests ✅ │  │ • File I/O      │  │ • Hardware   │ │
│  └─────────────────┘  └─────────────────┘  └──────────────┘ │
│                                                             │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │            🆕 Threading Support (Planned)               │ │
│  │  • Kernel threading infrastructure (#108)              │ │
│  │  • pthread API (#109) • Thread-safe libc (#110)       │ │
│  │  • Advanced synchronization (#111) • Debugging (#112) │ │
│  └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────┬───────────────────────────────┘
                              │ Hardware Abstraction
┌─────────────────────────────┴───────────────────────────────┐
│                         HARDWARE                           │
│    CPU    │    RAM    │   Storage   │  Graphics  │  Input   │
│   x86-64  │   4GB+    │    Disk     │    VGA     │   PS/2   │
└─────────────────────────────────────────────────────────────┘

Known Issues and Limitations

Current Limitations

• Filesystem: Read-only FAT32 and tmpfs support exist; write support and broader FS coverage are still TODO (Issues #60, #62-#65).
• Limited hardware support: Only basic PS/2 keyboard, VGA framebuffer
• No network stack: No networking capabilities (Issues #67-#73)
• Graphics: Basic framebuffer, no hardware acceleration
• Audio: No audio subsystem implemented yet

Active Development Areas

• Threading: Complete multithreading support in development (Issues #108-#113)
• IPC: Advanced inter-process communication planned (Issues #102-#107)
• File I/O: File descriptor management and filesystem support (Issues #96, #60, #62-#65)
• Process Management: Fork/exec and full process lifecycle (Issue #93)

Testing Environment

• QEMU only: Primary testing on QEMU emulator, real hardware testing limited
• x86-64 focus: No support for other architectures planned currently
• Development tools: Requires cross-compilation toolchain for full development

Project Structure

• src/ - Kernel source code (C and Assembly)
• include/ - Header files
• tests/ - Unit tests using Unity framework
• build/ - Build artifacts and bootloader assets
• docs/ - Architecture documentation and design decisions
• tasks.json - Detailed task tracking with GitHub issue integration
• road_to_doom.md - Comprehensive roadmap for userland Doom support
• issue_dependencies.dot/.png - Visual dependency chart of all issues
• ISSUE_DEPENDENCY_ANALYSIS.md - Detailed dependency analysis and implementation strategy

Contributing

We welcome contributions from developers of all skill levels! 🚀

• New Contributors: Start with our Contributing Guide for a complete development workflow
• Find Tasks: Check GitHub Issues or browse tasks.json for detailed task tracking
• High Priority: Issues #89, #96, #108 are ready to implement with no blocking dependencies
• Report Issues: Use our issue templates to report bugs or request features
• Security Issues: Please review our Security Policy for responsible disclosure
• Code Style: Follow the guidelines in CODING.md
• Community: Read our Code of Conduct

Whether you're interested in kernel development, want to learn about operating systems, or just want to help us reach the goal of running Doom in userland, there's a place for you in the meniOS community!

License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright (c) 2020-2025 Plínio Balduino

References

• Intel® 64 and IA-32 Architectures Software Developer's Manual Combined Volumes: 1, 2A, 2B, 2C, 2D, 3A, 3B, 3C, 3D, and 4: https://www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html
• PIC: https://pdos.csail.mit.edu/6.828/2014/readings/hardware/8259A.pdf http://www.brokenthorn.com/Resources/OSDevPic.html
• APIC: http://web.archive.org/web/20070112195752/http://developer.intel.com/design/pentium/datashts/24201606.pdf
• ATA: http://learnitonweb.com/2020/05/22/12-developing-an-operating-system-tutorial-episode-6-ata-pio-driver-osdev/ http://www.t13.org/Documents/UploadedDocuments/docs2016/di529r14-ATAATAPI_Command_Set_-_4.pdf p.74
• ASM: https://bitismyth.wordpress.com/assembly-bunker/
• Mem: https://arjunsreedharan.org/post/148675821737/memory-allocators-101-write-a-simple-memory
• AMD: https://developer.amd.com/resources/developer-guides-manuals/ https://www.amd.com/system/files/TechDocs/48751_16h_bkdg.pdf
• Limine Protocol: https://codeberg.org/Limine/limine-protocol/src/branch/trunk/PROTOCOL.md