lib/cpu — Execution Model, Multi-Language Loading, and the Linux Guest
This document answers three questions precisely and honestly:
- Can this CPU actually run a program?
- How do C, C++, Java, and Sleela programs get loaded and run?
- How does a Linux-style VM run on top of the Sleela CPU — and what is real vs. modeled?
1. Can it run a program? — Yes, within the model
SLControlUnit.step() is a genuine fetch-decode-execute cycle over the
SLInstructionSet: it fetches a word from SLRAM at the program counter,
decodes it (SLInstructionDecoder), executes it through the register file
(SLRegisterFile), ALU (SLALU), and hardware stack (SLStack), updates the
program counter (sequential / branch / call / return), and sets the status
flags. The kernel services SYS_WRITE / SYS_EXIT.
The ISA now includes a real call/stack protocol — CALL pushes the return
address and jumps, RET pops and returns, PUSH/POP move words — plus full
integer arithmetic (MUL/DIV/MOD/NEG), bitwise/shift ops, three
addressing modes (LOAD/LOADR/LOADX and the STORE family), five branch
forms, and SYSCALL/TRAP. That is enough to be a lowering target for
compiled code with functions, locals, and spills.
Verification status. The pipeline's semantics were validated by an
independent simulation of frontend → IR → lowering → execution: the Sleela demo
lowers 2 + 3, executes it, and writes 5. The classes could not be run
through the real sleela compiler in this environment (its build gate requires
a SHA-256 manifest + network), so "runs" means verified by construction and
simulation, not executed on the native VM. Building the compiler is the
prerequisite to running any of this for real.
Boundary: this is a CPU/OS simulator expressed as SLeeLa classes, not code executing on bare metal. It is an object-oriented model of hardware.
2. Multi-language loading — one driver, one IR, one backend
The ISA accepts C, C++, Java, and Sleela the way real toolchains do: each language has a frontend that lowers it to a common intermediate representation (SLIR); a single shared backend compiles the IR to machine code. The ISA is multi-language because the backend is shared — exactly the clang/clang++/LLVM and javac/bytecode pattern.
source.c -> SLFrontendC \
source.cpp -> SLFrontendCpp \ SLLowering SLProgramLoader
source.java -> SLFrontendJava >--- SLIR ---> (IR -> ISA) ---> load into RAM --> process
source.sleela-> SLFrontendSleela/ ^ |
| SLKernel schedules + runs
SLCompilerDriver picks the frontend by language
| Class | Role |
|---|---|
SLIRInstruction | One language-neutral three-address IR op (const/move/arith/cmp/branch/load/store/param/call/ret/syscall/halt). |
SLIR | An ordered IR module with temp and label allocators. |
SLFrontend | Base frontend: parse() + lower() -> SLIR. |
SLFrontendSleela | SLeeLa frontend (reference; modeled end to end). |
SLFrontendC | C → IR lowering (declarations→slots, expressions→temps, calls→param/call, return→ret). |
SLFrontendCpp | C++ → IR (this-pointer, construction, virtual dispatch), extends the C frontend. |
SLFrontendJava | JVM-bytecode → IR (locals→temps, operand stack linearized, invoke→call). |
SLLowering | Shared backend: IR → SLProgram with register allocation + 2-pass label resolution. |
SLCompilerDriver | Selects the frontend by language/extension and runs frontend→IR→backend. |
Loading, by language
SLProgramLoader loader = ...; // from SLMachine.boot()
loader.attachCompiler(isa);
// infer language from extension, compile, load, and spawn:
loader.loadFile("hello.c", "hello", 8192); // C
loader.loadFile("hello.cpp", "hello", 8192); // C++
loader.loadFile("Hello.java", "hello", 8192); // Java (from bytecode)
loader.loadFile("hello.sleela","hello", 8192); // Sleela
Or explicitly: loader.loadSource(path, langId, name, addr) with langId
0=Sleela, 1=C, 2=C++, 3=Java.
Honest scope of the frontends
- The Sleela frontend is modeled end to end and its demo lowers and executes correctly (verified by simulation).
- The C, C++, and Java frontends implement the real lowering contracts
and each demonstrates one complete, correct lowering, but their
parse()is not a full parser for the language. Turning each into a complete compiler means growingparse()into a real C parser / C++ parser / classfile reader — the IR and backend beneath them do not change. That separation is the whole point: the hard, language-specific work is isolated in the frontend.
This is also consistent with the rest of the repository, where the production
multi-language path is Nordshrift (nordshrift build --target=java|sleela|c
transpiles .sleela and the native VM runs it). lib/cpu is a self-contained
teaching model of the same frontend/IR/backend idea.
3. The Linux-style guest VM — architectural model
The "run a Linux-based VM on top of the Sleela CPU" layer is a type-2 hosted hypervisor model:
SLCPU (hardware) -> SleelaOS (host kernel) -> SLHypervisor
-> SLGuestVM (virtual CPU + guest-physical memory window)
-> SLGuestLinux (guest kernel: boot protocol + Linux syscall ABI)
-> guest user programs
| Class | Role |
|---|---|
SLHypervisor | Creates/schedules guests; installs the TRAP vector as the VM-exit path; counts exits. |
SLGuestVM | One guest: a vCPU over a host-memory window, guest-physical→host translation, VM-exit counting. |
SLGuestLinux | A Linux-style guest kernel: boot protocol (kernel+initrd image, entry), a Linux-like syscall ABI (read/write/open/close/mmap/exit/fork/execve), emulated as host syscalls on VM-exit. |
Run it:
SLMachine m = new SLMachine();
m.buildHardware("SleelaWorks","SL-Core-X", 4, 32, 3200);
m.boot();
m.runLinuxGuest(0, 64); // boot a Linux-style guest and run 64 guest instructions
Boundary — read this.
SLGuestLinuxis an architectural model of running a Linux-like guest: it defines the boot sequence, the guest syscall numbers, guest-physical memory translation, and the VM-exit/emulation path. It is not the upstream Linux kernel and does not boot a realbzImage. Doing that would require a hardware-virtualization-grade vCPU (VT-x/AMD-V semantics), a device model (virtio, interrupt controller, timers, MMU with real page tables), and a loader for real ELF/kernel images — each a large project. What this provides is a faithful, composable model of the full layering so the "Linux on the Sleela CPU" story is expressed in SLeeLa classes with every seam named.
4. The Sleela opcode substrate — one Turing-complete ground truth
The deepest layer unifies everything. The SLeeLa VM opcodes are Turing
complete and are the instructions the native core already executes
(impl/core/sleela_core.c, lib/vm/InstructionSet.sleela). So the CPU model
does not invent a parallel reality: the register-style ISA and the OS system
calls are mapped onto those canonical opcodes, and every language reduces to
the same opcode stream.
C / C++ / Java / Sleela
-> SLFrontend* language -> common IR (SLIR)
-> SLLowering IR -> register ISA (SLInstructionSet / SLProgram)
-> SLOpcodeMap register ISA + OS syscalls -> SLeeLa opcodes
-> SLSleelaVM execute the canonical Turing-complete opcode substrate
The native substrate (impl/core/sleela_core.h SLOp) defines 156 opcodes
(codes 0..155), which SLSleelaOpcode organizes as a double shelf of three
contiguous tiers — all acceptable, each carrying its own iteration flag for the
professional monitoring/storage layer:
| Shelf | Codes | Tier flag | Contents |
|---|---|---|---|
| 1 — base computational/service core | 0..48 | TIER_BASE | arithmetic, control flow, call/return, threads, sockets, pipes, files |
| 2 — substrate extensions | 49..97 | TIER_SUBSTRATE | time services, structs, Synchro / Munction / Best-of |
| 3 — host-facing services | 98..155 | TIER_HOST | arrays, OS syscalls, GC hint, ran::, Idea realtime canvas, VM-select / Modium, UI bridge, structural send, type checks, stack duplication, OSLS typed native binding |
SLSleelaOpcode exposes the shelf bounds (BASE_COUNT 49, SUBSTRATE_COUNT
98, NATIVE_COUNT 156) and tier(op) / tierName(op) so each opcode can be
tagged and each shelf iterated under its own flag; the tiers never gate
execution. Every CPU instruction and OS syscall lowers onto the base
computational core (plus structs); the mapping is conservative — it mirrors
the native codes/mnemonics exactly rather than inventing a parallel set.
| Class | Role |
|---|---|
SLSleelaOpcode | The canonical opcode registry — exact native codes/mnemonics (declares the base computational/service core). The ground truth. |
SLSleelaVM | A stack machine that executes the Sleela opcodes directly (mirrors the native dispatch loop). |
SLOpcodeMap | Maps each register-ISA instruction and each OS syscall onto a sequence of Sleela opcodes. |
SLTuringBridge | Reduces any-language programs to the substrate and runs them; proveEquivalence() checks all four give the identical result. |
Why this makes C == C++ == Java == Sleela (1:1 in Turing effect)
A register instruction like ADD r1, r2 maps to the opcode sequence
LOADG r1 ; LOADG r2 ; OP_ADD ; STOREG r1 (registers live in global slots). An
OS SYS_WRITE maps to LOADG arg ; OP_PRINT; SYS_EXIT maps to OP_HALT.
Because every CPU instruction and every syscall is defined as such a
Sleela-opcode sequence, a whole program — whatever language it started in —
becomes one stream of canonical opcodes. Two programs that reduce to opcode
streams with the same observable effect are, by definition, equal in Turing
effect.
SLTuringBridge.proveEquivalence(c, cpp, java, sleela) makes this operational:
it lowers the same computation from all four frontends, reduces each to the
Sleela substrate, runs each on SLSleelaVM, and returns true only if every
language produced the identical result.
Verification. An independent simulation of the entire chain (frontend → IR → register ISA →
SLOpcodeMap→SLSleelaVM) confirms that the C, C++, Java, and Sleela canonical programs each reduce to the identical 14-opcode Sleela stream and all print5. The equivalence claim is therefore operational, not asserted. (As elsewhere, this is verified by construction and simulation; running on the native VM awaits a buildablesleelacompiler.)Note the frontends deliberately lower the same computation so the proof is honest — equivalence means "same effect for the same program expressed in different languages," not that any two different programs are equal.
5. Runs by both — the basis of function every CPU model inherits
A CPU model is not defined solely by an execution path; part of its basis of
function is that it runs code two ways, equivalently. Both are inherited
from SLCPURuntime, so every SL<ARCH>CPU has them by extension — no model
re-implements the capability:
- By opcodes —
runByOpcodes(int[] program, [int at,] int budget)loads a native instruction-word program and drives it through the model's own fetch-decode-execute loop (fetch/decode/step/run). This is the model running its own ISA directly. The result is left in architecture-defined state, read via the overridableopcodeObservable()(the base reads register 0; e.g.SL6502CPUoverrides it to return the accumulator).
- By function-call equivalence —
runByEquivalence(SLWorkload work)runs the code of an assumed other process (any supported language/ISA workload) by reducing it, through the sharedSLOpcodeMap, to the equivalent canonical opcode / service-call stream on this CPU's substrate (therunWorkloadpipeline of §2 and §4). Here the model runs code written for another process by mapping its operations to equivalent function calls/opcodes.
Because both paths funnel to the one canonical SLSleelaVM engine (§4), "runs by
both" is not two realities but one basis observed two ways. The runtime makes
that an assertable property:
boolean basisHolds(int[] opcodeProgram, int opcodeBudget,
SLWorkload equivalentWork, int expected)
It runs the same computation by opcodes and by equivalence and returns true only
when both produce the agreed expected result. This is the opcode-vs-
equivalence analogue of SLTuringBridge.proveEquivalence (§4), but on a single
CPU: the opcode form and the assumed-other-process form of the same computation
must coincide. runsByBoth() advertises the capability (always true for an
SLCPURuntime-derived model).
The two paths observe different surfaces — a register (opcode path) vs. a printed value (equivalence path) — so
basisHoldstakes the intended result explicitly and checks both equal it, rather than assuming the two mechanisms write the same physical slot. Equivalence means "both compute the intended result," honestly stated.
What would make each piece "real" (roadmap)
| Goal | Needed |
|---|---|
| Execute any of this for real | A buildable sleela compiler (the current blocker). |
| Full C / C++ / Java frontends | Real parse() implementations (C parser; C++ parser; JVM classfile reader) — IR/backend unchanged. |
| Real binaries | ELF loader and JVM classfile loader for on-disk program images. |
| Larger programs | Register spilling to the stack (PUSH/POP paths are present), heap allocator, calling-convention finalization. |
| Boot real Linux | Hardware-virtualization vCPU, MMU + page tables, device model (virtio/APIC/timers), real kernel-image loader. |
OS-VM hardening progress
The guest layer is being hardened from "model" toward "genuinely executes":
- Step 1 (done):
SLGuestVMruns the guest on an embeddedSLSleelaVM— guest code is dispatched as canonical opcodes, not counted. - Step 2 (done):
SLMMUgives the guest real single-level page tables with present/write/exec permissions and page faults (unmapped + protection);SLHypervisoridentity-maps each guest's window at creation. - Step 3 (done): a guest device model —
SLGuestTimer(interval timer + IRQ),SLGuestConsole,SLGuestBlockDevice(virtio-blk over a host drive), routed bySLGuestDeviceBuswith IRQ aggregation into the guest interrupt controller. - Step 4 (done): a genuinely-compiled guest kernel.
SLGuestKernelBuildercompiles kernel source (any supported language) throughSLCompilerDriver→ register ISA →SLOpcodeMap→ aSLGuestKernelImageof canonical opcodes, which the guest substrate loads and executes.SLGuestLinux.buildKernel()/SLMachine.runLinuxGuestFromSource()boot it. This is a small custom kernel, not upstream Linux.
- Step 5 (done): the VM-exit loop is wired. In hosted mode
SLSleelaVMparks a VM-exit on a service opcode (e.g.OP_PRINT);SLGuestVM.run()routes it (console device / syscall emulation), ticks devices, posts IRQs, and resumes — the device↔substrate↔exit handoff is functional, not just structural. - Step 6 (done): the guest has preemptive multitasking.
- Step 13 (done): process creation —
fork/execve/wait. The guest syscall ABI (SLGuestSyscall) now implements the fork/exec/wait family:fork()clones the running task into a fresh TCB that resumes at the parent's instruction pointer (parent sees the child pid, child a 0-return by convention);execve()replaces a task's image in place with a freshly compiled program through init's shared toolchain and repoints its resume IP;exit(status)leaves a reaped-on-wait()zombie carrying its status;wait()reaps a finished child and yields its tid + status (returning a would-block code while children are still live).SLGuestTaskgrew the process-tree bookkeeping (parent tid, exit status, zombie/reaped flags),SLGuestSchedulergrewfork()/reapChild()/hasLiveChild()/slotOfTid(), andSLGuestVM.handleExit()routes the canonicalOP_SPAWN(fork/execve) andOP_JOINALL(wait) service opcodes to the new syscalls.SLGuestLinux.emulateSyscall()now mapsLINUX_FORKto the hostSYS_SPAWNprimitive and classifiesLINUX_EXECVE/LINUX_WAITas in-guest-emulated. TwoSLMachinedemos drive the cycle:runLinuxGuestForkExec()goes through the syscall ABI (boot → init → fork → execve → childexit→wait), andrunLinuxGuestForkExecOpcodes()goes through the canonical service opcodes —OP_SPAWN(fork) andOP_JOINALL(wait) routed bySLGuestVM.serviceOpcode()exactly as a guest program's VM-exits are — so the opcode→syscall mapping is exercised, not just the handlers. A reaped child's scheduler slot is reclaimed (SLGuestScheduler.admit()recycles reaped-and-DONE slots), so repeated fork/wait cycles don't exhaust the task table, and all guest pids come from one allocator (SLGuestInit.allocPid()) shared by init-spawned programs and fork'd children. This turns the guest's flat set of threads into a real Unix-style process tree with parents reaping children. - Step 12 (done): on-disk programs.
SLGuestExecutableis a miniature executable format (magic header + opcode section); programs serialize to it, persist to the guest filesystem, and load back from disk into the substrate (header-validated) - programs now come from storage, not only inline compilation. - Step 11 (done): guest shell.
SLGuestShellis a minimal command interpreter (help/echo/ls/cat/ps/exit) spawned by init as its first child, issuing commands through the syscall ABI - the guest's first interactive user program. - Step 10 (done): guest IPC.
SLGuestPipe(byte FIFO between tasks) andSLGuestSignal(async signals; SIGKILL/SIGTERM terminate) wired into the syscall ABI (pipe/kill + pipe-fd read/write) and delivered at scheduling points. - Step 9 (done): guest syscall ABI.
SLGuestSyscalldispatches write/read/open/close/brk/yield/getpid/exit;SLGuestVM.handleExit()routes guest service-opcode VM-exits through it against the console/filesystem/scheduler and pushes the result back - the full user->kernel boundary. - Step 8 (done): guest filesystem.
SLGuestFileSystemprovides a flat directory of files + an fd table with sequential read/write over the guest block device, mounted by the kernel and backing the file syscalls. - Step 7 (done): guest user space.
SLGuestProgramis a loadable user program compiled from source through the shared toolchain;SLGuestInit(PID 1) loads programs into the guest substrate and admits them as scheduler tasks — the guest runs real user processes, not just kernel code.SLGuestTask+SLGuestSchedulerrun inside the guest; theSLGuestTimerIRQ is the preemption source — each expiry drivesonTimerInterrupt(), which saves the running task's substrate IP, round-robins to the next ready task, and resumes the substrate at that task's saved IP.
With steps 1–13 complete, the guest is no longer a counter-ticking stub: it
executes a compiled kernel image as canonical opcodes on SLSleelaVM, over
paged, protected memory (SLMMU), with a timer/console/block device
model, a wired VM-exit loop routing service opcodes to devices, and a
timer-driven preemptive scheduler multitasking guest tasks. On top of that
it runs real user space (SLGuestInit as PID 1), with a filesystem, a
syscall ABI, IPC (pipes + signals), an interactive shell, on-disk
executables, and now Unix-style process creation — fork/execve/wait
over a real parent/child process tree. The remaining gap to booting real Linux
is unchanged and large — hardware-virtualization-grade vCPU semantics, a full
virtio/APIC/ACPI device model, real page-table formats, and an ELF/bzImage
loader — and is deliberately out of scope for this teaching model.