Example Apps

Example Apps

Purpose

This page tracks the QEMU userspace example applications included in the OSAI initramfs. These apps prove the current EL0 C toolchain, syscall ABI, mutable filesystem surface, control-plane access, QEMU-internal network path, SMP task syscall, and CPU-only AI runtime boundary.

Contents

• Status
• Included Apps
• LSTM XOR Benchmark
• Verification
• Limits

Status

The example apps are built as freestanding AArch64 ELF binaries and packaged into the VirtIO read-only initramfs under /bin.

Current QEMU gate status: done for the macOS/QEMU AArch64 target.

Scope note: these are QEMU integration apps. They prove app-callable OS surfaces inside OSAI, not production SSH login, external network interoperability, POSIX pthread compatibility, or a general-purpose machine-learning runtime.

Included Apps

App	Path	Purpose	Status
OSAI shell engine	/bin/osai-shell	Exercises BSD-style file and directory commands: pwd, cd, ls, mkdir, touch, write, cat, mv, rm, and rmdir through filesystem syscalls.	Done in QEMU
Hello	/bin/hello	Demonstrates the freestanding C userspace toolchain and EL0 runtime integration.	Done
Sysinfo	/bin/sysinfo	Prints OSAI/QEMU system identity and requests process, filesystem, network, and telemetry status through osctl.	Done
Systest	/bin/systest	Exercises syscall and mutable filesystem behavior: mkdir, write, read, stat, list, rename, delete.	Done
Smptest	/bin/smptest	Runs an app-requested SMP worker task set through the SMP syscall and checks scheduler state.	Done in QEMU
Nettest	/bin/nettest	Calls app-facing UDP echo and TCP connect/close syscalls against the queue-backed QEMU network stack.	Done in QEMU
LSTM XOR	/bin/lstm-xor	Calls the CPU-AI decode syscall, then runs a CPU-only two-hidden-layer LSTM-style XOR example with train/run timings.	Done in QEMU

LSTM XOR Benchmark

/bin/lstm-xor is intentionally small and deterministic. It uses the current OSAI userspace ABI and CPU-AI decode syscall rather than a hosted libc, GPU runtime, or general ML framework.

The app logs:

• train_ns: monotonic nanoseconds spent in the deterministic training loop.
• run3_avg_ns: average monotonic nanoseconds across three inference batches.
• final_errors: final XOR error count.
• cpu-ai runtime decode=...: proof that the app crossed the OSAI CPU-AI runtime boundary.
• xor solve passed predictions=0,1,1,0: correctness marker.

The benchmark is a QEMU correctness and integration benchmark only. It is not a physical-hardware performance claim.

Verification

Primary gates:

• make qemu-smoke
• make qemu-userspace-suite
• make qemu-process-gate
• make qemu-osctl-gate
• make qemu-filesystem-gate
• make qemu-abi-contract

Expected markers include:

• /bin/osai-shell: commands passed pwd cd ls mkdir touch write cat mv rm rmdir
• /bin/osai-shell: SSH daemon is still pending; this is the shell engine exercised by QEMU
• /bin/hello: C toolchain and EL0 runtime integration passed
• /bin/sysinfo: complete
• /bin/systest: syscall and filesystem suite passed
• /bin/smptest: app-requested SMP worker set passed
• /bin/nettest: app-callable udp/tcp path passed
• /bin/lstm-xor: cpu-ai runtime decode=
• /bin/lstm-xor: xor solve passed predictions=0,1,1,0

Limits

The shell app currently runs a scripted command session in QEMU using the same command engine that an interactive terminal will call. The SSH transport is planned through the existing QEMU host-forwarded network path, but a production SSH daemon, authentication, PTY handling, and interactive terminal session are not complete yet.

/bin/nettest uses app-facing network syscalls and the queue-backed QEMU network stack. It is not yet an external host-to-guest TCP/UDP interoperability test.

/bin/smptest proves an app-requested SMP task set and per-CPU scheduling telemetry. It is not yet POSIX pthreads or arbitrary user-created preemptive threads.

/bin/lstm-xor proves CPU-only AI runtime integration and deterministic app benchmarking. It is not yet a general ML runtime, training framework, or model zoo.