Home /Modules/cpu/SLGuestVM.sleela

SLGuestVM.sleela

lib/cpu/SLGuestVM.sleela · 285 line(s) · sleela

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