EquinoxOS

A hobby monolithic kernel for x86_64 — with a real GUI, preemptive multitasking, networking, and audio.

Project is discontinued for unknown amount of time

What is EquinoxOS?

EquinoxOS is a from-scratch hobby operating system for x86_64 written in C and ASM. It boots via the Limine bootloader in 64-bit Higher Half mode, runs a compositing window manager with drop shadows and z-ordering, supports true preemptive multitasking with Ring 3 user-space isolation, dual filesystem support (FAT32 + EXT2), a full TCP/IP network stack, AC97 audio, and even runs a port of DOOM.

It's made to be minimally daily-usable while staying readable and educational.

🏗 System Architecture

graph TD
    subgraph UserSpace["🧑 User Space (Ring 3)"]
        ELF[ELF64 Executables] --> SDK[EquinoxOS SDK / CRT0]
        SDK --> SYSCALL[int 0x80 Syscall Interface]
    end

    subgraph KernelCore["⚙️ Kernel Core (Ring 0)"]
        SYSCALL --> HANDLER[Syscall Handler · 10 calls]
        HANDLER --> TASK[Preemptive Scheduler · Round-Robin]
        HANDLER --> MEM[Memory Manager]
        MEM --> PMM[PMM · Bitmap Allocator]
        MEM --> VMM[VMM · 4-Level Paging]
        MEM --> HEAP[Kernel Heap · kmalloc/kfree]
        MEM --> SHM[Shared Memory · shm_alloc]
    end

    subgraph Subsystems["🔧 Kernel Subsystems"]
        VFS[Virtual File System] --> FAT32[FAT32 R/W · ATA PIO]
        VFS --> EXT2[EXT2 R/W · ATA PIO]
        VFS --> DEVFS[Device Nodes]
        GUI[CWM Compositor] --> VESA[VESA LFB · Direct Framebuffer]
        GUI --> SHADOW[Drop Shadow · Alpha Blend]
        NET[Network Stack] --> RTL[RTL8139 Driver]
        NET --> ARP_IP[ARP · IPv4 · ICMP]
        NET --> UDP_TCP[UDP · TCP 3-way handshake]
        NET --> HTTP_DNS[HTTP GET · DNS · NTP]
        AUDIO[AC97 Driver] --> PCM[PCM Audio Output]
    end

    subgraph Hardware["🖥 Hardware"]
        VESA --> FB[Framebuffer]
        RTL --> NIC[RTL8139 NIC]
        FAT32 --> DISK[ATA Disk]
        EXT2 --> DISK
        AUDIO --> CODEC[AC97 Codec]
        PS2MOU[PS/2 Mouse] --> GUI
        PS2KB[PS/2 Keyboard] --> TASK
        PCI[PCI Bus Scan] --> RTL
        PCI --> AUDIO
    end

🛠 Hardware Support & Features

Category	Component	Status	Notes
Boot	Limine Protocol v3	✅	64-bit Higher Half, memory map, HHDM
CPU	x86_64 + SSE	✅	SSE init (CR0/CR4), used by VESA blitter
Memory — PMM	Bitmap Allocator	✅	Page-granular, `pmm_alloc_continuous()`
Memory — VMM	4-Level Paging	✅	PML4/PDP/PD/PT, separate user address spaces
Memory — Heap	`kmalloc` / `kfree`	✅	64 MB kernel heap
Memory — SHM	Shared Memory	✅	`shm_alloc()` for IPC between tasks
Multitasking	Preemptive Round-Robin	✅	IRQ0 (PIT 50 Hz) context switch
User Mode	Ring 3 Isolation	✅	Per-process PML4, TSS, GDT segments
Graphics	VESA LFB	✅	Double-buffered, hardware cursor, alpha blending
GUI	Compositing WM	✅	Z-ordering, drop shadows, window drag
Storage	ATA PIO	✅	Raw sector R/W for both FS drivers
Filesystem	FAT32	✅	Full Read + Write, 8.3 filenames
Filesystem	EXT2	✅	Read + Write, stress-tested
ELF Loader	ELF64	✅	PT_LOAD segments mapped into user PML4
Network	RTL8139	✅	PCI scan, raw TX/RX
Network	ARP / IPv4 / ICMP	✅	Full IPv4 stack with ICMP ping
Network	UDP / TCP	✅	UDP datagrams + TCP 3-way handshake
Network	HTTP / DNS / NTP	✅	HTTP GET, DNS resolve, NTP time sync
Audio	AC97	✅	PCM output via `SYS_AUDIO_PLAY` syscall
Input	PS/2 Keyboard	✅	Scancode-based, shell + app input
Input	PS/2 Mouse	✅	Relative tracking, click detection
PCI	PCI Bus Scan	✅	Vendor/device ID enumeration
Timer	PIT (8253)	✅	50 Hz tick, `get_time_ms()`
Serial	COM1	✅	Early boot log + QEMU debug output

