Home /Modules/cpu/SLCPURuntime.sleela

SLCPURuntime.sleela

lib/cpu/SLCPURuntime.sleela · 482 line(s) · sleela

<< lib/cpu/SLCPURuntime.sleela
   SLeeLa Standard Library Definition.
   Definition: Defines SLCPURuntime — the runnable base class every specific
     Sleela-sourced CPU model extends. It supplies the machinery a bare
     SL<ARCH>CPU skeleton was missing: real register storage (over SLRAM),
     architectural flags, a word-addressable memory interface, an ALU, a program
     counter, and a fetch-decode-execute loop with reset/step/run lifecycle.
   
     Crucially, SLCPURuntime is the seam that lets a CPU model run ON TOP OF the
     secondary Sleela VM: it owns an SLSleelaVM substrate and a lowering surface
     (emitConst/emitBinary/emitStore/...) so a concrete CPU can translate each of
     its native instructions into the canonical SLeeLa opcodes and execute them
     on the same engine the native Sleela VM interprets. A per-architecture model
     therefore only has to (a) declare its registers and (b) implement decode()
     to map its opcodes onto the ALU and the substrate — everything structural is
     inherited.
   
   Subclassing contract (what a concrete CPU overrides):
     - configureArch(): set widths and register count, then call bringUp().
     - decode(int word): map one fetched instruction word to execute*() / emit*().
     - optionally reset()/interrupt() for arch-specific state.
   
   Family: cpu. Composes SLRAM, SLALU, SLSleelaVM, SLSleelaOpcode. Extended by
     SL6502CPU, SLZ80CPU, SLX86CPU, SLARMCPU, SLMIPSCPU, SLRISCVCPU, SLM68000CPU. >>
#sleela 2.5
material;
class SLCPURuntime {
  < ---- 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 = 10493;
  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-09";
  < 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 archName;
  < data path width in bits >
  int width;
  < address bus width in bits >
  int addrWidth;
  < architectural register count >
  int regCount;

  < architectural registers (one word each) >
  SLRAM regs;
  < word-addressable system memory >
  SLRAM mem;
  int memWords;

  SLALU alu;
  < program counter (word index) >
  int pc;
  int flagZ; int flagN; int flagC; int flagV;
  int halted;
  < instructions executed >
  int retired;

  < --- clock: run at the model's spec, with overclock support --- >
  < spec/overclock frequency policy >
  SLClockPolicy clock;
  < the model's rated clock (set via setSpecClock) >
  int specMHz;

  < --- secondary-VM substrate: the CPU runs its lowered form here --- >
  SLSleelaVM substrate;
  SLSleelaOpcode op;
  < 1 => execute by lowering to canonical opcodes >
  int lowering;

  < --- workload execution: run C / C++ / Sleela work on this CPU within a >
  < resource grant. The register-ISA mapping pipeline is shared across all >
  < architectures (SLCompilerDriver -> SLProgram -> SLOpcodeMap -> substrate). --- >
  SLInstructionSet workIsa;
  SLInstructionDecoder workDecoder;
  SLSystemCall workSys;
  < the grant the current workload runs within >
  SLCPUResource activeGrant;
  int admittedWorkloads;
  int completedWorkloads;

  < --- substrate injection (nesting seam) --- >
  < When a host (the Secondary Sleela VM, SLVM) wants the CPU to run as a guest >
  < ON its substrate rather than on a private one, it attaches that substrate >
  < here. runWorkload()/mapWorkload() then target the attached substrate, so the >
  < CPU's lowered opcode stream and the host's dispatch loop operate on ONE >
  < SLSleelaVM — the true "CPU on top of the Secondary VM" nesting the docs >
  < describe. When null (the default) the CPU owns its substrate as before. >
  SLSleelaVM attachedSubstrate;

