uniOS
A scratch-built x86-64 operating system kernel written in C++20.
uniOS is a hobby operating system built from scratch. It features a working shell with command piping, TCP/IP networking, USB support, and runs on real x86-64 hardware.
Features
-
Modular windowing system (GUI) — Desktop environment with draggable windows, taskbar, and icons. Now moved to a dedicated subsystem with a new 8x16 premium terminal font.
-
SSE-Accelerated Renderer — High-performance graphics primitives (fills, gradients, copies) utilizing SSE2 SIMD instructions. Features dirty rectangle tracking and double buffering.
-
Initial FAT32 Support — Early infrastructure for FAT32 filesystem parsing (boot sectors and block device abstraction).
-
C++20 Kernel — Built with
-fno-exceptionsand-fno-rtti. Useskstring::utilities instead ofstd::to avoid libc dependencies. -
Bitmap PMM & 4-Level Paging — Physical memory tracked via dynamic bitmap allocator. Recursive 4-level paging for virtual memory. Support for systems with any amount of RAM.
-
Preemptive Multitasking — 1000Hz timer-based scheduling. 16KB kernel stacks per process. Features O(1) task insertion for improved scalability.
-
Heap Page Coalescing — Bucket-based allocator with automatic page coalescing. Fully freed pages are returned to the PMM to prevent memory fragmentation.
-
Scratch-built TCP/IP Stack — Hand-written Ethernet, ARP, IPv4, ICMP, UDP, TCP, DHCP, and DNS.
-
Interrupt-driven USB Stack — USB 3.0 (xHCI) support with initial USB Hub detection. Switched to efficient interrupt-driven event handling.
-
Audio Stack — Dual support for Intel HD Audio (HDA) and AC97. Play WAV/PCM files directly from the shell with per-channel volume control.
-
MSI-X Support — Support for Message Signaled Interrupts (MSI-X), providing significantly lower interrupt latency compared to traditional I/O APIC.
-
Modern Debug System — Overhauled logging with module-based filtering and severity levels.
Known Limitations
Warning
These are architectural constraints, not bugs.
| Limitation | Details |
|---|---|
| Experimental user-mode | Basic syscall interface (exit, read, write). No memory protection between processes yet. |
| USB polling | HID devices polled on timer, not via hardware interrupts. |
| QEMU-first | Tested primarily on QEMU. Real hardware may have driver issues. |
Getting Started
Prerequisites
gcc(cross-compiler forx86_64-elf)nasmxorrisoqemu-system-x86_64python3(for uniFS image generation)
Build & Run
# Clone the repository
git clone https://github.com/unionyxx/uniOS.git
cd uniOS
# Build Limine (one-time setup)
git clone https://github.com/limine-bootloader/limine.git --branch=v8.x-binary --depth=1
make -C limine
# Build and run
make run
# Or with networking
make run-netMake Targets
| Target | Description |
|---|---|
make |
Build release (optimized, no debug output) |
make debug |
Build with DEBUG_* logging enabled |
make run |
Run in QEMU |
make run-net |
Run with e1000 networking |
make run-usb |
Run with xHCI USB (keyboard/mouse) |
make run-sound |
Run with AC97 sound card |
make run-serial |
Run with serial output to stdio |
make run-gdb |
Run with GDB stub on localhost:1234 |
make clean |
Remove build artifacts |
Tip
Use make run-gdb to attach a debugger to QEMU on localhost:1234.
Shell Commands
| Category | Command | Description |
|---|---|---|
| Files | ls |
List files with type and size |
cat <file> |
Display text file contents | |
stat <file> |
Show file information | |
hexdump <file> |
Hex dump of file | |
touch <file> |
Create empty file | |
rm <file> |
Delete file | |
write <file> <text> |
Write text to file | |
append <file> <text> |
Append text to file | |
df |
Show filesystem usage | |
| Text | grep <pattern> [file] |
Search for pattern |
wc [file] |
Count lines, words, characters | |
head [n] [file] |
Show first N lines (default 10) | |
tail [n] [file] |
Show last N lines (default 10) | |
sort [file] |
Sort lines alphabetically | |
uniq [file] |
Remove consecutive duplicates | |
rev [file] |
Reverse each line | |
tac [file] |
Reverse line order | |
nl [file] |
Number lines | |
tr <from> <to> |
Translate characters | |
echo <text> |
Print text | |
| System | mem |
Show memory usage |
uptime |
Show system uptime | |
date |
Show current date/time | |
cpuinfo |
Show CPU information | |
lspci |
List PCI devices | |
version |
Show kernel version | |
uname |
Show system name | |
clear |
Clear screen | |
reboot |
Restart system | |
poweroff |
Shutdown system | |
| Network | ifconfig |
Show network configuration |
dhcp |
Request IP via DHCP | |
ping <host> |
Ping an IP or hostname | |
| Audio | audio status |
Show audio device status |
audio play <file> |
Play WAV file | |
audio pause |
Pause playback | |
audio resume |
Resume playback | |
audio stop |
Stop playback | |
audio volume [0-100] |
Get/set volume | |
| Scripting | run <file> |
Execute script file |
source <file> |
Execute in current context | |
set NAME=value |
Set variable | |
unset NAME |
Unset variable | |
env |
List all variables | |
test <expr> |
Evaluate expression | |
expr <math> |
Arithmetic expression | |
read <var> |
Read user input | |
sleep <ms> |
Sleep milliseconds | |
time <cmd> |
Time command execution | |
true / false |
Exit status 0 / 1 |
Note
Commands can be piped: ls | grep elf | wc
The shell parser splits by spaces. Pipes use a fixed 4KB buffer.
Keyboard Shortcuts
| Shortcut | Action |
|---|---|
| Tab | Command/filename completion |
| Ctrl+A | Move to start of line |
| Ctrl+E | Move to end of line |
| Ctrl+U | Cut text before cursor |
| Ctrl+K | Cut text after cursor |
| Ctrl+W | Delete word before cursor |
| Ctrl+Y | Paste (yank) |
| Ctrl+C | Copy selection / cancel line |
| Ctrl+L | Clear screen |
| ↑/↓ | Navigate command history |
| ←/→ | Move cursor |
| Home/End | Jump to start/end |
| Delete | Delete character at cursor |
| Shift+←/→ | Select text |
Project Structure
├── include/ # Header files
│ ├── boot/ # Limine boot protocol
│ ├── kernel/ # Kernel core headers
│ ├── drivers/ # Driver interfaces
│ └── libk/ # Kernel library
├── src/ # Source files
│ ├── kernel/ # Core kernel logic
│ │ ├── core/ # Entry (kmain), CPU, IRQ, GUI, Syscalls
│ │ ├── sched/# Task scheduler
│ │ ├── shell/# Command interpreter
│ │ ├── sync/ # Mutex, Spinlock
│ │ └── time/ # PIT Timer
│ ├── arch/ # CPU/Arch specific code (x86_64)
│ ├── mm/ # Memory management (PMM, VMM, Heap, VMA)
│ ├── drivers/ # Hardware drivers (Net, USB, Audio, Video, PCI, ACPI)
│ ├── fs/ # Filesystems (uniFS, FAT32, Block Dev)
│ └── net/ # TCP/IP stack
└── tools/ # Build and sync utilities
License
This project is licensed under the MIT License - see the LICENSE file for details.