HelixaOS

A tiny educational 32‑bit hobby operating system: bootloader → kernel → drivers → text console → framebuffer GUI.

✨ Overview

HelixaOS is a from-scratch 32‑bit protected‑mode hobby OS built to explore low‑level systems topics: multiboot boot flow, IDT + ISRs, PIC + PIT, PS/2 keyboard/mouse input, basic memory mapping, text + framebuffer rendering, and primitive GUI concepts. It currently boots via GRUB (Multiboot2), initializes core hardware, provides a rich text shell, and can switch to a simple framebuffer desktop with icons and a software cursor.

Goal: Be a readable learning codebase, not a production OS. The code favors clarity and instrumentation over micro‑optimizations.

✅ Feature Snapshot

• Multiboot2 GRUB boot (32-bit kernel)
• IDT + exception stubs (0–31) with panic UI + register/CR2 dump
• PIC setup, PIT @100Hz (ticks drive timers, caret blink, redraw pacing)
• Serial logging (mirrors internal ring buffer) + in‑kernel log viewer (Ctrl+L)
• Keyboard input with line editor (history, word delete, cursor nav)
• Shell with basic commands: help, clear, time, echo, reboot, and fault triggers (oops, div0, pf)
• VGA text console (styled regions, scrollback)
• Linear framebuffer mode (1024x768x32 preferred) with:
  • Desktop background + icon grid (with labels)
  • Software cursor (planned: hardware-backed / better blending)
  • Basic window prototype (draggable)
• PS/2 keyboard + mouse initialization (mouse work-in-progress if IRQ routing not active in some runs)
• Minimal 8x8 bitmap font renderer

🗂 Directory Structure

boot/            Multiboot stage + GRUB config
  boot.s         Early entry (multiboot handoff)
  grub/grub.cfg  Boot menu entries (text + framebuffer modes)
kernel/          Core kernel sources
  kernel.c       Entry point, state machine, main loop
  idt.c          Descriptor table + ISR wiring
  interrupts.s   ISR/IRQ stubs
  keyboard.c     PS/2 keyboard handling + line editor
  mouse.c        PS/2 mouse (packet decode, accel, bounds)
  fb.c           Framebuffer primitives + font
  fb_console.c   Text console atop VGA/FB
  ui_fb.c        Simple UI helpers (rects, boxes)
  gui.c          Prototype window/desktop helpers
  screen.c       Mode switching / higher-level drawing
  log.c/log.h    Ring buffer logging system
  serial.c       COM1 UART output
  linker.ld      Linker script (layout control)
Makefile         Build + QEMU runners

🛠 Build

Prerequisites (cross toolchain expected on Linux):

i386-elf-gcc
nasm
grub-mkrescue
xorriso
qemu-system-i386

Build (debug / verbose):

make

Release (quieter serial):

make RELEASE=1

Clean:

make clean

▶️ Run

Frame buffer / GUI path:

make run

GRUB menu entries:

• Text mode (VGA console)
• Framebuffer 640x480x32 / 800x600x32 / 1024x768x32 (preferred)

Serial + run combined:

make run-serial

In RELEASE builds serial UART is suppressed, but logs remain viewable via Ctrl+L in text mode.

🖥 GUI Mode Details

Features:

• Dark desktop + icon grid
• Icon label width handling (long names left-aligned)
• Cursor rendering each frame only when needed
• Planned: basic window manager evolution

Troubleshooting:

• If you see [fb] non-linear fb type unsupported: 2 pick a different framebuffer entry
• Ensure QEMU uses standard VGA (-vga std is baked into Makefile if applicable)
• Mouse: if cursor doesn’t move, IRQ12 may not be firing in this environment—poll fallback + debugging is in progress

⌨️ Keybindings

Shell editing: Left / Right / Home / End / Delete / Backspace / Insert

History: Up / Down

Shortcuts: Ctrl+U (clear line), Ctrl+W (delete word), Ctrl+C (clear), Enter (execute)

Log viewer: Ctrl+L toggle

🐚 Shell Commands

help
clear
time
echo <msg>
reboot
oops   # INT3
div0   # divide-by-zero
pf     # page fault trigger

⚠ Exception Diagnostics

• All CPU exceptions 0–31 stubbed
• Panic UI: vector name, error code, EIP, CR2 (for page faults), register dump

🔧 Internals / Architecture

• Boot: GRUB → multiboot info parsed (framebuffer tag, memory map)
• Paging: Higher-half mapping for framebuffer region (simple static layout)
• Interrupts: IDT populated; PIC remapped; ISRs + IRQ stubs in assembly
• Timer: PIT @100Hz → ticks, scheduling hooks, UI refresh pacing
• Input: PS/2 keyboard (scancode set 1), mouse (packet decode & accel)
• Rendering: Separate VGA text path vs linear framebuffer path
• Logging: Ring buffer + serial mirroring (debug) + in-screen viewer

🧪 Current Limitations

• No dynamic memory allocator yet
• No filesystem / storage drivers
• No real task scheduler or multitasking
• Mouse ISR reliability varies per emulator environment (work-in-progress)
• No network stack
• No SMP / AP startup

🗺 Roadmap (Aspirational)

• Improve mouse IRQ robustness & hardware abstraction
• Add basic physical / virtual memory management structures
• Simple heap allocator (bump → free-list)
• Minimal ELF loader + userland experiment
• Basic task switching (cooperative → preemptive)
• Double-buffered GUI compositor
• Configurable theme + better font
• Filesystem stub (RAMFS) + VFS layer
• Unit tests for pure logic pieces (hosted build)

🤝 Contributing

PRs and educational questions welcome.

• See CONTRIBUTING.md for setup, style, testing, and PR guidelines
• Keep diffs focused and documented; open an Issue for larger refactors/design changes first
• Prefer clarity over cleverness; add comments for hardware‑specific bits

---

Feel free to open issues for questions, learning discussions, or roadmap suggestions.

Happy hacking.