<< lib/cpu/SLGuestLinux.sleela SLeeLa Standard Library Definition. Definition: Defines SLGuestLinux — a Linux-style guest operating system that boots inside an SLGuestVM on the Sleela CPU. It models the Linux boot and runtime surface the hypervisor must support: a boot protocol (load kernel image + initrd into the guest window and jump to the entry), a Linux-style syscall ABI (write/read/open/close/exit/mmap/fork/execve as numbers), and the init handoff (PID 1). SCOPE NOTE — important: this is an ARCHITECTURAL MODEL of running a Linux-like guest, not the real Linux kernel. It defines the boot sequence, the syscall numbers the guest issues, and how those become VM-exits the hypervisor emulates. Running the actual upstream Linux kernel would require a full hardware-virtualization CPU and device model (far beyond this library). The value here is a faithful, composable model of the layering: SLCPU -> SleelaOS -> SLHypervisor -> SLGuestVM -> SLGuestLinux -> guest programs. Family: cpu. Composes SLGuestVM; booted by SLHypervisor. >> #sleela 2.5 material; class SLGuestLinux { < ---- 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 = 10234; 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; } < A small, Linux-like syscall ABI (numbers chosen for the model). > static final int LINUX_READ = 0; static final int LINUX_WRITE = 1; static final int LINUX_OPEN = 2; static final int LINUX_CLOSE = 3; static final int LINUX_MMAP = 9; static final int LINUX_EXIT = 60; static final int LINUX_FORK = 57; static final int LINUX_WAIT = 61; static final int LINUX_EXECVE = 59; String distro; SLGuestVM vm; < compiled kernel image (step 4), if built > SLGuestKernelImage kernelImage; < guest task scheduler, timer-driven (step 6) > SLGuestScheduler scheduler; < in-guest filesystem over the block device > SLGuestFileSystem filesystem; < guest syscall ABI dispatcher (lazy) > SLGuestSyscall syscalls2; int kernelEntry; int initEntry; int booted; int syscalls; int timerTicks; void configure(String distroName, SLGuestVM guest) { distro = distroName; vm = guest; booted = 0; syscalls = 0; kernelEntry = 0; initEntry = 0; timerTicks = 0; < 4-tick quantum > scheduler = new SLGuestScheduler(); scheduler.configure(4); < Mount a filesystem on the guest block device (data region after the > < kernel/boot blocks) if the guest has one. > SLGuestDeviceBus bus = guest.deviceBus(); if (bus != null && bus.blockDevice() != null) { filesystem = new SLGuestFileSystem(); filesystem.configure(bus.blockDevice(), 128); } } SLGuestFileSystem fileSystem() { return filesystem; } < Deliver any pending signal to the currently-running task's slot. Called at > < scheduling points so signals (e.g. SIGKILL/SIGTERM) take effect. > void deliverSignals() { SLGuestSyscall sys = syscallTable(); SLGuestTask run = scheduler.running(); if (run != null && sys.signalTable() != null) { int slot = scheduler.currentSlot(); if (slot >= 0) { sys.signalTable().deliver(slot); } } } < The guest syscall dispatcher, wired to this guest's devices, filesystem, > < and scheduler. Lazily built on first use. > SLGuestSyscall syscallTable() { if (syscalls2 == null) { syscalls2 = new SLGuestSyscall(); syscalls2.configure(vm.deviceBus(), filesystem, scheduler, 49152); } return syscalls2; } < Create and admit a guest task (a guest thread). The guest init process > < (PID 1) spawns these; the timer then schedules them preemptively. > SLGuestTask spawnTask(int tid, String name, int entryIndex) { SLGuestTask t = new SLGuestTask(); t.configure(tid, name, entryIndex); scheduler.admit(t); return t; } < Program the guest timer and start preemptive scheduling: set the timer > < reload and enable it so each expiry drives scheduler.onTimerTick(). > void startScheduling(int reload) { SLGuestDeviceBus bus = vm.deviceBus(); if (bus != null) { bus.programTimer(reload); } } < The guest timer-IRQ handler (the preemption point): advance the scheduler, > < save the current task's resume IP, and select the next task to run. > SLGuestTask onTimerInterrupt(int currentIP) { timerTicks = timerTicks + 1; SLGuestTask prev = scheduler.running(); if (prev != null) { prev.saveIP(currentIP); } return scheduler.onTimerTick(); } SLGuestScheduler taskScheduler() { return scheduler; } int timerTickCount() { return timerTicks; } < Start the guest init process (PID 1), which loads and spawns user programs. > < Returns the init object so the caller can exec() programs on it. > SLGuestInit startInit() { SLGuestInit init = new SLGuestInit(); init.configure(this, vm.guestSubstrate()); < Give the syscall layer access to init so execve() can reach the shared > < compile->load toolchain, and so fork()/wait() route through the same > < process table init manages. > syscallTable().attachInit(init); return init; } < Install a genuinely-compiled kernel image to boot (step 4). When set, > < boot() loads this image into the guest substrate instead of the inline stub. > void installKernelImage(SLGuestKernelImage image) { kernelImage = image; } < Build and install a compiled guest kernel from source in any supported > < language, via the real toolchain (SLGuestKernelBuilder). > void buildKernel(String sourcePath, int langId) { SLGuestKernelBuilder builder = new SLGuestKernelBuilder(); builder.configure(); kernelImage = builder.build(sourcePath, langId, "slk", "0.1"); } < Boot protocol: load a minimal guest-kernel opcode image into the guest VM's > < substrate, record the entry points, and enter the guest. The image is a > < real stream of canonical SLeeLa opcodes that the substrate executes (step > < 1): the "kernel" computes a value and prints it (its init banner), then > < halts — a stand-in for a real kernel image until step 4 loads a compiled > < guest kernel. A real boot copies bzImage + initrd into guest memory. > int boot(int kernelImageEntry, int initImageEntry) { kernelEntry = kernelImageEntry; initEntry = initImageEntry; loadKernelImage(); < guest substrate ip at 0; vCPU records entry > vm.enter(); booted = 1; return kernelEntry; } < Load the guest kernel into the substrate. If a compiled image was installed > < (step 4), load that genuinely-compiled kernel; otherwise fall back to a > < minimal inline opcode heartbeat so an unconfigured guest still boots. > void loadKernelImage() { if (kernelImage != null) { kernelImage.loadInto(vm.guestSubstrate()); return; } SLSleelaOpcode op = new SLSleelaOpcode(); op.configure(0, "OP_NOP"); < Fallback inline "init": print 2 + 3 (a boot heartbeat), then halt. > vm.loadOpcode(op.OP_CONST, 2); vm.loadOpcode(op.OP_CONST, 3); vm.loadOpcode(op.OP_ADD, 0); vm.loadOpcode(op.OP_PRINT, 0); vm.loadOpcode(op.OP_HALT, 0); } < Translate a guest Linux syscall number to the host SleelaOS syscall the > < hypervisor emulates it with (the VM-exit handler's job). > < Host-syscall mapping constants (SLSystemCall surface: write/read/open/close/ > < exit/spawn/yield = 0..6). Process creation is modeled thus: a guest fork() > < leans on the host's SYS_SPAWN primitive, while execve()/wait() have no host > < equivalent and are serviced entirely in-guest (SLGuestSyscall against the > < guest scheduler/process table). The actual in-guest routing happens in > < SLGuestVM.handleExit() off the OP_SPAWN/OP_JOINALL service opcodes; > < emulateSyscall() is the ABI-classification view, so it returns the > < GUEST_EMULATED tag (not a host syscall number) for those two to make the > < "no host delegate" distinction explicit to callers that classify a syscall. > static final int GUEST_EMULATED = 100; < True if the given guest Linux syscall is serviced in-guest (no host > < delegate): execve/wait are emulated against the guest process table rather > < than mapped to a host SleelaOS syscall. (A pure predicate — unlike > < emulateSyscall(), it does not count the call.) > boolean isGuestEmulated(int linuxNumber) { return linuxNumber == LINUX_EXECVE || linuxNumber == LINUX_WAIT; } int emulateSyscall(int linuxNumber) { syscalls = syscalls + 1; < host SYS_WRITE > if (linuxNumber == LINUX_WRITE) { return 0; } < host SYS_READ > if (linuxNumber == LINUX_READ) { return 1; } if (linuxNumber == LINUX_OPEN) { return 2; } if (linuxNumber == LINUX_CLOSE) { return 3; } < host SYS_EXIT > if (linuxNumber == LINUX_EXIT) { return 4; } < host SYS_SPAWN (process create) > if (linuxNumber == LINUX_FORK) { return 5; } < emulated in-guest > if (linuxNumber == LINUX_EXECVE) { return GUEST_EMULATED; } < emulated in-guest > if (linuxNumber == LINUX_WAIT) { return GUEST_EMULATED; } < unsupported (e.g. LINUX_MMAP): delivered as a guest fault > return -1; } boolean isBooted() { return booted == 1; } int syscallsEmulated() { return syscalls; } String distribution() { return distro; } }