Home /Modules/cpu/SLGuestSyscall.sleela

SLGuestSyscall.sleela

lib/cpu/SLGuestSyscall.sleela · 248 line(s) · sleela

<< 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 | <nation> | 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; }
}