EquinoxOS

KO | EN

gitlite — search

#javascript #ai #typescript #go #golang #rust #docker #nodejs #macos #windows #awesome #cli #vue #mcp

(★ 15)

EquinoxOS: x86-based Operating System.

EquinoxOS Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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*

[![License: GPL-2.0](https://img.shields.io/github/license/Equinox-Collective/EquinoxOS?style=for-the-badge&color=ff6b35&logo=gnu)](https://raw.githubusercontent.com/Equinox-Collective/EquinoxOS/main/)
[![Kernel](https://img.shields.io/badge/Kernel-Monolithic-crimson?style=for-the-badge)](https://raw.githubusercontent.com/Equinox-Collective/EquinoxOS/main/)
[![Arch](https://img.shields.io/badge/Arch-x86__64-5c6bc0?style=for-the-badge)](https://raw.githubusercontent.com/Equinox-Collective/EquinoxOS/main/)
[![Boot](https://img.shields.io/badge/Bootloader-Limine-1a1a2e?style=for-the-badge)](https://raw.githubusercontent.com/Equinox-Collective/EquinoxOS/main/)
[![Language](https://img.shields.io/badge/Language-C%20%2B%20ASM-00897b?style=for-the-badge&logo=c&logoColor=white)](https://raw.githubusercontent.com/Equinox-Collective/EquinoxOS/main/)
[![Status](https://img.shields.io/badge/Status-Active%20Development-f9a825?style=for-the-badge)](https://raw.githubusercontent.com/Equinox-Collective/EquinoxOS/main/)
[![Ring3](https://img.shields.io/badge/Ring%203-User%20Mode-8e24aa?style=for-the-badge)](https://raw.githubusercontent.com/Equinox-Collective/EquinoxOS/main/)
[![Sound](https://img.shields.io/badge/Audio-AC97-e53935?style=for-the-badge)](https://raw.githubusercontent.com/Equinox-Collective/EquinoxOS/main/)

</div>

---

## 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

```mermaid
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

---

## 🖥 Built-in Applications

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

### External Applications (userspace ELF)

> 💡 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/`:

</div>

**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

```sh
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

### 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.

```c
#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**](EID_SDK.md) for the full API reference, drawing primitives, and best practices.

---

## 📂 Project Structure

```text
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

### Build & Run

```bash
# 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

```bash
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

```bash
# 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
```

---

## 🗺 Roadmap

> Full details in [ROADMAP.md](ROADMAP.md) · recent patch set: [CHANGES.md](CHANGES.md)

### ✅ Completed

- [x] x86_64 Higher Half kernel via Limine (HHDM)
- [x] Bitmap PMM + 4-level VMM + 64 MB kernel heap
- [x] Preemptive Round-Robin scheduler (IRQ0 / PIT 50 Hz)
- [x] Ring 3 user mode with isolated per-process address spaces
- [x] GDT / IDT / TSS — proper kernel+user segments
- [x] ELF64 loader → Ring 3 jump (CRT0)
- [x] Syscall interface (`int 0x80`) — 30+ calls (print, file R/W, draw, mouse, kbd, exec, audio, net, shm, pipes, mqueue, …)
- [x] VESA LFB with compositing WM, alpha shadows, z-ordering
- [x] ATA PIO + FAT32 R/W + EXT2 R/W (stress-tested) + VFS abstraction
- [x] RTL8139 NIC + full happy-path TCP/IP stack (ARP, IPv4, ICMP, TCP, UDP, DNS, NTP, HTTP GET)
- [x] AC97 PCM audio driver
- [x] PS/2 keyboard & mouse, PCI bus scan, COM1 serial debug
- [x] Shared Memory (`shm_alloc`)
- [x] PSF font rendering (loaded from `/res/font.psf`)
- [x] **HAL skeleton** — `hal_display_ops_t` / `hal_input_ops_t` / `hal_block_ops_t` registry with adapters for VESA, PS/2, ATA PIO
- [x] **GPT partition table parser** (UTF-16 names, header validation; CRC32 still TODO)
- [x] **Sync primitives** — spinlock, waitqueue, sleeping mutex, counting semaphore
- [x] **IPC** — kernel pipes (4 KB ring buffer) + priority message queues + syscalls 60–67
- [x] **PSF2 font renderer** in the kernel (variable glyph width, Unicode, UTF-8 decoder)
- [x] **EID v2.0 widget set** — button / checkbox / text input / slider + animation helper (linear / quad / cubic easing)
- [x] **enGUI** spun out as a Git submodule (`app/sysgui`) and launched as the Ring 3 init process
- [x] DOOM port with AC97 audio · HTTP browser (`htmlview.elf`) · WAV player (`niplay.elf`)
- [x] USB stack (UHCI / EHCI / xHCI)

### 🔧 In Progress / Planned

- [ ] AHCI/SATA driver (slot into the HAL block interface, retire ATA PIO)
- [ ] VFS file descriptors (`open` / `read` / `write` / `close`, seek, stat) and pipe VFS nodes
- [ ] EXT2 indirect / double-indirect / triple-indirect blocks (large files)
- [ ] GPT CRC32 verification + multi-partition VFS mount
- [ ] SSE/AVX-accelerated compositing (needs FXSAVE/FXRSTOR on context switch)
- [ ] Real-time blur (Gaussian/Box) and WM-level window animations
- [ ] Kernel-side TrueType rendering (userspace `stb_truetype.h` already in SDK)
- [ ] Cross-process shared memory for GUI event streaming
- [ ] Port `mlibc` / `newlib` as a full libc → self-hosting (TCC / GCC inside the OS)
- [ ] Shell scripting, env vars, native piping via kernel pipes
- [ ] DHCP client + DNS cache, full TCP state machine with retransmission, POSIX socket syscalls
- [ ] HTTPS (BearSSL / mbedTLS port) + RNG + cert store
- [ ] Intel HD Audio driver and multi-stream software mixer
- [ ] Native EquinoxFS format + installable ISO that writes the OS to disk

---

### Screenshots

</div>

---

## 👥 Contributors

---

[![License: GPL-2.0](https://img.shields.io/github/license/Equinox-Collective/EquinoxOS?style=flat-square&color=ff6b35)](https://raw.githubusercontent.com/Equinox-Collective/EquinoxOS/main/LICENSE)
[![Stars](https://img.shields.io/github/stars/Equinox-Collective/EquinoxOS?style=flat-square&color=f9a825)](https://github.com/Equinox-Collective/EquinoxOS/stargazers)
[![Forks](https://img.shields.io/github/forks/Equinox-Collective/EquinoxOS?style=flat-square&color=5c6bc0)](https://github.com/Equinox-Collective/EquinoxOS/network/members)
[![Last Commit](https://img.shields.io/github/last-commit/Equinox-Collective/EquinoxOS?style=flat-square)](https://github.com/Equinox-Collective/EquinoxOS/commits)

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

</div>

---

## Star History

EquinoxOS

EquinoxOS Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

EquinoxOS

EquinoxOS Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README