Home /Modules/cpu/CPU-ON-SECONDARY-VM.md

CPU-ON-SECONDARY-VM.md

lib/cpu/CPU-ON-SECONDARY-VM.md · 215 line(s) · markdown

Running a Sleela-sourced CPU on top of the Secondary Sleela VM

This note documents the layer added so that a CPU written in SleeLa can run as a real CPU and as a model for further .sleela inputs, on top of the secondary Sleela VM (lib/vm), which in turn runs on the Native Sleela VM substrate (lib/cpu/SLSleelaVM).

The execution stack

  hardware model      gates -> SLALU -> SLCore -> SLCPU        (lib/cpu)
        |
  Native Sleela VM    SLSleelaVM: the canonical opcode substrate (lib/cpu/SLSleelaVM.sleela)
        |
  Secondary Sleela VM SLVM: heap/frames/threads/classes/loader (lib/vm/SLVM.sleela)
        |
  Sleela-sourced CPU  SLCPURuntime + SL<ARCH>CPU               (lib/cpu/SLCPURuntime.sleela)

Every layer ultimately executes the same canonical opcode stream the native engine interprets, which is what makes the layering 1:1 in Turing effect (SLTuringBridge).

What was missing, and what was added

Secondary VM runtime (lib/vm)

The core object model used to be 13 identical empty stubs. They are now real:

ClassRole
SLVMValuetagged (tag,payload) runtime value
SLVMHeaphandle-based object store over SLRAM (header + field slots, GC marks)
SLVMMemoryflat word/byte-addressable linear memory
SLVMObjecttyped handle for reading/writing an instance
SLVMField / SLVMMethod / SLVMClasstype metadata, field slots, method code windows
SLVMFrameactivation record: locals + operand stack + return ip
SLVMThreadcall stack of frames + run state (for OP_SPAWN/OP_JOINALL)
SLVMModuleid→class table + the shared SLSleelaVM substrate
SLVMModuleLoaderpackage lifecycle: discover → define classes → load
SLVMNativeBindingaudited bridge: parks a VM-exit the host services
SLVMthe interpreter: owns heap/memory/loader/threads and drives the substrate one opcode at a time, routing CALL/RET and service VM-exits

A coder can now design and control a Sleela-sourced VM end to end:

SLVM vm = new SLVM(); vm.configure("app"); vm.boot(65536, 65536);
SLVMModule m = vm.loader().beginModule("app", 4096, 4096, 1024);
m.emit(1, 2);   // OP_CONST 2
m.emit(1, 3);   // OP_CONST 3
m.emit(8, 0);   // OP_ADD
m.emit(27, 0);  // OP_PRINT
m.emit(48, 0);  // OP_HALT
vm.install(m);
vm.run(1000);   // prints 5 via the native substrate

CPU base layer (lib/cpu)

A concrete CPU now only has to declare its registers and implement decode():

class SL6502CPU extends SLCPURuntime {
  void configure() { bringUp("MOS 6502", 8, 16, 5, 65536); }
  void decode(int word) { /* map 6502 opcodes onto readReg/writeReg/aluOp/... */ }
}

Resource assignment and multi-language workloads

Every CPU can now run a workload written in C, C++, or Sleela within an explicit resource grant, via two classes and one inherited method:

Because the register-ISA image is language-independent, the same workload runs identically whether its source was C, C++, or Sleela — the 1:1 Turing-effect guarantee. Example:

SLCPUResource grant = new SLCPUResource();
grant.configure(4096, 100000, grant.PRIORITY_NORMAL);   // 4K words, 100k-instr slice

SLWorkload job = new SLWorkload();
job.configure("hello", "examples/hello.c", job.LANG_C, grant);

SL6502CPU cpu = new SL6502CPU(); cpu.configure();
int out = cpu.runWorkload(job);     // compiles C -> maps onto substrate -> runs in grant

Admission is enforced: a workload whose memory request exceeds the CPU's address space, or whose budget is non-positive, is rejected (runWorkload returns -1).

The full nested stack: Creator → SLVM → Sleela CPU → program

runWorkload() above runs a CPU on its own substrate. The full product stack nests the CPU inside the Secondary Sleela VM, built by the VM Creator Edition:

SleelaVMCreator (lib/vm/creator)
  → builds + boots a live SLVM (lib/vm, the Secondary Sleela VM)
      → which runs on the Native Sleela VM substrate (lib/cpu/SLSleelaVM)
          → hosts a Sleela CPU model (SLCPURuntime / SL<ARCH>CPU) as executor
              → runs a C / C++ / Java / Sleela program through that CPU

This is now wired in code (previously it existed only in this document). The bridge is a substrate-injection seam:

One-call usage through the creator:

SLCPUResource grant = new SLCPUResource(); grant.configure(4096, 100000, grant.PRIORITY_NORMAL);
SL6502CPU cpu = new SL6502CPU(); cpu.configure();
SLWorkload job = new SLWorkload(); job.configure("app", "examples/hello.c", job.LANG_C, grant);

SleelaVMCreator creator = new SleelaVMCreator(); creator.configure();
int out = creator.run(5, cpu, job, 1000000);   // generation 5 "Manager"

The two feasibility stackings in PERFECT.CONSEQUENCE.md correspond exactly to whether the CPU uses its own substrate (direct) or an SLVM-injected one (nested); the nested column is this hostCpu path.

CPU fleet status — all 99 folders runnable

Every architecture folder now carries a runnable SL<ARCH>CPU that extends SLCPURuntime, declares a real register file, and implements decode():

Each generated model uses a compact, arch-flavored instruction encoding (load/move/arithmetic/compare/branch/halt) routed through the inherited SLALU and memory. The per-arch bus/timing/register detail continues to live in each folder's nine markdown docs; tools/generate-cpu-models.py is the source of truth for the generated set and can be re-run or extended with richer decoders.

Optional acceleration: direct DMA and native GPU access

Two opt-in capabilities span the whole stack (native VM → Secondary VM → CPU → program). Both default off and are turned on only when a program needs them.

They are exposed as options at every layer, and flow down when enabled:

LayerEnableAccess
CPU (SLCPURuntime)enableDMA() / enableGPU()dmaEngine() / gpuDevice(), dmaCopy(...)
Secondary VM (SLVM)enableDMA() / enableGPU() (before hostCpu)hosted CPU inherits them; dmaEngine()/gpuDevice()
Creator (SleelaVMCreator)requestDMA() / requestGPU()applied to the built VM and its hosted CPU
Build (SLExecutorBuild)enableDMA() / enableGPU()on the build's CPU
Options model (SleelaVMFeatureBits)DMA / GPU capability bitsfeature-mask gating

Example (Creator grants both; the program uses them):

SleelaVMCreator creator = new SleelaVMCreator(); creator.configure();
creator.requestDMA(); creator.requestGPU();
creator.selectGeneration(5); creator.create(); creator.installExecutor(cpu);

cpu.dmaEngine().memcpy(0, 100, 4);     // direct block move, no CPU loop
SLGPUDevice gpu = cpu.gpuDevice();     // offload a compute kernel
gpu.emitKernel(1, 2); gpu.emitKernel(1, 3); gpu.emitKernel(8, 0); gpu.emitKernel(27, 0); gpu.emitKernel(48, 0);
int out = gpu.dispatch(gpu.totalLanes(), 100);

See examples/dma-and-gpu-options.sleela. Because they are plain options, a program that never needs them pays nothing; one that needs DMA or the GPU at any point simply enables it.