<< lib/vm/SLVM.sleela SLeeLa Standard Library Definition. Definition: Defines SLVM — the secondary Sleela VM: the runnable interpreter a coder uses to design and control a Sleela-sourced virtual machine. It owns the managed object heap (SLVMHeap), the flat linear memory (SLVMMemory), the module loader (SLVMModuleLoader), a main thread with a frame-based call stack (SLVMThread/SLVMFrame), and a native-binding table (SLVMNativeBinding). SLVM does not re-implement opcode semantics — it drives the module's canonical SLSleelaVM substrate (the native Sleela VM, lib/cpu/SLSleelaVM) one opcode at a time, intercepting CALL/RET to maintain frames and service opcodes to route through native bindings. Running on top of that substrate is exactly what makes this the "secondary VM on top of the Native Sleela VM": every effect ultimately executes on the same 156-opcode engine (codes 0..155) the native layer interprets. Typical use (opcode module): vm = new SLVM(); vm.boot(1<<16, 1<<16); module = vm.loader().beginModule("app", 4096, 4096, 1024); ... emit opcodes / define classes ... vm.install(module); vm.run(1000000); Guest-CPU use (Creator -> SLVM -> CPU -> program): SLVM can also host a Sleela CPU model (any SLCPURuntime / SLCPU) as its executor and run a C / C++ / Java / Sleela program through it, nested on this VM's substrate: vm = new SLVM(); vm.configure("edition"); vm.boot(1<<16, 1<<16); SL6502CPU cpu = new SL6502CPU(); cpu.configure(); vm.hostCpu(cpu); < job wraps a .c/.cpp/.java/.sleela source > int out = vm.runGuestWorkload(job, 1000000); (SleelaVMCreator builds and boots the SLVM for this flow.) Family: vm. Composes SLVMHeap, SLVMMemory, SLVMModuleLoader, SLVMThread, SLVMFrame, SLVMValue, SLVMNativeBinding, SLSleelaVM; hosts SLCPURuntime. >> #sleela 2.5 material; class SLVM { < ---- Descriptive metadata (version 1.11 nested-friendly accessors) ---- > << Eleven catalogued attributes with getter/setter pairs, so a GUI, loader, or catalog can read and (where appropriate) override this record. Values are faithful to the subject's real origin where publicly known. >> String metaVersion = "1.0.0"; int metaId = 925; String metaAuthor = "Max Rupplin vs. Dr. Mrs. Elisabeth Harkins"; String metaDate = "2026-10-16"; String metaCopyright = "SLeeLa project"; String metaTrademark = "none"; String metaCorporation = "none"; < metaOrigin: National | | International | Galactic > String metaOrigin = "International"; String metaBirthDate = "2026-09-28"; < metaScienceRating: maturity/robustness on a 1..10 scale > int metaScienceRating = 9; < metaNationalSchedule: a real, citable instrument or "none" > String metaNationalSchedule = "none"; String getMetaVersion() { return metaVersion; } void setMetaVersion(String v) { metaVersion = v; } int getMetaId() { return metaId; } void setMetaId(int v) { metaId = v; } String getAuthor() { return metaAuthor; } void setAuthor(String v) { metaAuthor = v; } String getDate() { return metaDate; } void setDate(String v) { metaDate = v; } String getCopyright() { return metaCopyright; } void setCopyright(String v) { metaCopyright = v; } String getTrademark() { return metaTrademark; } void setTrademark(String v) { metaTrademark = v; } String getCorporation() { return metaCorporation; } void setCorporation(String v) { metaCorporation = v; } String getOrigin() { return metaOrigin; } void setOrigin(String v) { metaOrigin = v; } String getBirthDate() { return metaBirthDate; } void setBirthDate(String v) { metaBirthDate = v; } int getScienceRating() { return metaScienceRating; } void setScienceRating(int v) { metaScienceRating = v; } String getNationalSchedule() { return metaNationalSchedule; } void setNationalSchedule(String v) { metaNationalSchedule = v; } String name; < 0 off, 1 booted, 2 running, 3 halted > int state; SLVMHeap heap; SLVMMemory memory; SLVMModuleLoader moduleLoader; < the currently installed module > SLVMModule module; < == module.engine(); the native-opcode engine we drive > SLSleelaVM substrate; SLVMThread main; < Bounded native-binding table (SLeeLa surface has no arrays). > int bindingCount; SLVMNativeBinding b0; SLVMNativeBinding b1; SLVMNativeBinding b2; SLVMNativeBinding b3; < opcodes executed through this VM > int steps; < last serviced VM-exit opcode (-1 if none) > int lastExit; < --- guest-CPU hosting (Creator -> SLVM -> CPU -> program stack) --- > < When SLVM hosts a Sleela CPU model as its executor, the CPU is pinned here > < and SLVM lends it the substrate so the CPU's lowered program runs nested on > < the Secondary VM rather than on a private engine. > SLCPURuntime guestCpu; < last observable output of a guest workload > int guestResult; < --- optional capabilities propagated to a hosted guest CPU --- > < When set before hostCpu(), the guest CPU is granted direct DMA and/or native > < GPU access, so a program running under this VM can use them at any point. > int dmaOption; int gpuOption; < --- native-RAM option --- > < When set before boot(), the VM's linear memory runs on REAL host RAM > < (SLNativeMemory) instead of the simulated SLRAM store, for running outside > < simulation for procedural layment. Off (simulated) by default. > int nativeRamOption; void configure(String vmName) { name = vmName; state = 0; } < Native-RAM option: when set before boot(), the VM's linear memory runs on > < REAL host RAM (SLNativeMemory) instead of the simulated SLRAM store — for > < running outside simulation for procedural layment. Off by default. > void useNativeRam() { nativeRamOption = 1; } void useSimulatedRam(){ nativeRamOption = 0; } boolean nativeRam() { return nativeRamOption == 1; } < Boot: build the heap, linear memory, loader and main thread. The linear > < memory honors the native-RAM option. > void boot(int heapWords, int memoryWords) { heap = new SLVMHeap(); heap.configure(heapWords); memory = new SLVMMemory(); if (nativeRamOption == 1) { memory.configureNative(memoryWords); } else { memory.configure(memoryWords); } moduleLoader = new SLVMModuleLoader(); moduleLoader.configure("lib/vm"); main = new SLVMThread(); main.configure(0, "main"); bindingCount = 0; steps = 0; lastExit = -1; state = 1; } < Convenience: boot directly onto native host RAM. > void bootNative(int heapWords, int memoryWords) { nativeRamOption = 1; boot(heapWords, memoryWords); } SLVMModuleLoader loader() { return moduleLoader; } < Register a native binding (e.g. print). Up to 4 in this bounded surface. > void bindNative(SLVMNativeBinding binding) { binding.resolve(); if (bindingCount == 0) { b0 = binding; } else if (bindingCount == 1) { b1 = binding; } else if (bindingCount == 2) { b2 = binding; } else if (bindingCount == 3) { b3 = binding; } if (bindingCount < 4) { bindingCount = bindingCount + 1; } } SLVMNativeBinding bindingFor(int opcode) { if (bindingCount > 0 && b0.opcode() == opcode) { return b0; } if (bindingCount > 1 && b1.opcode() == opcode) { return b1; } if (bindingCount > 2 && b2.opcode() == opcode) { return b2; } if (bindingCount > 3 && b3.opcode() == opcode) { return b3; } return null; } < Install a loaded module and prime its entry method as the first frame. > void install(SLVMModule m) { module = m; substrate = m.engine(); < service opcodes become VM-exits we route > substrate.setHosted(); SLVMMethod entry = m.resolveMethod(m.entryClass(), m.entryName()); if (entry != null) { SLVMFrame frame = new SLVMFrame(); frame.configure(entry, -1, m.entryClass(), 256); main.pushFrame(frame); main.enterContext(m.entryClass(), -1); substrate.setInstructionPointer(entry.entryPoint()); } main.start(); state = 1; } < Run up to budget opcodes, servicing VM-exits (native bindings) inline. > int run(int budget) { if (state == 0) { return 0; } state = 2; int ran = 0; while (ran < budget && !substrate.isHalted() && main.running()) { substrate.step(); steps = steps + 1; ran = ran + 1; if (substrate.exiting()) { serviceExit(); } } if (substrate.isHalted()) { main.finish(); state = 3; } return ran; } < Route a parked VM-exit: a bound native service runs and returns a value; > < an unbound service is acknowledged so the guest can proceed. > void serviceExit() { int opcode = substrate.exitReasonOpcode(); int payload = substrate.exitReasonPayload(); lastExit = opcode; SLVMNativeBinding binding = bindingFor(opcode); int result = 0; if (binding != null) { < host would perform real work here > binding.recordResult(payload); result = payload; } substrate.resolveExit(); substrate.pushResult(result); } < --- guest-CPU hosting: run a Sleela CPU model as SLVM's executor --- > < Pin a Sleela CPU model (any SLCPURuntime / SLCPU) as the guest this VM > < executes, and lend it a hosted substrate so the CPU runs nested on the > < Secondary VM. The substrate is sized generously; the CPU's workload grant > < bounds actual use. > void hostCpu(SLCPURuntime cpu) { guestCpu = cpu; substrate = new SLSleelaVM(); substrate.configure(1 << 16, 4096, 1024); < the CPU's service opcodes become our VM-exits > substrate.setHosted(); < CPU lowers onto OUR substrate => true nesting > cpu.attachSubstrate(substrate); < grant the enabled options to the guest > if (dmaOption == 1) { cpu.enableDMA(); } if (gpuOption == 1) { cpu.enableGPU(); } state = 1; } < --- optional capabilities: enable BEFORE hostCpu() so the guest inherits them --- > < Direct DMA: the hosted CPU gets a direct memory-access engine, so a program > < under this VM can move bulk data without the CPU copying it word by word. > void enableDMA() { dmaOption = 1; if (guestCpu != null) { guestCpu.enableDMA(); } } void disableDMA(){ dmaOption = 0; if (guestCpu != null) { guestCpu.disableDMA(); } } boolean dmaEnabled() { return dmaOption == 1; } < Native GPU access: the hosted CPU gets a GPU device to offload compute to. > void enableGPU() { gpuOption = 1; if (guestCpu != null) { guestCpu.enableGPU(); } } void disableGPU(){ gpuOption = 0; if (guestCpu != null) { guestCpu.disableGPU(); } } boolean gpuEnabled() { return gpuOption == 1; } < Direct access to the guest's engines (null until hosted/enabled). > SLDMAController dmaEngine() { return (guestCpu != null) ? guestCpu.dmaEngine() : null; } SLGPUDevice gpuDevice() { return (guestCpu != null) ? guestCpu.gpuDevice() : null; } SLCPURuntime hostedCpu() { return guestCpu; } < Run the full stack in one call: the hosted guest CPU compiles a C/C++/Java/ > < Sleela workload, maps it onto SLVM's substrate, and SLVM drives that opcode > < stream (servicing I/O VM-exits through its native bindings). Returns the > < observable output. This is the Creator -> SLVM -> CPU -> program executor > < path realized end to end. > int runGuestWorkload(SLWorkload work, int budget) { if (guestCpu == null) { return -1; } SLSleelaVM target = guestCpu.mapWorkload(work, substrate); < workload rejected by the CPU's grant > if (target == null) { return -1; } state = 2; int ran = 0; while (ran < budget && !substrate.isHalted()) { substrate.step(); steps = steps + 1; ran = ran + 1; if (substrate.exiting()) { serviceExit(); } } if (substrate.isHalted()) { state = 3; } guestResult = substrate.printed(); work.markDone(guestResult); return guestResult; } int lastGuestResult() { return guestResult; } < --- object allocation surface for Sleela-sourced VM code --- > SLVMObject newInstance(int classId) { SLVMClass k = (module != null) ? module.classById(classId) : null; int fields = (k != null) ? k.instanceSize() : 0; SLVMObject obj = new SLVMObject(); obj.create(heap, classId, fields); return obj; } < --- GC surface: clear marks, mark reachable from the main thread's "this". --- > int collect() { heap.clearMarks(); if (main.contextHandle() >= 0) { heap.mark(main.contextHandle()); } return heap.objectCount(); } void start() { state = 2; } void stop() { state = 3; main.finish(); } void register() { } String vmName() { return name; } int runState() { return state; } int stepsRun() { return steps; } int lastService() { return lastExit; } SLVMHeap theHeap(){ return heap; } SLVMMemory linearMemory() { return memory; } SLVMThread mainThread() { return main; } SLSleelaVM engine(){ return substrate; } boolean active() { return state == 1 || state == 2; } boolean halted() { return state == 3; } }