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 (ui_daemon), 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[arkrt Daemon]
    D -->|Isolated fork & execve| E[ui_daemon]
    E -->|Unix Domain Socket IPC| D
    D -->|Isolated fork & execve| F[setup_app]

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: arkrt/main.swift
Purpose: Executed by the Linux kernel as the first userspace process (PID 1).
- Mounts virtual filesystems: /proc, /sys, and /dev (via mount syscall wrappers).
- Initializes the monolithic arkrt daemon directly.
- Spawns subsequent system services like ui_daemon and setup_app based on configuration files parsed by ServiceManager.swift.

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 (During Boot Sequence)

Since arkrt is now PID 1, verification checks can be integrated directly into the bootloader staging or deferred to the kernel signature validation mechanism.
The build tool build.c still generates signature.bin for integrity.

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:

Statically Linked Vendor Libraries (Telemetry & System)

To guarantee execution without dynamic linker (ld.so) overhead and eliminate dependency hell, arkrt compiles core Apple libraries directly into its monolithic module:

swift-metrics: Provides an abstract telemetry API used by services to emit counters, timers, and gauges. Used for performance tracking within the IPC router and display compositor. In ArkOS, a custom metrics backend handles these emissions without external dependencies, buffering them in memory to be queried via the IPC CMD_DUMP_LOGS or metrics-specific commands. It enables the system to monitor boot times, UI frame rates, and IPC round-trip latency at a granular level.
swift-system: Provides low-level, idiomatic Swift bindings for Linux system calls and file descriptors, ensuring type-safe access to POSIX APIs without raw UnsafePointer manipulation.
swift-argument-parser: Parses early boot command-line flags injected by the kernel (e.g. init=/init --recovery). Because these are compiled from source simultaneously with arkrt (swiftc -o arkrt $(find arkrt -name "*.swift")), there is no module import overhead. All types are natively available within the unified binary.

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%\\|Charging\\|AC`)
104	`CMD_GET_BLUETOOTH`	Query Bluetooth device status	UTF-8 String (`ACTIVE\\|hci0` 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
107	`CMD_GET_INTERFACES`	List all network interfaces	Pipe-delimited lines: `name\\|UP/DOWN\\|CARRIER/NO_CARRIER\\|ip\\|mac`
108	`CMD_GET_SERVICES`	Query service manager status	Pipe-delimited service status report
109	`CMD_RESTART_SERVICE`	Restart a named service	UTF-8 String (`OK:RESTARTED:name`)
110	`CMD_GET_SYSTEM_INFO`	CPU, RAM, uptime summary	Pipe-delimited: `cores=N\\|ram=X/YMB\\|uptime=Zh Ym\\|net=Connected`
111	`CMD_GET_CPU_USAGE`	Query current CPU utilization	UTF-8 String (e.g., `23.5%`)
112	`CMD_GET_MEMORY_USAGE`	Query RAM usage statistics	UTF-8 String (e.g., `512/2048MB\\|available=1536MB`)

5. Wayland Server (`ArkCompositor`) & Client (`ui_daemon`)

ArkOS integrates a custom Wayland server and client architecture natively into the OS without relying on external compositors like Weston or Mutter. The arkrt daemon functions as the primary Wayland display server (ArkCompositor), while user interface applications (such as ui_daemon and setup_app) act as Wayland clients using the ArkGraphics framework.

Wayland Server (`ArkCompositor` in `arkrt`)

Initialization: When arkrt boots, it calls ArkCompositor.shared.start() to initialize the native C-based Wayland server (ark_wayland_server.c).
Event Loop Integration: The compositor's dispatch() method is integrated directly into the arkrt core event loop, meaning the init daemon itself pumps display events and handles shared memory (SHM) buffer allocation.
Direct Framebuffer Access: The compositor maps the Linux /dev/fb0 framebuffer memory directly into userspace. It receives wl_surface_commit events from clients and copies their rendered memory into the physical screen.

Wayland Client (`ArkGraphics`)

Connection: UI processes initialize an ArkGraphics object which connects to the local Wayland socket (wayland-0).
Shared Memory (SHM): The client allocates anonymous shared memory files via memfd_create, creating a double-buffer which it registers with the compositor.
Rendering: Clients perform software rendering (e.g., anti-aliased geometry, typography) directly into this shared memory space.
Commit: The client calls ArkGraphics.pan() which translates to wl_surface_damage and wl_surface_commit, notifying the ArkCompositor to redraw the screen.

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.

C-Based Optimized 4K Typography

High-resolution text scaling (up to 6x, e.g. 192x192 pixels per character) is supported via a custom font generation pipeline (tools/font_gen.py).
The font data is generated as an optimized static C array (ArkFontRobotoBoldData.c) to avoid overloading the Swift compiler.
Swift directly links and accesses this C-array memory without copying, enabling ultra-fast, zero-overhead font mapping at crisp 4K resolutions.

Isolated IPC Query Loop

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

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

6. Comprehensive File Tree & Implementation Status

The ArkOS repository contains a mix of fully implemented core systems and placeholder directories reserved for future user space applications, UI elements, and hardware abstraction layers. The following section maps out each component, detailing its operational mechanics and current integration status without visual markers.

Boot & Kernel Operations

boot/ [Status: Fully Implemented]
- Mechanics: This directory controls the initial power-on sequence. It contains bootloader.asm and stage2.asm for x86 architecture boot processes, alongside bootloader.c for UEFI systems. The loaders initialize memory, set up the Global Descriptor Table (GDT), and transition the system into protected mode before handing execution over to the Linux kernel. It also contains rules for packing the initramfs.
- animationframes/: Houses the pre-rendered binary frames (frame_000.bin to frame_099.bin) used specifically for the Atom boot animation sequence executed during stage transitions.
kernel/ [Status: Fully Implemented]
- Mechanics: Contains the Linux kernel source tree. This kernel has been heavily patched and configured strictly for ArkOS to support specialized IPC, customized display framebuffer handling, and rigid resource control restrictions that tie into arkrt.

System Initialization & Core Daemon

system/ [Status: Fully Implemented]
- ui_daemon: The isolated UI compositor process that acts as the visual layer during initialization and beyond. It maps the /dev/fb0 framebuffer into user space via fb_helper.c and performs double-buffered software rendering.
- apps/setup_app.swift: The ArkOS initial Welcome screen, built entirely with the declarative ArkUI framework.
- sysroot/: The basic skeleton of the root filesystem (/etc, /usr, /lib, /sbin) populated during the build stage.
- services/: Holds .serve configuration files managed by ServiceManager.swift.
arkrt/ [Status: Fully Implemented]
- Mechanics: The central monolithic Ark Runtime daemon, operating directly as PID 1. Written in Swift, it contains KernelBridge.swift for hardware telemetry (reading /sys/class/power_supply and network interfaces), IPC.swift for binding the /dev/arkrt.sock Unix domain socket, and ServiceManager.swift which reads /system/services/ to manage daemon lifecycles. It effectively orchestrates process management, memory tracking, and all privileged operations.

Frameworks & UI Architecture

frameworks/
arkrt/ark.ui.basic/ (SwiftCrossUI) [Status: Partially Implemented]: A modified fork of SwiftCrossUI acting as the declarative UI framework for ArkOS.
- Current Integration: The framework successfully compiles within the out_staging directory using incremental caching (--scratch-path). The type-erasure and protocol constraints have been resolved to prevent compiler crashes during cross-module optimization. However, it is not yet fully dynamically linked or actively utilized by the overarching Desktop Environment shell.
- DRM/ [Status: Unimplemented Placeholder]: The skeletal structure for a Digital Rights Management client and daemon intended for secure media playback.
ark.display.graphics/ (ArkGraphics) [Status: Fully Implemented]
- Mechanics: Integrates native Wayland and LibDRM components into the arkrt daemon.
- Static C Module Compilation: Because arkrt is a monolithic static binary built with musl libc, build_graphics_c.sh cross-compiles Wayland and LibDRM C sources using the Swift SDK's musl sysroot. This avoids glibc-specific header collisions (such as gnu_dev_makedev or __cmsg_nxthdr).
- LibFFI Stubbing: Wayland relies on libffi for dynamic protocol dispatch. To avoid adding heavyweight dynamic linkage to the kernel, lightweight stub implementations (ffi_stubs.c) are provided to pacify the static linker until full runtime FFI processing is required.
- Swift Import: Both libraries define module.modulemap to expose their C headers. ArkGraphics.swift natively imports CWayland and CLibDRM, providing a Swift API layer over the compositing logic.
prebuilts/ [Status: Fully Implemented]
- Swift/: Contains the precompiled Swift 6.3.2 runtime and standard libraries required for statically linking Swift code. This SDK is shipped directly with the OS.
- clang/: LLVM/Clang 22 toolchain for compiling C/C++ targets across all architectures.
- mimalloc.o: Microsoft's ultra-fast mimalloc memory allocator, shipped as a prebuilt object file and statically linked during OS compilation.
  
  Vendor Verification
vendor/ [Status: Partially Implemented]
- verify/: Contains Python scripts (sign.py, key.py) and C headers (sha256.c) used dynamically during the build process to cryptographically sign the arkrt executable, ensuring the chain of trust established in init.c.
- mirror/ & OS_INFO: Files specifying OS update mirror endpoints and metadata strings identifying the OS build version.
- Widewine/ [Status: Unimplemented Placeholder]: Contains a mocked drm.ark file reserved for future Widevine DRM binary blobs.

Build Orchestration & Image Assembly

tools/ [Status: Fully Implemented]
- Mechanics: Contains the build.c orchestrator. This highly customized C program manages the compilation pipeline. It utilizes incremental compilation techniques (cp -ur) and Swift Package Manager's caching layers to assemble the Swift UI framework rapidly. It ultimately packs the rootfs, kernel, and initial ramdisk into standard .img files.
out_staging/ [Status: Fully Implemented]
- Mechanics: The scratchpad directory generated dynamically during the make build cycle. All intermediate object files, static libraries, and .swift_build artifacts are housed here before final assembly.
finished/ [Status: Fully Implemented]
- Mechanics: The final output destination where the bootable disk images are deployed, ready to be flashed to physical media or booted in an emulator.
- boot.img: Bootloader + animation + kernel + initramfs (x86_64 only).
- sys.img: System partition containing frameworks, libraries, and apps.
- vend.img: Vendor partition with DRM blobs, mirror info, and signing data.
- vbk.img: Verified Boot Key — contains securebuild.ark with the signing key. The bootloader reads this key and compares it against the signatures on sys.img and vend.img. If they don't match, boot fails.
- vbmeta.img: Boot metadata — contains vbmeta.ark which tells the bootloader the partition layout and how to mount each image. This is loaded first during the boot process.
- dtbo.img: Device Tree Blob Overlays — contains all .dtb and .dtbo files from kernel/prebuilts/. The bootloader extracts these and makes them available to the kernel.
- rpi4.img (ARM64 only): A single flashable SD card image combining all partitions (boot, system, vendor) for direct flashing to an RPi4.

7. Deep Dive: Line-by-Line Code Execution & Output Analysis

This section explores the fundamental lines of code orchestrating ArkOS, examining what each block executes, its interactions with the kernel, and the exact outputs produced at runtime.

7.1. Stage 1 Bootloader: `bootloader.asm`

The Stage 1 bootloader operates in 16-bit real mode. It is precisely 512 bytes, residing in the Master Boot Record (MBR).

Segment Initialization & Stack Setup

[BITS 16]
[ORG 0x7C00]

start:
    cli                     ; Disable interrupts while setting up segments
    xor ax, ax              ; Zero out AX register
    mov ds, ax              ; Data Segment = 0
    mov es, ax              ; Extra Segment = 0
    mov ss, ax              ; Stack Segment = 0
    mov sp, 0x7C00          ; Stack pointer starts at 0x7C00 (grows downwards)
    sti                     ; Re-enable interrupts

Execution & Output: When the BIOS hands over control, it jumps to 0x7C00. The cli command disables interrupts to prevent the CPU from handling hardware events while memory boundaries are undefined. Setting DS, ES, and SS to zero ensures all memory addressing is absolute relative to 0x0000. The stack pointer is placed exactly at 0x7C00 (right below our bootloader code) so stack push operations won't overwrite the bootloader. Output: Silent memory configuration.

Disk Reading (INT 13h)

load_stage2:
    mov ah, 0x02            ; BIOS Read Sector function
    mov al, 16              ; Number of sectors to read (16 sectors = 8KB)
    mov ch, 0               ; Cylinder 0
    mov cl, 2               ; Sector 2 (Sector 1 is this MBR)
    mov dh, 0               ; Head 0
    mov dl, [boot_drive]    ; Drive number passed by BIOS
    mov bx, 0x7E00          ; Buffer address (directly after MBR in memory)
    int 0x13                ; Call BIOS disk interrupt
    jc disk_error           ; Jump to error handler if carry flag is set

Execution & Output: The bootloader uses BIOS interrupt 0x13 to read from the disk. It reads the subsequent 16 sectors into 0x7E00 (the memory region immediately following 0x7C00 + 512 bytes). If the disk read fails, the CPU sets the Carry Flag (jc), triggering a halt. Output: Loads the Stage 2 bootloader into RAM.

Transition to Protected Mode

    cli                     ; Disable interrupts for mode switch
    lgdt [gdt_descriptor]   ; Load Global Descriptor Table

    mov eax, cr0
    or eax, 0x1             ; Set Protected Environment (PE) bit in CR0
    mov cr0, eax

    jmp 0x08:protected_mode ; Far jump to flush instruction pipeline

Execution & Output: Interrupts are disabled permanently for the remainder of the bootloader. The lgdt instruction loads a flat memory model mapping 4GB of addressable space. By setting the first bit of Control Register 0 (CR0), the CPU switches from 16-bit real mode to 32-bit protected mode. A far jump jmp 0x08: is required to flush the CPU's prefetch queue and set the Code Segment (CS) to 0x08 (defined in the GDT). Output: CPU transforms into 32-bit mode.

7.2. System Initialization: `init.c`

As the first userspace process spawned by the Linux kernel (PID 1), init.c sets up the virtual filesystems and performs cryptographic verification of the arkrt daemon.

Mounting Virtual Filesystems

#include <sys/mount.h>
#include <stdio.h>
#include <unistd.h>

void setup_fs() {
    mount("proc", "/proc", "proc", 0, NULL);
    mount("sysfs", "/sys", "sysfs", 0, NULL);
    mount("devtmpfs", "/dev", "devtmpfs", 0, NULL);
}

Execution & Output: The mount() syscalls interact directly with the VFS (Virtual File System) layer of the Linux kernel.

/proc exposes kernel structures and process states.
/sys exposes hardware tree telemetry (battery, network).
/dev exposes device nodes (/dev/fb0, /dev/urandom). Output: The kernel populates these directories. No text is printed to stdout to maintain the quiet boot sequence.

Cryptographic Signature Verification

#define ARK_KEY "e3b0c44298fc1c149afbf4c899*************************8"

int verify_arkrt() {
    FILE *f = fopen("/sbin/arkrt", "rb");
    if (!f) return -1;
    
    // ... SHA-256 computation over file chunks ...
    char hash_out[65];
    compute_sha256(f, hash_out);
    
    if (strncmp(hash_out, ARK_KEY, 64) == 0) {
        return 1; // Valid
    }
    return 0; // Invalid
}

Execution & Output: The process opens /sbin/arkrt in binary mode. It streams the file through a SHA-256 block hashing function. The resulting hash string is compared directly against ARK_KEY (which is dynamically injected during the build.c compilation phase).

If valid, the function returns 1.
If invalid, init goes into an infinite while(1) { sleep(1); } loop to prevent a kernel panic while blocking system execution. Output: A quiet halt if tampering is detected.

Daemon Fork and Exec

int main() {
    setup_fs();
    if (verify_arkrt()) {
        pid_t pid = fork();
        if (pid == 0) {
            char *args[] = {"/sbin/arkrt", NULL};
            execve(args[0], args, NULL);
        }
    }
    while(1) pause();
    return 0;
}

Execution & Output: fork() duplicates the init process. The child process (pid == 0) uses execve() to replace its memory space entirely with the arkrt executable. The parent init process goes to sleep forever using pause(), acting as a silent reaper for zombie processes. Output: arkrt begins execution as PID 2.

7.3. The Isolated UI Daemon: `ui_daemon`

ui_daemon is executed separately and is entirely responsible for drawing pixels to the screen using double-buffered memory arrays. It is started by arkrt as the primary display compositor.

Framebuffer Memory Mapping

let fd = open("/dev/fb0", O_RDWR)
var vinfo = fb_var_screeninfo()
get_vinfo(fd, &vinfo)
var finfo = fb_fix_screeninfo()
get_finfo(fd, &finfo)

let scrSz = Int(finfo.smem_len)
let fb_ptr = mmap(nil, scrSz, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0)
let fbp = fb_ptr!.bindMemory(to: UInt8.self, capacity: scrSz)

Execution & Output: The UI opens the raw Linux framebuffer (/dev/fb0). It uses ioctl via get_vinfo and get_finfo to query the screen resolution (e.g., 1920x1080) and bytes-per-pixel (usually 4 bytes/32-bit). mmap maps the physical GPU memory directly into the Swift process's RAM. Output: fbp becomes a mutable array where modifying an index directly changes a pixel's color on the physical monitor.

Double Buffering & Anti-Aliased Rendering

let work = UnsafeMutablePointer<UInt8>.allocate(capacity: ABUFSZ)
memset(work, 0, ABUFSZ)

// ... calculate circle positions (ex, ey) ...
diskAA(work, ex, ey, curElR, 255)

blit(work, fbp, sx, sy, lineLen, scrH, fd, &vinfo)
usleep(16666)

Execution & Output: Instead of writing to fbp directly (which causes screen tearing), it allocates a work buffer. It uses memset to clear it to black. The diskAA function iterates over the bounded box of the circle and calculates the Euclidean distance to the center. If the pixel is on the edge, it applies an alpha blend: alpha = 1.0 - (distance - inner_radius) The blit function copies the work buffer to fbp via memcpy. usleep(16666) halts execution for 16.6 milliseconds to enforce a strict 60 FPS framerate. Output: Smooth, tearing-free animations.

Phase 1: Spawn & Orbit Expansion

for frame in 0..<35 {
    let t = Double(frame) / 34.0
    let easeOut = 1.0 - pow(1.0 - t, 3.0)
    let curInnerR = Double(INNER_R) * easeOut
    // ... drawing logic ...
}

Execution & Output: The splash screen uses a cubic ease-out mathematical formula (1.0 - (1.0 - t)^3). As frame goes from 0 to 34, t goes from 0.0 to 1.0. The radius of the orbits expands rapidly at first, then slows down smoothly as it reaches its final INNER_R size. Output: Visual ring expansion.

Phase 3: Spiral Inward & Crash

for frame in 0..<30 {
    let t = Double(frame) / 29.0
    let easeIn = t * t
    let curInner = Double(INNER_R) * (1.0 - easeIn)
    // ... drawing logic ...
}

Execution & Output: Uses a quadratic ease-in formula (t^2). The orbit radius collapses inward slowly at first, then accelerates rapidly until it crashes into the central nucleus NUC_R. Output: Electrons collapse inward.

Unix Domain Socket IPC Query

let ip = queryIPC(cmdId: 102)
let battery = queryIPC(cmdId: 103)
let sysTime = queryIPC(cmdId: 101)

print("  - Interface IP  : \(ip)")

Execution & Output: Once the splash finishes, the UI queries the arkrt daemon. queryIPC opens /dev/arkrt.sock and constructs a 6-byte binary payload (2 bytes command ID, 4 bytes payload length = 0). It sends this to arkrt and waits for a response. arkrt responds with a UTF-8 string payload. The UI extracts this and prints it natively over the framebuffer canvas via VT100 terminal emulation.

7.4. Runtime Telemetry: `KernelBridge.swift`

KernelBridge.swift resides inside arkrt. It handles all hardware-level queries by reading the Linux /sys tree.

Battery Level Polling

func getBattery() -> String {
    let batPath = "/sys/class/power_supply/BAT0/capacity"
    guard let fd = fopen(batPath, "r") else { return "N/A" }
    var buffer = [CChar](repeating: 0, count: 8)
    fgets(&buffer, 8, fd)
    fclose(fd)
    let str = String(cString: buffer).trimmingCharacters(in: .whitespacesAndNewlines)
    return str + "%"
}

Execution & Output: The kernel automatically updates the /sys/class/power_supply/BAT0/capacity file with the hardware battery level integer. The Swift function uses standard C library functions (fopen, fgets) to read up to 8 characters. It trims the trailing newline inserted by the kernel and appends a % sign. Output: e.g., 98%.

IP Address Interrogation

func getIP() -> String {
    var interfaces: UnsafeMutablePointer<ifaddrs>?
    guard getifaddrs(&interfaces) == 0 else { return "UNKNOWN" }
    
    var current = interfaces
    var ipStr = "UNKNOWN"
    
    while let iface = current {
        let name = String(cString: iface.pointee.ifa_name)
        let family = iface.pointee.ifa_addr.pointee.sa_family
        
        if family == UInt8(AF_INET) && name != "lo" {
            var hostname = [CChar](repeating: 0, count: Int(NI_MAXHOST))
            getnameinfo(iface.pointee.ifa_addr, socklen_t(MemoryLayout<sockaddr_in>.size), 
                        &hostname, socklen_t(hostname.count), nil, 0, NI_NUMERICHOST)
            ipStr = String(cString: hostname)
            break
        }
        current = iface.pointee.ifa_next
    }
    freeifaddrs(interfaces)
    return ipStr
}

Execution & Output: The POSIX getifaddrs function populates a linked list of network interfaces. The loop iterates through ifa_next. It filters for IPv4 (AF_INET) and ignores the loopback interface (lo). It then uses getnameinfo to translate the raw binary sockaddr struct into a human-readable IP dotted-decimal string. freeifaddrs is strictly called to prevent memory leaks in the daemon. Output: e.g., 192.168.1.100.

7.5. Build Orchestrator: `build.c`

The tools/build.c file is the master compiler orchestrator, written in C for absolute portability across host build environments.

Incremental Build Logic

if (is_up_to_date(arkrt_out, arkrt_sources, 7)) {
    printf("  \u001b[0;32m✓\u001b[0m arkrt is up-to-date (skipping)\n");
} else {
    char cmd[1024];
    snprintf(cmd, sizeof(cmd), "make -C %s %s/arkrt", base,
             is_rpi4 ? "out_staging/rpi4" : "out_staging");
    run(cmd);
}

Execution & Output: First, build.c guarantees the existence of output directories via mkdir -p. Instead of triggering full builds or delegating blindly to Swift Package Manager, the orchestrator implements a custom is_up_to_date stat-based checking mechanism. It checks the modified times of all core arkrt Swift sources against the existing out_staging/arkrt binary. Output: A clean, incremental build process that drastically reduces sequential build times by only invoking make when strictly necessary.

ISO Generation

system("xorriso -as mkisofs -R -J -b boot/grub/i386-pc/eltorito.img -no-emul-boot "
       "-boot-load-size 4 -boot-info-table -o finished/arkos.iso out_staging/");

Execution & Output: After all binaries (init, arkrt, ui_daemon) are placed in out_staging, xorriso wraps the entire directory into an ISO-9660 filesystem image. It targets eltorito.img to ensure the CD image is natively bootable by a legacy BIOS or UEFI compatibility layer. Output: arkos.iso in the finished/ directory.

7.6. Build Environment Setup & Target Selection

ArkOS uses an Android-style build environment. Before compiling, the developer sources envsetup.sh and selects a target architecture using the type command — mirroring Android's source build/envsetup.sh + lunch workflow.

Environment Setup

cd arkos/
source envsetup.sh    # Loads build functions into shell
type arm64            # Select ARM64 target (Raspberry Pi 4)
type x86_64           # Select x86_64 target (PC / QEMU)
make build            # Build for the selected target

How type works:

Sets TARGET_ARCH, TARGET_TRIPLE, CC, CXX, and sysroot paths as environment variables
All C/C++ compilation uses clang with --target=<triple> (e.g., clang --target=aarch64-linux-gnu)
Swift compilation uses swiftc with the appropriate SDK for each architecture
The ARKOS_TARGET_SET flag signals the Makefile that a target was selected

Make Targets

Target	Description
`make build`	Full build for selected target (reads `TARGET_ARCH` env)
`make build-rpi4`	Shortcut: cross-compile for RPi4 ARM64
`make run`	Launch x86_64 BIOS in QEMU
`make run-uefi`	Launch x86_64 UEFI in QEMU (1920x1080)
`make run-rpi4`	Launch ARM64 RPi4 in QEMU
`make test-uefi`	Test x86_64 UEFI (auto-detects host, uses KVM or TCG)
`make test-bios`	Test x86_64 BIOS (auto-detects host, uses KVM or TCG)
`make test-uefi-arm64`	Test ARM64 UEFI via QEMU
`make test-bios-arm64`	Test ARM64 direct kernel boot via QEMU
`make clean`	Remove all build artifacts

`make build`

build:
	@$(MAKE) --no-print-directory -C $(TOOLS)
ifeq ($(TARGET_ARCH),aarch64)
	@$(TOOLS)/build $(ARKOS) --device rpi4
else
	@$(TOOLS)/build $(ARKOS)
endif

Execution & Output: This target first compiles tools/build.c using clang, then runs the build orchestrator. When TARGET_ARCH=aarch64, it passes --device rpi4 to trigger ARM64 cross-compilation paths.

Cross-Architecture Test Targets

The test-* targets auto-detect the host CPU architecture using uname -m and select the appropriate QEMU acceleration:

Same architecture (e.g., x86_64 host testing x86_64 build): Uses KVM for near-native speed
Cross architecture (e.g., x86_64 host testing ARM64 build): Uses TCG software emulation

This allows developers on any platform to test both architectures.

7.7. UEFI Bootloader: `bootloader.c`

While the Legacy BIOS boot relies on 16-bit assembly (bootloader.asm), the modern UEFI bootloader is written entirely in C (bootloader.c). It leverages the Extensible Firmware Interface (EFI) API to interact directly with the motherboard's firmware in 32-bit or 64-bit protected/long mode right from the start.

Graphics Initialization (GOP) & Initial Display

EFI_GRAPHICS_OUTPUT_PROTOCOL *gop = NULL;
EFI_GUID gop_guid = EFI_GRAPHICS_OUTPUT_PROTOCOL_GUID;
uefi_call_wrapper(SystemTable->BootServices->LocateProtocol, 3, &gop_guid, NULL, (VOID **)&gop);

EFI_GRAPHICS_OUTPUT_BLT_PIXEL black = {0, 0, 0, 0};
uefi_call_wrapper(gop->Blt, 10, gop, &black, EfiBltVideoFill, 0, 0, 0, 0,
                  gop->Mode->Info->HorizontalResolution, gop->Mode->Info->VerticalResolution, 0);

EFI_GRAPHICS_OUTPUT_BLT_PIXEL white = {255, 255, 255, 0};
uefi_call_wrapper(gop->Blt, 10, gop, &white, EfiBltVideoFill, 0, 0,
                  center_x + 97, center_y + 97, 6, 6, 0);

Execution & Output: Unlike Legacy BIOS which uses INT 10h VESA modesetting, UEFI uses BootServices->LocateProtocol to find the EFI_GRAPHICS_OUTPUT_PROTOCOL (GOP). The Blt (Block Image Transfer) function is called via the uefi_call_wrapper macro (necessary for ABI compatibility between GCC and UEFI calling conventions). It first floods the screen with EfiBltVideoFill using black pixels, then calculates the exact center offset and draws a 6x6 pixel solid white dot. Output: A pitch-black screen with a crisp white dot in the exact center.

Filesystem Abstraction & Loading the Kernel

EFI_LOADED_IMAGE *loaded_image = NULL;
uefi_call_wrapper(SystemTable->BootServices->HandleProtocol, 3, ImageHandle, 
                  &LoadedImageProtocol, (VOID **)&loaded_image);

EFI_DEVICE_PATH *kernel_path = FileDevicePath(loaded_image->DeviceHandle, L"\\EFI\\BOOT\\bzImage");
EFI_HANDLE kernel_img = NULL;
uefi_call_wrapper(SystemTable->BootServices->LoadImage, 6, FALSE, ImageHandle, 
                  kernel_path, NULL, 0, &kernel_img);

Execution & Output: In BIOS mode, sectors are blindly read off the disk using INT 13h. In UEFI, the firmware natively understands FAT32 filesystems (the EFI System Partition / ESP). The bootloader queries the LoadedImageProtocol to find out which drive it booted from (loaded_image->DeviceHandle). It constructs a Unicode path \EFI\BOOT\bzImage and asks the motherboard to load the Linux kernel executable into RAM using LoadImage. Output: The kernel is silently staged in memory.

ESP File Reading: `read_file_from_esp` Helper

status = uefi_call_wrapper(SystemTable->BootServices->HandleProtocol, 3, 
                           loaded_image->DeviceHandle, &FileSystemProtocol, (VOID **)&fs);
status = uefi_call_wrapper(fs->OpenVolume, 2, fs, &root);
status = uefi_call_wrapper(root->Open, 5, root, &file, FileName, EFI_FILE_MODE_READ, 0);

Execution & Output: To read arbitrary files (like the animation payload), the bootloader relies on EFI_SIMPLE_FILE_SYSTEM_PROTOCOL. It opens the root volume of the USB drive/disk, and then traverses the filesystem to open \EFI\BOOT\animation.bin. It then dynamically allocates a buffer using BootServices->AllocatePool and reads the raw bytes. Output: A populated memory pointer containing binary file data.

The Boot Animation Loop

EFI_GRAPHICS_OUTPUT_BLT_PIXEL *frames = (EFI_GRAPHICS_OUTPUT_BLT_PIXEL *)anim_buffer;
for (UINTN f = 0; f < num_frames; f++) {
    EFI_GRAPHICS_OUTPUT_BLT_PIXEL *frame = &frames[f * anim_width * anim_height];
    
    uefi_call_wrapper(gop->Blt, 10, gop, frame, EfiBltBufferToVideo, 0, 0,
                      center_x, center_y, anim_width, anim_height,
                      anim_width * sizeof(EFI_GRAPHICS_OUTPUT_BLT_PIXEL));
    
    uefi_call_wrapper(SystemTable->BootServices->Stall, 1, 16666);
}

Execution & Output: The UEFI loader plays the exact same Atom boot animation as the UI, but it must do it before the OS loads. It iterates over the pre-rendered 200x200 pixel arrays in animation.bin. Using EfiBltBufferToVideo, it blasts each frame directly to the GPU framebuffer. BootServices->Stall(16666) halts CPU execution for 16.6 milliseconds (yielding ~60 FPS). Output: Smooth, hardware-accelerated boot sequence animation playing over the white dot.

Kernel Command Line & Execution Handoff

CHAR16 *cmd_line = L"initrd=\\EFI\\BOOT\\initramfs.img console=ttyS0 console=tty0 loglevel=0 logo.nologo init=/init root=/dev/sdb rw quiet vt.global_cursor_default=0";
kernel_loaded_image->LoadOptions = cmd_line;
kernel_loaded_image->LoadOptionsSize = (StrLen(cmd_line) + 1) * sizeof(CHAR16);

uefi_call_wrapper(SystemTable->BootServices->StartImage, 3, kernel_img, &exit_data_size, &exit_data);

Execution & Output: Before starting the kernel, the bootloader injects boot parameters directly into the kernel's UEFI struct (LoadOptions). It sets loglevel=0, quiet, and logo.nologo to guarantee the kernel doesn't spit out terminal text over the beautiful boot animation. Finally, StartImage executes the kernel, causing the UEFI firmware to permanently yield control to Linux. Output: Transition to the Linux Kernel (init.c).

7.8. Graphics Stack: Wayland & LibDRM

The ArkGraphics framework abstracts the complexities of the Wayland protocol and Direct Rendering Manager (LibDRM) subsystem, providing a native Swift environment for UI compositing. Because arkrt is a static binary compiled against musl-libc, custom C wrappers are required to handle dynamic protocol dispatch.

LibFFI Stubbing for Static Compilation

// ffi_stubs.c
void ffi_call(ffi_cif *cif, void (*fn)(void), void *rvalue, void **avalue) {
    // Stub implementation to pacify static linker
}

ffi_status ffi_prep_cif(ffi_cif *cif, ffi_abi abi, unsigned int nargs,
                        ffi_type *rtype, ffi_type **atypes) {
    return FFI_OK; // Stub
}

Execution & Output: Wayland’s libwayland-client historically relies on libffi to dynamically unmarshal function arguments across the IPC socket at runtime. Because ArkOS static-links the entire system stack, integrating a full libffi dependency causes severe symbol conflicts and inflates the binary size. The build system injects ffi_stubs.c into the CWayland module. Output: A successful static link that provides structural API compliance without the heavy dynamic footprint.

Swift Wrapper Exposing Native Modules

// ArkGraphics/Wayland.swift
@_exported import CWayland

public class WaylandDisplay {
    public let displayPtr: OpaquePointer
    
    public init?() {
        guard let ptr = wl_display_connect(nil) else {
            return nil
        }
        self.displayPtr = ptr
    }
}

Execution & Output: The C libraries (CWayland and CLibDRM) are wrapped in thin Swift wrappers. The @_exported import CWayland attribute automatically exposes all underlying C types and functions to downstream dependents of the ArkGraphics framework (such as ark.ui.basic). The wrappers implement RAII (Resource Acquisition Is Initialization) semantics, converting raw OpaquePointer types into memory-safe Swift classes. Output: A memory-safe, composable API for declarative UI rendering.

7.9. Architectural Comparison: Legacy BIOS vs. UEFI Boot Flow

Feature	Legacy BIOS (`bootloader.asm`)	UEFI (`bootloader.c`)
Execution Mode	Boots in 16-bit Real Mode. Must manually configure GDT and perform a Far Jump to enter 32-bit Protected Mode.	Boots directly in 32-bit or 64-bit Protected/Long mode (depending on the motherboard). No GDT hacking required.
Disk I/O	Blindly reads raw disk sectors (LBA) using BIOS `INT 13h` interrupts. Has no concept of files or folders.	Natively understands FAT32 formatting. Uses `EFI_SIMPLE_FILE_SYSTEM_PROTOCOL` to traverse directories and read specific files by string name.
Graphics	Uses standard VESA BIOS Extensions (VBE) via `INT 10h` to request a linear framebuffer mode. Hard to standardize across GPUs.	Uses `EFI_GRAPHICS_OUTPUT_PROTOCOL` (GOP). The firmware handles GPU abstraction, offering seamless drawing APIs like `Blt`.
API Integration	Relies entirely on ancient, opaque BIOS hardware interrupts (e.g., `INT 10h`, `INT 13h`, `INT 15h`).	Uses C structs and function pointers populated by the motherboard's firmware (`SystemTable->BootServices`).
Security	None natively. Vulnerable to bootkit infections manipulating the MBR.	Contains native infrastructure for Secure Boot (cryptographically verifying the kernel binary against embedded motherboard keys).

7.10. ARM64 Device Support: Raspberry Pi 4 Model B

Boot Flow & Hardware Initialization

The Raspberry Pi 4 Model B (Broadcom BCM2711 SoC) does not feature a traditional PC BIOS or UEFI firmware. Instead, hardware initialization is orchestrated directly by the VideoCore VI GPU firmware:

Power-On & GPU Initialization: The VideoCore GPU wakes from internal ROM, reads the EEPROM bootloader, and mounts the FAT32 boot partition of the SD card.
GPU Firmware Execution (start4.elf & fixup4.dat): The GPU loads start4.elf and fixup4.dat from the FAT32 boot partition. These proprietary binaries initialize hardware clocks, SDRAM controllers, power management channels, and VideoCore display pipelines.
Firmware Configuration (config.txt): start4.elf parses boot/rpi4/config.txt. Key directives set include arm_64bit=1 (forces AArch64 mode), enable_gic=1 (enables GICv2 interrupt controller), and kernel=kernel8.img.
Kernel & Device Tree Loading: The GPU loads the ARM64 Linux kernel (kernel8.img), the Device Tree Blob (bcm2711-rpi-4-b.dtb), and initramfs.img into memory.
ARM Core Execution: The GPU releases the 4x Cortex-A72 ARM cores from reset and hands execution directly to the ARM64 Linux kernel at address 0x80000.

Why GPU Firmware Files (`start4.elf`, `fixup4.dat`) are Required

On a Raspberry Pi 4, the ARM64 CPU cannot boot directly from raw flash without the GPU initializing the BCM2711 SoC first. The start4.elf binary serves as the GPU's operating system during early boot. The pack_rpi4.py script automatically stages these binaries into boot/rpi4/firmware/ (fetching them from the official firmware release if not present locally) and embeds them into the FAT32 boot partition of rpi4.img.

Kernel Defconfig Policy (`kernel/arkos_rpi4_defconfig`)

The RPi4 kernel is configured via kernel/arkos_rpi4_defconfig:

Core Facilities (=y): Architecture, CPU scheduling, GIC interrupt controller, BCM2711 SoC drivers, EXT4 filesystem, DEVTMPFS, MMC storage drivers, TTY/PL011 serial, Framebuffer (/dev/fb0), DRM V3D/VC4, and USB HID keyboard/mouse are compiled as built-ins to guarantee immediate boot without initramfs dependency bottlenecks.
Subsystem Modules (=m): Networking, wireless (cfg80211), Bluetooth, ALSA audio, crypto drivers, and secondary filesystems are compiled as loadable kernel modules.

Boot Animation Strategy

Real Hardware (RPi4): Because the RPi4 GPU firmware bypasses our x86 real-mode assembly bootloader, early expanding dot visual transitions are handled by ui_daemon running directly against /dev/fb0 on the Linux kernel framebuffer.
QEMU Emulation: When emulating in QEMU with bootloader binaries, the stage2 assembly bootloader handles early expanding dot rendering prior to kernel execution.

Separate Architecture Sysroot Layout

ArkOS maintains isolated sysroot trees for each target architecture to prevent library or module collisions:

system/
├── sysroot/              # x86_64 system root & kernel modules
└── sysrootaarch64/       # ARM64 (aarch64) system root & kernel modules
    ├── etc/
    ├── lib/modules/
    ├── sbin/
    └── usr/lib/

Partitioning & Image Architecture

The generated rpi4.img utilizes a standard GPT partition table optimized for RPi4 storage:

Partition	File System	Size	Description
Partition 1 (boot)	FAT32	256 MB	Contains `start4.elf`, `fixup4.dat`, `kernel8.img`, `initramfs.img`, `bcm2711-rpi-4-b.dtb`, `config.txt`, and `cmdline.txt`.
Partition 2 (system)	ext4	2.0 GB	Mounted as `/system` containing ArkOS frameworks, binaries (`arkrt`, `ui_daemon`), and libraries.
Partition 3 (vendor)	ext4	100 MB	Mounted as `/vendor` containing DRM modules, keys, and hardware signatures.

Architectural Comparison: x86_64 vs. ARM64 (RPi4)

Component	x86_64 Target	ARM64 Target (RPi4 Model B)
Boot Mechanism	Custom x86 assembly bootloader (`bootloader.asm`) or UEFI loader (`bootloader.c`).	VideoCore VI GPU bootloader (`start4.elf`) loading `config.txt` and `kernel8.img`.
Hardware Config	ACPI tables & DSDT.	Device Tree Blob (`bcm2711-rpi-4-b.dtb`).
Kernel Binary	`kernel/prebuilts/bzImage` (Compressed x86 image).	`kernel/prebuilts/Image` (Raw ARM64 kernel image).
C Cross-Compiler	`clang --target=x86_64-linux-gnu` (x86_64-linux-musl for graphics).	`clang --target=aarch64-linux-gnu`.
Swift Target Triple	`x86_64-swift-linux-musl`.	`aarch64-swift-linux-musl`.
Display Pipeline	VESA / VirtIO GPU (`/dev/fb0`).	VideoCore VC4 DRM / Framebuffer (`/dev/fb0`).
Expanding Dot Animation	Executed in 16-bit VESA assembly stage2 / UEFI GOP.	Executed by `ui_daemon` on `/dev/fb0` framebuffer (detects real hardware via device tree).

System Resource Monitoring

ArkOS provides real-time CPU and memory usage monitoring through the arkrt IPC layer:

CPU Usage (CMD_GET_CPU_USAGE, ID 111): Reads /proc/stat twice with a 100ms interval, computes the delta between idle and total CPU time, and returns a percentage.
Memory Usage (CMD_GET_MEMORY_USAGE, ID 112): Reads /proc/meminfo for MemTotal and MemAvailable, computes used memory, and returns used/totalMB|available=XMB.

arkos_architecture_guide.md 48 KB 永久連結 文件歷史 原始文件