🖥 Built-in Applications

The OS ships a full desktop environment with the following apps:

App	Description
Terminal	Interactive shell with command history and kernel log streaming
Explorer	Graphical file manager — lists FAT32/EXT2 files, launches ELF executables
Notepad	Text editor with disk save support (`NOTES.TXT` → FAT32/EXT2)
Paint	Drawing app with Bresenham line algorithm + BMP export to disk
System Monitor	Real-time RAM usage bar and process overview
DOOM	The classic id Software shooter, ported to run natively with AC97 sound

External Applications (userspace ELF)

App	How to launch	Description
`snake.elf`	Explorer / `run snake.elf`	Classic snake game
`bmpview.elf`	`run bmpview.elf BG.BMP`	BMP image viewer
`htmlview.elf`	Explorer	Lightweight HTML/DOM viewer (HTTP only)
`browser.elf`	`run bin/browser.elf <url>`	Full graphical web browser — HTTPS/TLS, DNS, HTML/CSS, JavaScript (QuickJS), DOM & images
`niplay.elf`	`run niplay.elf terry.wav`	WAV music player via AC97
`widget_demo.elf`	Explorer	EID v2.0 widget showcase (button / checkbox / text input / slider + animations)
`ipc_test.elf`	Explorer	Pipe & message-queue smoke test (syscalls 60–67)
`doom.elf`	Explorer	DOOM port with AC97 audio

💡 The desktop / system shell itself is now the separate enGUI project, pulled in as the app/sysgui Git submodule and launched as the Ring 3 init process (bin/sysgui.elf). Older versions had Lua (luagui.elf) bundled — Lua was removed from the SDK and app set.

🌐 Web Browser

browser.elf is a from-scratch graphical web browser running as a Ring 3 userspace app. It drives the full network stack and renders real web pages — including this project's own landing page at https://equinoxos.duckdns.org/:

EquinoxOS browser rendering equinoxos.duckdns.org

Capabilities:

🔒 HTTPS / TLS via vendored BearSSL with a bundled Mozilla CA trust store
🌐 DNS + TCP/IP over the rtl8139 driver and the custom kernel network stack
📄 HTML + CSS layout engine — selectors, custom properties (var()), inline images
🟨 JavaScript through an embedded QuickJS engine with DOM bindings, a window object and fetch()
🖼 Image decoding for inline page graphics
🖱 Scrolling, link navigation and an address bar, drawn through the EID v2.0 immediate-mode GUI toolkit

run bin/browser.elf https://equinoxos.duckdns.org/

⚠️ Known limitation: some websites can still bring the OS down with a kernel panic. This is a known issue and is being actively worked on — it will be fixed soon.

⌨️ Developer API (EquinoxOS SDK)

Applications are ELF64 binaries linked at 0x1000000, built with the bundled SDK. All kernel services are accessed via int 0x80.

Syscall Table

`RAX`	Name	Description	Key Args
`1`	`SYS_PRINT`	Write string to terminal + serial	`rdi`: `char* msg`
`2`	`SYS_READ_FILE`	Map file from VFS into user RAM	`rdi`: name, `rsi`: size_out
`3`	`SYS_WRITE_FILE`	Save buffer to VFS (FAT32/EXT2)	`rdi`: name, `rsi`: buf, `rdx`: size
`5`	`SYS_DRAW_BUFFER`	Blit pixel buffer to compositor window	`rdi/rsi`: x/y, `rdx/rcx`: w/h, `r8`: buf
`7`	`SYS_GET_MOUSE`	Get mouse X/Y/buttons from kernel	`rax`: X, `rbx`: Y, `rcx`: buttons
`9`	`SYS_GET_SCANCODE`	Pop keyboard scancode (non-blocking)	—
`10`	`SYS_EXIT`	Terminate process, reclaim RAM	`rdi`: exit_code
`12`	`SYS_GET_FONT`	Map PSF font pointer into user space	—
`20`	`SYS_AUDIO_PLAY`	Submit PCM chunk to AC97 driver	`rdi`: buf, `rsi`: size

EID v2.0 — Immediate Mode GUI Toolkit

EquinoxOS includes EID (Equinox Interface Designer) — an immediate-mode UI toolkit that gives apps full control over their visual style.

#include <eid.h>
#include <equos.h>

eid_ctx_t ui;
uint32_t buffer[400 * 300];