  < --- optional capabilities: direct DMA and native GPU access --- >
  < Off by default. A program/executor that needs them turns them on; when on, >
  < the CPU exposes a direct-memory-access engine and a GPU device it can >
  < offload to at any point. >
  < 1 when direct DMA is enabled >
  int dmaOption;
  < 1 when native GPU access is enabled >
  int gpuOption;
  < the DMA engine (operates over this CPU's memory) >
  SLDMAController dma;
  < the GPU device >
  SLGPUDevice gpu;

  < Bring the inherited machinery up once a subclass has set its widths. >
  void bringUp(String name, int dataBits, int addressBits, int registers, int memoryWords) {
    archName = name; width = dataBits; addrWidth = addressBits;
    regCount = registers; memWords = memoryWords;

    regs = new SLRAM(); regs.configure(registers + 1, 32); regs.allocate();
    mem  = new SLRAM(); mem.configure(memoryWords, 32); mem.allocate();
    alu  = new SLALU(); alu.configure(dataBits);

    pc = 0; flagZ = 0; flagN = 0; flagC = 0; flagV = 0;
    halted = 0; retired = 0;

    substrate = new SLSleelaVM();
    substrate.configure(memoryWords, 4096, registers + 16);
    op = new SLSleelaOpcode(); op.configure(0, "OP_NOP");
    lowering = 0;

    < Default the clock to a conservative 1 MHz spec; a model/user overrides it >
    < with setSpecClock(ratedMHz) so the CPU runs at its own specification. >
    clock = new SLClockPolicy();
    specMHz = (specMHz > 0) ? specMHz : 1;
    clock.configureSpec(specMHz);

    < Shared multi-language workload pipeline. >
    workIsa = new SLInstructionSet(); workIsa.configure();
    workDecoder = new SLInstructionDecoder(); workDecoder.configure(workIsa);
    workSys = new SLSystemCall(); workSys.configure();
    admittedWorkloads = 0; completedWorkloads = 0;

    < Optional capabilities default to off. >
    dmaOption = 0; gpuOption = 0;
  }

  < --- optional capability: direct DMA --- >
  < Enable the direct memory-access engine over this CPU's memory. After this a >
  < program can call dmaEngine().transfer(...) / memcpy(...) / fill(...) to move >
  < bulk data without the CPU copying word by word. >
  void enableDMA() {
    dmaOption = 1;
    if (dma == null) { dma = new SLDMAController(); }
    dma.configure(mem);
    dma.enable();
  }
  void disableDMA() { dmaOption = 0; if (dma != null) { dma.disable(); } }
  boolean dmaEnabled() { return dmaOption == 1; }
  SLDMAController dmaEngine() { return dma; }
  < Convenience passthrough for the common bulk move (returns words moved or -1). >
  int dmaCopy(int src, int dst, int length) {
    if (dmaOption == 0 || dma == null) { return -1; }
    return dma.memcpy(src, dst, length);
  }

  < --- optional capability: native GPU access --- >
  < Enable a GPU device the CPU can offload parallel/compute kernels to. The >
  < device uses a real host GPU over the bridge when available, else a modelled >
  < SIMT engine, so GPU code always runs. >
  void enableGPU() { enableGPU("SLeeLa Compute GPU", 16, 64, 1000, 256); }
  void enableGPU(String name, int units, int lanes, int core, int vramMiB) {
    gpuOption = 1;
    if (gpu == null) { gpu = new SLGPUDevice(); }
    gpu.configure(name, units, lanes, core, vramMiB);
    gpu.enable();
  }
  void disableGPU() { gpuOption = 0; if (gpu != null) { gpu.disable(); } }
  boolean gpuEnabled() { return gpuOption == 1; }
  SLGPUDevice gpuDevice() { return gpu; }

  < The register ISA used by the shared compile/map pipeline (SLWorkload.compile >
  < needs it to lower any supported language to a language-independent image). >
  SLInstructionSet workloadIsa() { return workIsa; }

  < Host hands its substrate to the CPU so the CPU runs nested on it (SLVM). >
  void attachSubstrate(SLSleelaVM hostSubstrate) { attachedSubstrate = hostSubstrate; }
  void detachSubstrate() { attachedSubstrate = null; }
  boolean nested() { return attachedSubstrate != null; }

  < --- clock / overclocking --- >
  < Set the model's rated clock (its own specification). A concrete SL<ARCH>CPU >
  < calls this in configure() so the CPU runs at spec; it may be called before >
  < or after bringUp(). >
  void setSpecClock(int ratedMHz) {
    specMHz = ratedMHz;
    if (clock == null) { clock = new SLClockPolicy(); }
    clock.configureSpec(ratedMHz);
  }
  < Overclock the CPU to a target effective frequency (returns false if the >
  < target exceeds the model's stability ceiling — the OC is applied but the >
  < policy reports it unstable). >
  boolean overclock(int targetMHz) {
    if (clock == null) { return false; }
    clock.overclockTo(targetMHz);
    return clock.isStable();
  }
  void setClockMultiplier(int m)  { if (clock != null) { clock.setMultiplier(m); } }
  void setBaseClock(int mhz)      { if (clock != null) { clock.setBaseClock(mhz); } }
  void setStabilityCeiling(int mhz){ if (clock != null) { clock.setStabilityCeiling(mhz); } }
  void resetClock()               { if (clock != null) { clock.resetToSpec(); } }

  SLClockPolicy clockPolicy() { return clock; }
  int specClockMHz()   { return specMHz; }
  int effectiveMHz()   { return (clock != null) ? clock.effectiveMHz() : specMHz; }
  boolean overclocked(){ return clock != null && clock.isOverclocked(); }
  boolean clockStable(){ return clock == null || clock.isStable(); }
  < How many model cycles the clock delivers in a given number of microseconds >
  < (lets a workload budget be expressed in time rather than raw instructions). >
  int cyclesInMicroseconds(int us) { return effectiveMHz() * us; }

  < Compile + map a workload onto a target substrate WITHOUT running it, so a >
  < host (SLVM) can drive the resulting opcode stream itself. Returns the >
  < substrate that now carries the workload, or null if the workload was >
  < rejected. Used by SLVM.runGuestWorkload for the Creator -> SLVM -> CPU -> >
  < program stack. >
  SLSleelaVM mapWorkload(SLWorkload work, SLSleelaVM target) {
    if (!admit(work)) { return null; }
    activeGrant = work.grant();
    if (!work.compiled()) { work.compile(workIsa); }
    if (!activeGrant.ioEnabled()) { target.setHosted(); }
    SLOpcodeMap map = new SLOpcodeMap();
    map.configure(workIsa, workSys, target);
    map.mapProgram(work.image(), workDecoder);
    work.markRunning();
    return target;
  }

  < --- resource assignment + workload execution --- >
  < Admission control: can this CPU satisfy the workload's resource grant? >
  < A workload is admitted only when its memory request fits the CPU's address >
  < space and (if it needs I/O/privileged services) the model provides them. >
  boolean admit(SLWorkload work) {
    SLCPUResource g = work.grant();
    if (g == null) { work.markRejected(); return false; }
    if (g.words() > memWords) { work.markRejected(); return false; }
    if (g.budget() <= 0) { work.markRejected(); return false; }
    work.markAdmitted();
    admittedWorkloads = admittedWorkloads + 1;
    return true;
  }

  < Run a workload on this CPU within its grant. The source (C/C++/Sleela/Java) >
  < is compiled to the register ISA, mapped onto THIS CPU's canonical-opcode >
  < substrate, and executed up to the grant's instruction budget. Returns the >
  < observable output (the printed value), or -1 if the workload was rejected. >
  int runWorkload(SLWorkload work) {
    if (!admit(work)) { return -1; }
    activeGrant = work.grant();

    < Compile the source to a language-independent register-ISA image. >
    if (!work.compiled()) { work.compile(workIsa); }

    < Target substrate: the host's injected one when nested (CPU runs as a guest >
    < of the Secondary VM), otherwise a fresh private one sized to the grant so >
    < one workload cannot see another's memory. >
    if (attachedSubstrate != null) {
      substrate = attachedSubstrate;
    } else {
      substrate = new SLSleelaVM();
      substrate.configure(activeGrant.words(), 4096, regCount + 16);
    }
    if (!activeGrant.ioEnabled()) { substrate.setHosted(); }

    < Map the register-ISA image onto this CPU's substrate. >
    SLOpcodeMap map = new SLOpcodeMap();
    map.configure(workIsa, workSys, substrate);
    map.mapProgram(work.image(), workDecoder);

    < Execute within the instruction budget (the resource time-slice). >
    work.markRunning();
    int ran = substrate.run(activeGrant.budget());
    int i = 0; while (i < ran) { activeGrant.chargeInstruction(); i = i + 1; }

    int observable = substrate.printed();
    work.markDone(observable);
    completedWorkloads = completedWorkloads + 1;
    return observable;
  }

