ArkOS: Comprehensive System Architecture & Implementation Guide

This guide documents the technical details of the ArkOS system boot flow, signature verification pipeline, the arkrt monolithic system services framework, the isolated Main User UI (swift_splash), and the Unix Domain Socket IPC communication layer.

1. System Boot Flow

The ArkOS boot sequence traverses multiple stages of execution, beginning with the boot sector and ending with the isolated user space application:

graph TD
    A[Bootloader Sector 1] -->|Loads Stage 2| B[Stage 2 Bootloader]
    B -->|Modesetting & Quiet Console| C[Linux Kernel]
    C -->|Launches PID 1| D[init.c]
    D -->|Quiet Verified Boot Check| E[arkrt Daemon]
    E -->|Isolated fork & execve| F[swift_splash UI]
    F -->|Unix Domain Socket IPC| E

Stage 1: Bootloader Sector 1

File: bootloader.asm
Purpose: A standard 512-byte x86 Master Boot Record (MBR) loaded by the BIOS at address 0x7C00. It initializes segment registers, sets up a temporary stack, and loads the larger Stage 2 bootloader from disk sectors into memory before transferring control.

Stage 2: Bootloader Stage 2

File: stage2.asm
Purpose: Initializes protected mode, sets up the Global Descriptor Table (GDT), configures VESA BIOS Extensions (VBE) for graphics modesetting, and passes control to the Linux kernel.
Boot Parameters: Configured with console=tty0 logo.nologo quiet to prevent the kernel from dumping device detection and mode initialization text, ensuring a seamless visual transition to the screen clear.

Stage 3: Userspace Initialization (PID 1)

File: init.c
Purpose: Executed by the Linux kernel as the first userspace process (PID 1).
- Mounts virtual filesystems: /proc, /sys, and /dev (via mount syscalls).
- Performs a quiet signature verification of the arkrt daemon executable.
- Spawns the arkrt process via fork() and execve().
- Enters a loop waiting for the daemon. If the daemon crashes, it hangs to prevent a kernel panic.

2. Verified Boot Signature Check

ArkOS enforces a secure verified boot mechanism for its user space services.

Signature Key & Generation

Compiler/Signer: build.c / sign.py
Mechanism:
- During compilation, build.c compiles the arkrt binary.
- The signing tool hashes the compiled arkrt executable using SHA-256.
- It encrypts/signs the hash using the Verified Boot secure build key to generate signature.bin.
- The hardcoded verification key ARK-OS-... is injected directly into init.c as a macro ARK_KEY.

Verification Step (Inside `init.c`)

Before launching /arkrt, init.c reads the contents of /arkrt and computes its SHA-256 checksum.
It compares the checksum against the signature verification key.
If the signature is correct, it prints [OK] (silenced to keep the boot quiet) and executes the daemon. If it fails, the boot sequence halts.

3. The `arkrt` Monolithic System Service Framework

The arkrt service manager acts as the core system daemon of ArkOS, running as a privileged background process.

Component Location: arkrt/
Core Architecture Components:

Kernel & Hardware Bridge (`KernelBridge.swift`)

Memory Tracking: Calls the Linux getrusage API with 0 (RUSAGE_SELF) to read the resident set size (ru_maxrss) dynamically and verify that idle consumption does not cross the 2.0 GB RAM cap.
Resource Controller: Enforces thread execution boundaries on the 2-core CPU configuration by dispatching async operations to a designated, restricted thread pool.
Log Manager: Manages an in-memory, non-blocking circular buffer of system logs. Features a thread-safe lock-free mechanism to allow logging from concurrent threads.
Power Management: Scans /sys/class/power_supply dynamically to locate the battery subsystem node (e.g. BAT0, BAT1), parses the capacity percentage file, and triggers system shutdown via a wrapper calling the Linux C symbol reboot with LINUX_REBOOT_CMD_POWER_OFF (0x4321fedc).
Network Interface Manager: Scans /sys/class/net to query interface names, and queries getifaddrs from libc to dynamically parse IPv4 address buffers of active networks (filtering out loopback devices).

Unix Domain Socket IPC (`IPC.swift`)

Binds a Unix Domain Socket at /dev/arkrt.sock using static handlers.
Listens for connections in a concurrent dispatch queue managed by the Resource Controller thread pool.
Enforces an autoreleasepool block around connection cycles on Linux to guarantee that intermediate structures allocated during socket operations are immediately reclaimed.

Command Router (`CommandRouter.swift`)

Interprets and processes requests from the UI using a zero-copy parsing structure.
Matches and extracts parameters via UnsafeRawBufferPointer to route request codes to their corresponding Swift namespace handlers under the ark.system API layer.

4. IPC Binary Protocol Specification

Communication between the isolated UI and arkrt uses a strict binary packet structure. This eliminates JSON/string serialization parsing overhead and ensures high performance.

Packet Frame Layout

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|       Command ID (2 Bytes)    |      Payload Length (4 Bytes)  |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       Payload Data (N Bytes)                  |
|                               ...                             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Command ID (UInt16): The numeric code representing the system call command (sent big-endian).
Payload Length (UInt32): The size of the payload following the header in bytes (sent big-endian).
Payload Data: Raw UTF-8 bytes of the parameter or returned data.

Supported Command ID Reference

Command ID	Command Name	Description	Response Format
101	`CMD_GET_TIME`	Retrieve system formatted time	UTF-8 String (e.g., `Jul 5, 2026 at 10:12:00 AM`)
102	`CMD_GET_IP`	Query active interface IP	UTF-8 String (e.g., `10.0.2.15` / `127.0.0.1`)
103	`CMD_GET_BATTERY`	Query battery level percentage	UTF-8 String (e.g., `98%`)
104	`CMD_GET_BLUETOOTH`	Query Bluetooth device status	UTF-8 String (`ACTIVE` or `INACTIVE`)
105	`CMD_SHUTDOWN`	Shutdown the OS	UTF-8 String (`SHUTTING_DOWN`)
106	`CMD_DUMP_LOGS`	Retrieve circular buffer logs	Newline-separated UTF-8 Log String

5. Isolated Main User UI (`swift_splash.swift`)

The user interface layer is decoupled from the service framework, operating as an isolated process with restricted privileges to prevent UI faults from crashing the kernel.

Double-Buffered Rendering

Opens the system framebuffer /dev/fb0.
Maps the screen memory to userspace using a shared pointer (mmap).
Pre-allocates two memory blocks: a static template buffer (tpl) and an active workspace buffer (work).
Draws anti-aliased geometries into the workspace buffer first, then calls a custom blit loop using memcpy to sync the workspace to the screen framebuffer. This eliminates vertical tearing and flickering.

High-Resolution AA Algorithms

Filled Disk AA (diskAA): Draws a filled circle at a coordinate $(cx, cy)$ with radius $r$. It computes pixel distances and applies linear opacity interpolation on the edges: $$\alpha = r_{\text{outer}} - d$$ Ensuring smooth, anti-aliased circular corners.
Ring AA (ringAA): Draws a hollow outline of a circle by evaluating whether the pixel falls on the inner or outer border limits, interpolating transparency symmetrically around the center radius.

Isolated IPC Query Loop

Once the splash screen animation completes, the UI launches an IPC client:

Connects to the Unix socket /dev/arkrt.sock.
Sends binary header requests for system statistics.
Parses the incoming response payloads zero-copy using UnsafeRawBufferPointer.
Prints the formatted statistics onto the screen's canvas.

arkos_architecture_guide.md 8.4 KB History Raw