void render() {
    eid_begin(&ui, buffer, 400, 300);
    ui.mx -= win_x;  // Map global → window-relative coords
    ui.my -= win_y;

    uint32_t id    = eid_get_id("OK", 50, 120);
    uint32_t state = eid_process_interaction(&ui, id, 50, 120, 100, 36);

    uint32_t col = (state & EID_STATE_HOVER) ? 0x00FFFF : 0x006666;
    if (state & EID_STATE_ACTIVE) col = 0xFFFFFF;

    eid_draw_rect(buffer, 400, 300, 50, 120, 100, 36, col);
    eid_draw_text(buffer, 400, 300, 68, 130, "OK", 0x000000);

    if (state & EID_STATE_CLICKED) { /* handle */ }
    eid_end(&ui, win_x, win_y);
}

📖 See EID_SDK.md for the full API reference, drawing primitives, and best practices.

📂 Project Structure

EquinoxOS/
├── src/                                  # Kernel source
│   ├── kernel.c                          # kmain() — boot entry, subsystem init
│   ├── api.h                             # EquinoxAPI struct (app ↔ kernel contract)
│   ├── linker.ld                         # Kernel linker script
│   ├── boot/                             # Boot glue
│   │   ├── eqstart.c / eqstart.h         # Early boot init
│   │   ├── boot_config.h                 # Boot configuration
│   │   ├── nyan_data.h                   # Boot splash data
│   │   └── limine/limine.h               # Limine protocol header
│   ├── syslibc/                          # Kernel-side stdio + string helpers
│   └── system/
│       ├── core/                         # GDT, IDT, PIC, CPU, I/O ports, panic, NASM stubs
│       ├── hal/                          # Hardware Abstraction Layer
│       ├── mem/
│       │   ├── pmm.c                      # Bitmap Physical Memory Manager
│       │   ├── vmm.c                      # 4-level Virtual Memory Manager
│       │   ├── memory.c                  # kmalloc / kfree heap
│       │   └── shm.c                     # Shared Memory
│       ├── usr/
│       │   ├── task.c                    # Scheduler + context switch
│       │   ├── syscall.c                 # int 0x80 dispatch table
│       │   ├── ipc.c                     # Pipes + message queues
│       │   └── sync.c                    # Synchronization primitives
│       ├── fs/
│       │   ├── vfs.c / vfs.h             # Virtual File System abstraction
│       │   ├── fs.c                      # FS mount / registration layer
│       │   ├── fat32.c                   # FAT32 driver (R/W)
│       │   ├── ext2.c / ext2_tests.c     # EXT2 driver (R/W) + tests
│       │   ├── gpt.c                     # GPT partition parsing
│       │   └── elf.h                     # ELF64 loader structures
│       ├── drivers/
│       │   ├── vesa/                     # VESA LFB, BMP encoder, PSF2 + 8x8 fonts
│       │   ├── devices/
│       │   │   ├── audio/ac97.c          # AC97 PCM audio driver
│       │   │   ├── keyboard/             # PS/2 keyboard (scancodes)
│       │   │   ├── mouse/                # PS/2 mouse (relative tracking)
│       │   │   ├── pci/                  # PCI bus scan
│       │   │   ├── pcspeaker/            # PC Speaker beeper
│       │   │   └── usb/                  # USB host controllers: UHCI · OHCI · EHCI · xHCI
│       │   └── hardware/
│       │       ├── net/                  # RTL8139 · ARP · IPv4 · ICMP · TCP · UDP · DNS · sockets
│       │       ├── disk/                 # ATA PIO disk driver
│       │       └── serial/               # COM1 serial (QEMU log)
│       ├── misc/                         # PIT 8253 timer, RTC, RNG
│       └── shell/                        # Shell command parser
├── app/                                  # Ring 3 userspace apps
│   ├── snake.c                           # Snake game
│   ├── bmpview.c                         # BMP image viewer
│   ├── htmlview.c                        # HTML/HTTP browser (QuickJS-powered)
│   ├── niplay.c                          # WAV music player
│   ├── widget_demo.c                     # EID v2.0 widget showcase
│   ├── ipc_test.c                        # Pipe + message-queue test app
│   ├── doom/                             # DOOM port (doomgeneric)
│   ├── sysgui/                           # enGUI submodule (Ring 3 init process)
│   ├── urlget.c / httpsget.c / tlsboot.c # HTTP(S) / TLS client tools
│   └── js*.c · *test*.c                  # JS/DOM, networking, socket & misc test apps
├── sdk/                                  # Userspace SDK
│   ├── include/                          # equos.h, eid.h/eid_ext.h, libc + DOM/QuickJS/HTTP headers
│   ├── lib/                              # CRT0 (_start), syscall stubs, libc, eid, QuickJS glue
│   ├── lib_dom/                          # DOM implementation
│   ├── lib_qjs/                          # QuickJS bindings (fetch, window, page, DOM-JS)
│   ├── lib_http/                         # HTTP client
│   ├── lib_image/                        # Image decoding
│   └── codec/                            # WAV / audio codec helpers
├── iso_root/                             # Bootable ISO staging area
│   ├── EFI/BOOT/ · boot/limine/          # Limine UEFI + BIOS boot files
│   ├── bin/                              # Compiled ELF userspace apps
│   └── res/                              # Fonts, wallpapers, HTML tests, Lua sysgui scripts
├── tools/                                # Host build tools (CA bundle fetch · PEM → anchors)
├── resources/                            # Branding & wallpaper assets
├── Makefile                              # Windows build (mingw/msys2 cross-compiler)
├── WINDOWS_ext2.py                       # Python script — generates hdd.img (EXT2)
├── EID_SDK.md                            # Full EID + Syscall reference
├── ROADMAP.md                            # Development phases & milestones
├── CHANGES.md                            # Changelog
├── CONTRIBUTING.md                       # Contribution guide
├── ext2_plan.md / network_plan.md        # Design notes
└── LICENSE                               # GPL-2.0