  int grantsAdmitted()  { return admittedWorkloads; }
  int workloadsRun()    { return completedWorkloads; }
  SLCPUResource currentGrant() { return activeGrant; }

  < --- register / memory access (what decode() uses) --- >
  int readReg(int i)             { if (i < 0 || i > regCount) { return 0; } return regs.readWord(i); }
  void writeReg(int i, int v)    { if (i < 0 || i > regCount) { return; } regs.writeWord(i, maskWord(v)); }
  int readMem(int addr)          { if (addr < 0 || addr >= memWords) { return 0; } return mem.readWord(addr); }
  void writeMem(int addr, int v) { if (addr < 0 || addr >= memWords) { return; } mem.writeWord(addr, maskWord(v)); }

  int maskWord(int v) {
    int m = 1; int i = 0; while (i < width) { m = m * 2; i = i + 1; }
    int r = v % m; if (r < 0) { r = r + m; } return r;
  }

  < --- ALU surface (decode() routes arithmetic through here so flags are set) --- >
  int aluOp(int a, int b, int op) {
    int r = alu.execute(a, b, op);
    flagZ = alu.zero(); flagN = alu.negative(); flagC = alu.carry(); flagV = alu.overflow();
    return r;
  }

  < --- lowering surface: emit canonical opcodes onto the secondary VM --- >
  void enableLowering() { lowering = 1; substrate.setHosted(); }
  int emitConst(int v)        { return substrate.emit(op.OP_CONST, v); }
  int emitLoadGlobal(int slot){ return substrate.emit(op.OP_LOADG, slot); }
  int emitStoreGlobal(int slot){ return substrate.emit(op.OP_STOREG, slot); }
  int emitAdd()  { return substrate.emit(op.OP_ADD, 0); }
  int emitSub()  { return substrate.emit(op.OP_SUB, 0); }
  int emitMul()  { return substrate.emit(op.OP_MUL, 0); }
  int emitPrint(){ return substrate.emit(op.OP_PRINT, 0); }
  int emitHalt() { return substrate.emit(op.OP_HALT, 0); }
  int emitJump(int target)      { return substrate.emit(op.OP_JMP, target); }
  int emitJumpIfFalse(int target){ return substrate.emit(op.OP_JMPF, target); }

