Home /Modules/cpu/EXECUTION.md

EXECUTION.md

lib/cpu/EXECUTION.md · 299 line(s) · markdown

lib/cpu — Execution Model, Multi-Language Loading, and the Linux Guest

This document answers three questions precisely and honestly:

  1. Can this CPU actually run a program?
  2. How do C, C++, Java, and Sleela programs get loaded and run?
  3. 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
ClassRole
SLIRInstructionOne language-neutral three-address IR op (const/move/arith/cmp/branch/load/store/param/call/ret/syscall/halt).
SLIRAn ordered IR module with temp and label allocators.
SLFrontendBase frontend: parse() + lower() -> SLIR.
SLFrontendSleelaSLeeLa frontend (reference; modeled end to end).
SLFrontendCC → IR lowering (declarations→slots, expressions→temps, calls→param/call, return→ret).
SLFrontendCppC++ → IR (this-pointer, construction, virtual dispatch), extends the C frontend.
SLFrontendJavaJVM-bytecode → IR (locals→temps, operand stack linearized, invoke→call).
SLLoweringShared backend: IR → SLProgram with register allocation + 2-pass label resolution.
SLCompilerDriverSelects 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

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
ClassRole
SLHypervisorCreates/schedules guests; installs the TRAP vector as the VM-exit path; counts exits.
SLGuestVMOne guest: a vCPU over a host-memory window, guest-physical→host translation, VM-exit counting.
SLGuestLinuxA 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. SLGuestLinux is 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 real bzImage. 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:

ShelfCodesTier flagContents
1 — base computational/service core0..48TIER_BASEarithmetic, control flow, call/return, threads, sockets, pipes, files
2 — substrate extensions49..97TIER_SUBSTRATEtime services, structs, Synchro / Munction / Best-of
3 — host-facing services98..155TIER_HOSTarrays, 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.

ClassRole
SLSleelaOpcodeThe canonical opcode registry — exact native codes/mnemonics (declares the base computational/service core). The ground truth.
SLSleelaVMA stack machine that executes the Sleela opcodes directly (mirrors the native dispatch loop).
SLOpcodeMapMaps each register-ISA instruction and each OS syscall onto a sequence of Sleela opcodes.
SLTuringBridgeReduces 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 print 5. The equivalence claim is therefore operational, not asserted. (As elsewhere, this is verified by construction and simulation; running on the native VM awaits a buildable sleela compiler.)

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:

  1. 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 overridable opcodeObservable() (the base reads register 0; e.g. SL6502CPU overrides it to return the accumulator).
  1. 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 shared SLOpcodeMap, to the equivalent canonical opcode / service-call stream on this CPU's substrate (the runWorkload pipeline 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 basisHolds takes 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)

GoalNeeded
Execute any of this for realA buildable sleela compiler (the current blocker).
Full C / C++ / Java frontendsReal parse() implementations (C parser; C++ parser; JVM classfile reader) — IR/backend unchanged.
Real binariesELF loader and JVM classfile loader for on-disk program images.
Larger programsRegister spilling to the stack (PUSH/POP paths are present), heap allocator, calling-convention finalization.
Boot real LinuxHardware-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":

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.