🚀 Quick Start

Prerequisites

Tool	Purpose
`x86_64-elf-gcc`	Cross-compiler (freestanding, no stdlib)
`nasm`	Assembler for interrupt stubs & CRT0
`x86_64-elf-ld`	Linker
`xorriso`	ISO image creation
`python3`	EXT2 disk image generation
`qemu-system-x86_64`	Virtual machine for testing

Build & Run

# 1. Clone the repo
git clone https://github.com/Equinox-Collective/EquinoxOS.git
cd EquinoxOS

# 2. Build kernel + all apps + create ISO + HDD image
make all

# 3. Launch in QEMU (512 MB RAM, RTL8139, AC97 audio)
make run

Windows users: Use the Makefile (tested with msys2/mingw toolchain).
Linux users: Use Makefile-linux.

Individual Build Targets

make kernel.elf   # Build kernel only
make apps         # Build all userspace ELF apps
make doom.elf     # Build DOOM port
make iso          # Package bootable ISO
make create_hdd   # Generate hdd.img (EXT2) via Python script
make clean        # Remove all build artifacts
make cleanrun     # clean + all + run

Debugging

# addr2line to map a fault RIP to source
x86_64-elf-addr2line -e kernel.elf <RIP_ADDRESS>

# QEMU serial log is written to qemu.log automatically
# and streamed to stdout via -serial stdio

The kernel outputs a full boot log to COM1 (visible in QEMU terminal):

=== EquinoxOS Kernel Starting ===
HHDM offset initialized
GDT initialized  |  SSE initialized  |  PMM initialized
VMM initialized  |  Heap initialized |  VESA initialized
IDT initialized  |  PIC remapped     |  Timer initialized
Task system initialized  |  VFS initialized
FAT32 initialized  |  EXT2 initialized
PCI initialized  |  GUI initialized  |  Shell initialized
=== EquinoxOS Ready ===

🗺 Roadmap

Full details in ROADMAP.md · recent patch set: CHANGES.md

✅ Completed

🔧 In Progress / Planned

Screenshots

👥 Contributors

	Handle	Role
👑	@ewasion137	Lead Developer
⭐	@oxtiskz	Special Thanks (account deleted)
⭐	@gobgolaxi	Contributor
⭐	@Offihito	Contributor
⭐	@Lertov2424232	Contributor

Built from scratch, for the love of low-level programming.

Navigation Menu

Uh oh!

Repository files navigation

EquinoxOS

What is EquinoxOS?

🏗 System Architecture

🛠 Hardware Support & Features

🖥 Built-in Applications

External Applications (userspace ELF)

🌐 Web Browser

⌨️ Developer API (EquinoxOS SDK)

Syscall Table

EID v2.0 — Immediate Mode GUI Toolkit

📂 Project Structure

🚀 Quick Start

Prerequisites

Build & Run

Individual Build Targets

Debugging

🗺 Roadmap

✅ Completed

🔧 In Progress / Planned

Screenshots

👥 Contributors

Star History

About

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
app		app
docs		docs
iso_root		iso_root
resources		resources
sdk		sdk
src		src
third_party		third_party
tools		tools
.gitignore		.gitignore
.gitmodules		.gitmodules
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
WINDOWS_ext2.py		WINDOWS_ext2.py
make_manifest.py		make_manifest.py

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

EquinoxOS

What is EquinoxOS?

🏗 System Architecture

🛠 Hardware Support & Features

🖥 Built-in Applications

External Applications (userspace ELF)

🌐 Web Browser

⌨️ Developer API (EquinoxOS SDK)

Syscall Table

EID v2.0 — Immediate Mode GUI Toolkit

📂 Project Structure

🚀 Quick Start

Prerequisites

Build & Run

Individual Build Targets

Debugging

🗺 Roadmap

✅ Completed

🔧 In Progress / Planned

Screenshots

👥 Contributors

Star History

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Contributors

Languages