<< lib/cpu/SLGuestSyscall.sleela SLeeLa Standard Library Definition. Definition: Defines SLGuestSyscall — the guest kernel's system-call ABI and dispatcher. When a guest user program issues a syscall, the substrate takes a VM-exit; SLGuestVM routes it here, and this class emulates the requested service against the guest's devices (console), filesystem, scheduler, and task table, then returns a result the guest resumes with. This is the controlled user->kernel boundary a real OS exposes. ABI: a guest syscall carries a number plus up to three integer arguments (modeled as the exit payload + operand-stack values). The dispatcher returns an integer result (or a negative errno-style code), and reports control effects (exit/yield) so SLGuestVM can act on them. Family: cpu. Composes SLGuestDeviceBus, SLGuestFileSystem, SLGuestScheduler. >> #sleela 2.5 material; class SLGuestSyscall { < ---- 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 = 10240; 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; } < Linux-like syscall numbers (a small, representative subset). > static final int SYS_READ = 0; static final int SYS_WRITE = 1; static final int SYS_OPEN = 2; static final int SYS_CLOSE = 3; static final int SYS_BRK = 12; < create a pipe (returns a pipe handle) > static final int SYS_PIPE = 22; < sched_yield > static final int SYS_YIELD = 24; static final int SYS_GETPID = 39; < send a signal to a task slot > static final int SYS_KILL = 62; static final int SYS_EXIT = 60; < Process creation / lifecycle (the fork/exec/wait family). > < clone the caller; child shares its text > static final int SYS_FORK = 57; < replace the caller's image with a new one > static final int SYS_EXECVE = 59; < reap a finished child, yielding its status > static final int SYS_WAIT = 61; < Pipe fd convention: fds >= PIPE_FD_BASE address the single modeled pipe's > < read (base) / write (base+1) ends. > static final int PIPE_FD_BASE = 100; SLGuestDeviceBus devices; SLGuestFileSystem fs; SLGuestScheduler scheduler; < process spawner (for execve: compile/load a new image) > SLGuestInit init; < IPC: a (modeled single) pipe > SLGuestPipe pipe; < IPC: signal delivery > SLGuestSignal signals; < modeled program break (heap top) > int brkTop; < tid allocator for fork()'d children > int nextChildPid; int calls; int lastResult; < exit status returned by the most recent wait() > int lastChildStatus; void configure(SLGuestDeviceBus deviceBus, SLGuestFileSystem filesystem, SLGuestScheduler sched, int heapBase) { devices = deviceBus; fs = filesystem; scheduler = sched; brkTop = heapBase; calls = 0; lastResult = 0; nextChildPid = 1000; lastChildStatus = 0; signals = new SLGuestSignal(); signals.configure(sched); } < Give the syscall layer the init process so execve can reach the shared > < compile->load->admit toolchain. Wired lazily by the kernel. > void attachInit(SLGuestInit guestInit) { init = guestInit; } SLGuestSignal signalTable() { return signals; } SLGuestPipe currentPipe() { return pipe; } int childStatus() { return lastChildStatus; } boolean valid(int number) { return number == SYS_READ || number == SYS_WRITE || number == SYS_OPEN || number == SYS_CLOSE || number == SYS_BRK || number == SYS_PIPE || number == SYS_YIELD || number == SYS_GETPID || number == SYS_KILL || number == SYS_EXIT || number == SYS_FORK || number == SYS_EXECVE || number == SYS_WAIT; } boolean isPipeFd(int fd) { return fd >= PIPE_FD_BASE; } < Dispatch a syscall. arg0..arg2 are the integer arguments; returns the > < syscall result (>=0) or a negative error. Control effects (exit/yield) are > < queried separately by the caller via isExit()/isYield(). > int dispatch(int number, int arg0, int arg1, int arg2) { calls = calls + 1; int r = -1; if (number == SYS_WRITE) { < write(fd, ch, _): fd 1/2 -> console; pipe fd -> pipe; else -> filesystem. > if (arg0 == 1 || arg0 == 2) { if (devices != null && devices.hasConsole()) { devices.consoleWrite(arg1); r = 1; } } else if (isPipeFd(arg0) && pipe != null) { r = pipe.writeByte(arg1); } else if (fs != null) { r = fs.writeByte(arg0, arg1); } } else if (number == SYS_READ) { if (isPipeFd(arg0) && pipe != null) { r = pipe.readByte(); } else if (fs != null) { r = fs.readByte(arg0); } } else if (number == SYS_PIPE) { < Create the pipe; return its read-end fd (write end is read end + 1). > pipe = new SLGuestPipe(); pipe.configure(256); r = PIPE_FD_BASE; } else if (number == SYS_KILL) { < kill(slot, sig): raise a signal against the task in scheduler slot arg0. > if (signals != null) { signals.raise(arg0, arg1); r = 0; } else { r = -1; } } else if (number == SYS_OPEN) { if (fs != null) { r = fs.openByName(arg0); } } else if (number == SYS_CLOSE) { if (fs != null) { r = fs.close(arg0); } } else if (number == SYS_GETPID) { if (scheduler != null && scheduler.running() != null) { r = scheduler.running().taskId(); } else { r = 1; } } else if (number == SYS_BRK) { if (arg0 > 0) { brkTop = arg0; } r = brkTop; } else if (number == SYS_YIELD) { r = 0; } else if (number == SYS_FORK) { r = doFork(); } else if (number == SYS_EXECVE) { < execve(progName, sourcePath, langId): replace the caller's image with a > < freshly compiled one. arg0/arg1 are modeled file identifiers the init > < toolchain resolves; arg2 is the source language id. > r = doExecve(arg0, arg1, arg2); } else if (number == SYS_WAIT) { r = doWait(); } else if (number == SYS_EXIT) { < exit(status): record the status on the running task so a waiting parent > < can reap it, and leave it DONE (a zombie until wait()ed on). > if (scheduler != null && scheduler.running() != null) { scheduler.running().exitWith(arg0); } r = arg0; } lastResult = r; return r; } < fork(): clone the running task. The kernel returns the child's tid to the > < parent and (by convention) 0 to the child; here we model the parent's > < return value (the child's new tid). The child is admitted as a ready task > < that resumes at the same point as the parent. Returns -1 if there is no > < running task or the task table is full. > int doFork() { if (scheduler == null) { return -1; } SLGuestTask parent = scheduler.running(); if (parent == null) { return -1; } < Draw the child pid from the single guest pid allocator (init) so fork'd > < children and init-spawned programs share one, collision-free pid space; > < fall back to a private counter only if init is not wired yet. > int childTid; if (init != null) { childTid = init.allocPid(); } else { childTid = nextChildPid; nextChildPid = nextChildPid + 1; } SLGuestTask child = scheduler.fork(parent, childTid); < out of task slots > if (child == null) { return -1; } < parent sees the child's pid > return childTid; } < execve(): replace the running task's program image with a newly compiled > < one, loaded through init's shared toolchain, and repoint the task's resume > < IP at the new image's entry. Models the Unix contract that a successful > < execve does not return to the old image. Returns the new entry index, or -1 > < if execve is unavailable or the running task is unknown. > int doExecve(int progId, int srcId, int langId) { if (init == null || scheduler == null) { return -1; } SLGuestTask caller = scheduler.running(); if (caller == null) { return -1; } int entry = init.execInto(caller, progId, srcId, langId); < init repoints caller's IP; <0 on failure > return entry; } < wait(): reap a finished child of the running task. Returns the reaped > < child's tid (and stashes its exit status in lastChildStatus for the kernel > < to deliver), -1 if the caller has no children at all, or SYS_WAIT_BLOCK > < (negative) when children exist but none has exited yet (the caller should > < retry — modeled as a yield). > int doWait() { if (scheduler == null) { return -1; } SLGuestTask caller = scheduler.running(); if (caller == null) { return -1; } SLGuestTask child = scheduler.reapChild(caller.taskId()); if (child != null) { lastChildStatus = child.status(); return child.taskId(); } < not ready yet > if (scheduler.hasLiveChild(caller.taskId())) { return WAIT_BLOCK; } < no children > return -1; } < wait() would block: children exist, none exited > static final int WAIT_BLOCK = -2; boolean isExit(int number) { return number == SYS_EXIT; } boolean isYield(int number) { return number == SYS_YIELD; } boolean isWaitBlocked(int result) { return result == WAIT_BLOCK; } int programBreak() { return brkTop; } int result() { return lastResult; } int callCount() { return calls; } }