<< lib/cpu/SLGuestVM.sleela SLeeLa Standard Library Definition. Definition: Defines SLGuestVM — one guest virtual machine managed by the hypervisor. It presents a virtual CPU over a window of host memory (guest-physical addressing) and, crucially, EXECUTES the guest as a stream of canonical SLeeLa opcodes on an embedded SLSleelaVM substrate. Guest code is therefore run by the same Turing-complete engine as everything else in the model (step 1 of the OS-VM roadmap): the guest is not merely ticked and counted — its opcodes are actually dispatched. A guest TRAP/SYSCALL opcode is a VM-exit: the vCPU stops at that point, the hypervisor/guest-kernel emulates the operation, and the guest resumes. VM exits are recorded so the hypervisor can account for and service them. Guest address translation uses a real MMU (SLMMU, page tables + protection) when one is attached, falling back to a single base-offset window otherwise. Family: cpu. Composes SLCore, SLSleelaVM, SLRAM, SLMMU. >> #sleela 2.5 material; class SLGuestVM { < ---- 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 = 10243; String metaAuthor = "Kiro Agent"; 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-10-06"; < 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; < virtual CPU (the guest's modeled hardware core) > SLCore vcpu; < the Turing-complete engine that actually runs guest code > SLSleelaVM substrate; SLRAM hostMemory; < real page-table translation (step 2); null => base-offset > SLMMU mmu; < guest device model: timer, console, block (step 3) > SLGuestDeviceBus devices; < guest kernel, for timer-driven scheduling (step 6) > SLGuestLinux kernel; < host-physical base of the guest's memory window > int windowBase; < words > int windowSize; < guest-physical entry point > int guestEntry; int running; int exits; int guestInstr; < 0 none, 1 syscall, 2 trap, 3 halt > int lastExitReason; static final int EXIT_NONE = 0; static final int EXIT_SYSCALL = 1; static final int EXIT_TRAP = 2; static final int EXIT_HALT = 3; void configure(String vmName, SLCore core, SLRAM ram, int base, int size, int entry) { name = vmName; vcpu = core; hostMemory = ram; windowBase = base; windowSize = size; guestEntry = entry; running = 0; exits = 0; guestInstr = 0; lastExitReason = EXIT_NONE; < Each guest gets its own opcode substrate (its guest-physical code/data). > substrate = new SLSleelaVM(); substrate.configure(65536, 8192, 4096); } < Attach a real MMU for page-table translation + protection faults (step 2). > void attachMMU(SLMMU unit) { mmu = unit; } SLMMU memoryUnit() { return mmu; } < Attach the guest device model (timer/console/block) (step 3). > void attachDevices(SLGuestDeviceBus bus) { devices = bus; } SLGuestDeviceBus deviceBus() { return devices; } < Attach the guest kernel so timer interrupts drive its scheduler (step 6). > void attachKernel(SLGuestLinux guestKernel) { kernel = guestKernel; } < Advance the guest's devices by one tick (timer heartbeat, IRQ posting). > void tickDevices() { if (devices != null) { devices.tick(); } } < Guest-virtual -> host-physical translation: via the MMU when present > < (page tables + protection; a fault returns -1 and the hypervisor delivers a > < TRAP), else a single base-offset window. > int translate(int guestAddr) { if (mmu != null) { int phys = mmu.translate(guestAddr); < page fault -> VM-exit > if (phys < 0) { recordTrapExit(); return windowBase; } return phys; } return windowBase + guestAddr; } boolean inWindow(int guestAddr) { return guestAddr >= 0 && guestAddr < windowSize; } < Load one guest opcode+arg into the substrate's code store (the guest kernel > < / loader populates this; see SLGuestLinux). > int loadOpcode(int opcode, int arg) { return substrate.emit(opcode, arg); } SLSleelaVM guestSubstrate() { return substrate; } < Enter the guest: put the substrate in hosted mode (service opcodes become > < VM-exits the hypervisor routes), record the translated entry on the vCPU. > void enter() { substrate.setHosted(); vcpu.loadEntryPoint(translate(guestEntry)); running = 1; } < Run the guest, driving the VM-exit loop (step 5): execute substrate opcodes > < until a VM-exit (a service opcode parks one) or HALT; route each exit to the > < device model / syscall emulation; resolve it and resume. Devices are ticked > < each round so the timer heartbeat advances and posts interrupts. > int run(int budget) { if (running == 0) { enter(); } int ran = 0; while (running == 1 && ran < budget && !substrate.isHalted()) { int slice = substrate.run(budget - ran); ran = ran + slice; < guard against stall > if (slice == 0 && !substrate.exiting()) { ran = ran + 1; } if (substrate.exiting()) { handleExit(substrate.exitReasonOpcode(), substrate.exitReasonArg(), substrate.exitReasonPayload()); substrate.resolveExit(); } < advance timer; post device IRQs > tickDevices(); < let the guest PIC see raised lines > deliverPendingInterrupts(); } if (substrate.isHalted()) { running = 0; exits = exits + 1; lastExitReason = EXIT_HALT; } return ran; } < Route a VM-exit from a service opcode to the guest syscall ABI (step b). > < Service opcodes are the guest's syscall surface: OP_PRINT is write(1, ch), > < and the OP_FILE* opcodes are open/read/write/close. When a kernel is > < attached, the exit is dispatched through its syscall table (which emulates > < the service against the guest console, filesystem, and scheduler); the > < result is pushed back for the guest to resume with. SYS_EXIT finishes the > < running task. > void handleExit(int opcode, int arg, int payload) { SLSleelaOpcode op = new SLSleelaOpcode(); op.configure(0, "OP_NOP"); recordSyscallExit(); if (kernel == null) { < No kernel: fall back to direct console emulation for OP_PRINT. > if (opcode == op.OP_PRINT && devices != null && devices.hasConsole()) { devices.consoleWrite(payload); } return; } int result = serviceOpcode(opcode, arg, payload); < syscall return value to the guest > substrate.pushResult(result); } < Route one service opcode to the guest syscall ABI and return the syscall > < result, applying the SYS_EXIT side effect (finish the running task). This > < is the shared routing used by handleExit(); exposing it lets the guest's > < process-creation path (OP_SPAWN fork/execve, OP_JOINALL wait) be driven and > < observed directly, so the opcode->syscall mapping is exercised end to end. > int serviceOpcode(int opcode, int arg, int payload) { if (kernel == null) { return -1; } SLSleelaOpcode op = new SLSleelaOpcode(); op.configure(0, "OP_NOP"); SLGuestSyscall sys = kernel.syscallTable(); int number = syscallNumberFor(opcode, arg, op, sys); int result = sys.dispatch(number, syscallArg0(opcode, arg, op, payload), payload, syscallArg2(opcode, arg, op)); < SYS_EXIT: finish the running task > if (sys.isExit(number)) { SLGuestTask t = kernel.taskScheduler().running(); if (t != null) { t.finish(); } } return result; } < Map a service opcode to a guest syscall number. The process-creation family > < reuses the canonical substrate opcodes: OP_SPAWN is clone/exec (its arg > < selects fork vs. execve) and OP_JOINALL is wait. > int syscallNumberFor(int opcode, int arg, SLSleelaOpcode op, SLGuestSyscall sys) { if (opcode == op.OP_PRINT) { return sys.SYS_WRITE; } if (opcode == op.OP_FILEOPEN) { return sys.SYS_OPEN; } if (opcode == op.OP_FILEREAD) { return sys.SYS_READ; } if (opcode == op.OP_FILEWRITE) { return sys.SYS_WRITE; } if (opcode == op.OP_FILECLOSE) { return sys.SYS_CLOSE; } if (opcode == op.OP_SPAWN) { < OP_SPAWN with arg 0 is fork(); arg > 0 selects execve() (arg carries > < langId + 1 so 0 stays reserved for a plain fork). > if (arg == 0) { return sys.SYS_FORK; } return sys.SYS_EXECVE; } if (opcode == op.OP_JOINALL) { return sys.SYS_WAIT; } if (opcode == op.OP_HALT) { return sys.SYS_EXIT; } return sys.SYS_YIELD; } < The first syscall argument (fd for I/O; progId for execve): OP_PRINT writes > < to stdout (fd 1); OP_SPAWN carries the exec program id as its stack payload, > < surfaced to execve as arg0. > int syscallArg0(int opcode, int arg, SLSleelaOpcode op, int payload) { if (opcode == op.OP_PRINT) { return 1; } < execve progId > if (opcode == op.OP_SPAWN && arg != 0) { return payload; } return 0; } < The third syscall argument (execve langId): recovered from OP_SPAWN's arg, > < which holds langId + 1 so that arg 0 can mean "plain fork". > int syscallArg2(int opcode, int arg, SLSleelaOpcode op) { < langId > if (opcode == op.OP_SPAWN && arg != 0) { return arg - 1; } return 0; } < Surface any device interrupts the guest PIC now has pending and deliver them > < to the guest kernel. A timer IRQ (line 0) drives the guest scheduler > < (step 6): the kernel preempts the running task and selects the next one, > < and the substrate resumes at that task's saved instruction pointer. > void deliverPendingInterrupts() { if (devices != null) { int line = devices.pendingInterrupt(); if (line >= 0) { recordTrapExit(); devices.acknowledge(line); < timer IRQ -> scheduler > if (line == 0 && kernel != null) { SLGuestTask next = kernel.onTimerInterrupt(substrate.instructionPointer()); if (next != null) { < Deliver any pending signal to the newly-scheduled task (its slot > < is the scheduler's current index) before resuming it. > kernel.deliverSignals(); if (next.alive()) { substrate.setInstructionPointer(next.resumeIP()); } } } } } } < A guest syscall VM-exit: the guest kernel calls this when its code reaches a > < service point, so the hypervisor can emulate it against the host. > void recordSyscallExit() { exits = exits + 1; lastExitReason = EXIT_SYSCALL; } void recordTrapExit() { exits = exits + 1; lastExitReason = EXIT_TRAP; } void stop() { running = 0; } int exitCount() { return exits; } int lastExit() { return lastExitReason; } int guestInstructions() { return guestInstr; } < observable guest output > int printed() { return substrate.printed(); } String vmName() { return name; } int entry() { return guestEntry; } }