  < Execute the lowered program on the substrate (the "run on top of the >
  < secondary VM" path). Returns opcodes retired on the substrate. >
  int runLowered(int budget) { return substrate.run(budget); }
  int loweredOutput() { return substrate.printed(); }
  SLSleelaVM engine() { return substrate; }

  < --- fetch-decode-execute lifecycle (overridable) --- >
  < Default fetch: read the instruction word at pc and advance. >
  int fetch() {
    if (pc < 0 || pc >= memWords) { halted = 1; return 0; }
    int word = mem.readWord(pc);
    pc = pc + 1;
    return word;
  }

  < Subclasses override decode() to interpret one instruction word. The base >
  < treats a zero word as NOP and anything else as HALT so the loop terminates >
  < safely if a model forgets to override. >
  void decode(int word) {
    if (word == 0) { return; }
    halted = 1;
  }

  < Per-instruction hook a subclass overrides for M1-cycle side effects (e.g. >
  < the Z80 memory refresh). Default does nothing. >
  void preFetch() { }

  < One instruction: pre-fetch hook, fetch, decode/execute, count. >
  int step() {
    if (halted == 1) { return -1; }
    preFetch();
    int word = fetch();
    if (halted == 1) { return -1; }
    decode(word);
    retired = retired + 1;
    return word;
  }

  int run(int budget) {
    int ran = 0;
    while (halted == 0 && ran < budget) { step(); ran = ran + 1; }
    return ran;
  }

  void reset() {
    pc = 0; flagZ = 0; flagN = 0; flagC = 0; flagV = 0; halted = 0; retired = 0;
    int i = 0; while (i <= regCount) { regs.writeWord(i, 0); i = i + 1; }
  }

  void loadProgramWord(int addr, int word) { writeMem(addr, word); }
  void setEntryPoint(int addr) { pc = addr; }
  < arch-specific; default no-op >
  void interrupt(int vector) { }

  < --- introspection --- >
  boolean validate() { return width > 0 && regCount > 0 && memWords > 0; }
  String architecture() { return archName; }
  int programCounter()  { return pc; }
  int instructionsRetired(){ return retired; }
  boolean isHalted()    { return halted == 1; }
  int dataWidth()       { return width; }
  int registerCount()   { return regCount; }
  int zero()     { return flagZ; }
  int negative() { return flagN; }
  int carry()    { return flagC; }
  int overflow() { return flagV; }

  < ================================================================== >
  < RUNS BY BOTH -- the basis of function every CPU model inherits >
  < ================================================================== >
  < A CPU model is defined partly by the fact that it can run code two ways, >
  < and that the two ways AGREE: >
  <   (1) by OPCODES -- its own instruction set driven through the native >
  <       fetch-decode-execute loop (fetch/decode/step/run); and >
  <   (2) by FUNCTION-CALL EQUIVALENCE -- the code of an assumed other process >
  <       (any supported language/ISA workload) reduced through the shared >
  <       SLOpcodeMap to the equivalent canonical-opcode / service-call stream >
  <       on this CPU's substrate (runWorkload). >
  < Both mechanisms already funnel to the one canonical SLSleelaVM engine, so >
  < "runs by both" is not two behaviours but one basis observed two ways. These >
  < named entry points make that expectation first-class and inherited, and >
  < basisHolds() asserts the two observables coincide -- the opcode-vs- >
  < equivalence analogue of SLTuringBridge.proveEquivalence, on a single CPU. >

  < (1) Run a native instruction-word program through the opcode loop. The >
  < program is an int[] of packed instruction words (as a model's assembler >
  < helper produces); it is loaded from `at`, the entry point is set, and the >
  < fetch-decode-execute loop runs within `budget`. Returns opcodes retired. >
  int runByOpcodes(int[] program, int at, int budget) {
    reset();
    int n = arrayLength(program);
    int i = 0;
    while (i < n) { loadProgramWord(at + i, program[i]); i = i + 1; }
    setEntryPoint(at);
    return run(budget);
  }
  int runByOpcodes(int[] program, int budget) { return runByOpcodes(program, 0, budget); }

  < (2) Run the code of an assumed other process by function-call equivalence: >
  < the workload is compiled and mapped (SLOpcodeMap) to the equivalent opcode / >
  < service-call stream on this CPU, then executed within its grant. This is a >
  < first-class, honestly-named view of the shared workload path (runWorkload). >
  < Returns the observable output, or -1 if the workload was not admitted. >
  int runByEquivalence(SLWorkload work) { return runWorkload(work); }

  < The observable result left by the OPCODE path. A native instruction loop >
  < leaves its result in architecture-defined state (a register or a memory >
  < cell), NOT on the lowering substrate -- so the base reads register 0 as the >
  < conventional result slot. A model whose result lands elsewhere (e.g. the >
  < 6502's accumulator) overrides this to name its own result location, so the >
  < basis comparison stays honest rather than assuming a fixed convention. >
  int opcodeObservable() { return readReg(0); }

  < Does this CPU run by both? The basis holds when the SAME computation, run >
  < by opcodes and by function-call equivalence, yields the SAME observable. >
  < `opcodeProgram` is the native-opcode form left in opcodeObservable(); >
  < `equivalentWork` is the assumed-other-process form whose observable is its >
  < printed output. `expected` is the agreed result both must produce (callers >
  < supply it because the two paths observe different surfaces -- a register vs. >
  < a printed value -- so equivalence means "both equal the intended result", >
  < not "both read the same physical slot"). Returns true iff both agree with it. >
  boolean basisHolds(int[] opcodeProgram, int opcodeBudget,
                     SLWorkload equivalentWork, int expected) {
    runByOpcodes(opcodeProgram, 0, opcodeBudget);
    int viaOpcodes = opcodeObservable();
    int viaEquivalence = runByEquivalence(equivalentWork);
    return viaOpcodes == expected && viaEquivalence == expected;
  }

  < A model advertises that running by both mechanisms is part of its basis. >
  < Always true for an SLCPURuntime-derived model: both the opcode loop and the >
  < equivalence pipeline are inherited here. Subclasses do not re-implement it; >
  < they inherit the capability by extending this runtime. >
  boolean runsByBoth() { return true; }
}