Brew OS

Scope

Brew OS is a hobby operating system project designed for educational purposes to explore core OS concepts including kernel development, process management, memory management, and system-level programming. It's a work in progress.

Requirements

• *nix-based development environment (Linux/MacOS/MSYS2)
• GCC cross-compiler targeting i686
• GNU Binutils tageting i686
• GNU Make
• QEMU (for emulation and testing)

Build Instructions

Build the Project

make

Run in Emulator

make run

Clean Build Artifacts

make clean

Project Structure

brew-os/
├── kernel/           # Kernel code
|   ├── arch/         # Architecture specific code
|   ├── boot/         # Bootloader code
|   ├── drivers/      # Hardware driver code
|   ├── fs/           # Filesystem(s) code
|   ├── include/      # Header files
|   ├── kernel/       # Kernel entry point and misc code
|   ├── lib/          # Freestanding C library code
|   ├── mm/           # (non-arch specific) memory management code
|   └── linker.ld     # Linker script
├── AGENTS.md         # Directives for AI agents
├── Makefile          # Build configuration
└── README.md         # This file

TODOs

• Improve memory management:
  • Add paging-aware allocator hooks (slab/buddy) so drivers and filesystems can request page-aligned buffers
  • Extend memory_bytes_* stats with fragmentation metrics
  • Implement virtual memory and memory protection systems: per-process page tables, copy-on-write primitives, and guard pages around the kernel heap to catch overflows early.
• Process management and scheduling:
  • Implement a task structure with saved registers, stack setup, and a round-robin scheduler
  • Wire an iret-based context switch from the PIT interrupt handler
• Device drivers
  • Implement a generic character/block device registry with dev-style naming so new drivers (serial, mouse, network) can plug in without touching the shell
  • Generalize filesystem layer: add a VFS interface to multiplex FAT/EXT2 and implement writable EXT2
  • Cache directory entries and support write-back buffers
  • Fix issues with the floppy driver
  • Implement more devices (Mouse input, serial ports, USB, Audio, ...)
  • Implement a modular driver/kernel extension system
• Userland
  • Separate shell from kernel code, and split shell into multiple executables (ls, echo, touch, ...)
  • Implement a bash-like shell with scripting capabilities, piping and redirection, ...
  • Implement more tools and commands (hexdump, text editor, pwd, ...)
  • Remove demo code from kernel sources
• Diagnostics and logging
  • Add a ring-buffered kernel log with severity levels, expose it over serial for cross-machine debugging
  • Extend panic() to dump register state/stack traces
• Miscellaneous
  • Improve POSIX/UNIX compliance

And much much more...

Disclaimer on the use of AI

This project has been developed with the assistance of AI tools (notably GitHub Copilot and ChatGPT Codex) to help speed up development and provide code suggestions. While these tools can be helpful, they may also introduce code that is suboptimal, insecure, or incorrect. Which I experience firsthand while reviewing and debugging the generated code, some really crazy bugs got introduced during development. I don't blindly trust AI-generated code, and neither should you. Always review, test, and validate any code produced with the help of AI tools.