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

```mermaid
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](file:///home/arkos/repo/arkos/boot/source/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](file:///home/arkos/repo/arkos/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](file:///home/arkos/repo/tools/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/](file:///home/arkos/repo/arkos/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)                  |
|                               ...                             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
```

1. **Command ID** (`UInt16`): The numeric code representing the system call command (sent big-endian).
2. **Payload Length** (`UInt32`): The size of the payload following the header in bytes (sent big-endian).
3. **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
```nasm
[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)
```nasm
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
```nasm
    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
```c
#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
```c
#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
```c
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
```swift
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
```swift
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
```swift
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
```swift
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
```swift
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
```swift
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
```swift
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
```c
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
```c
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
```bash
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`
```makefile
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
```c
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
```c
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
```c
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
```c
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
```c
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
```c
// 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
```swift
// 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:

1. **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.
2. **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.
3. **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`.
4. **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.
5. **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`.