SLeeLa # SLeeLa VM Creator Source Package The /lib/vm/creator package is the SLeeLa source-side VM Creator. It gives each SLVM generation a stable formal name and source-level construction contract while keeping /impl as the standard native Core implementation. ## Formal VM names | Path | Formal Name | Source | |---|---|---| | /impl | Core | SleelaVMCore.sleela | | /1 | Foundation | SLVMFoundation.sleela | | /2 | Operator | SLVMOperator.sleela | | /3 | Specialist | SLVMSpecialist.sleela | | /4 | Supervisor | SLVMSupervisor.sleela | | /5 | Manager | SLVMManager.sleela | | /6 | Director | SLVMDirector.sleela | | /7 | Administrator | SLVMAdministrator.sleela | | /8 | Executive | SLVMExecutive.sleela | | /9 | Authority | SLVMAuthority.sleela | | /10 | Principal | SLVMPrincipal.sleela | | /11 | Sovereign | SLVMSovereign.sleela | These names are descriptive identifiers, not permissions by themselves. Selecting a higher-numbered VM never implicitly grants OS, filesystem, network, storage, security, or administrative capability. ## Creator entry points - SleelaVMCreator.sleela — VM construction coordinator (**implemented**): selects a generation, builds and **boots a live SLVM**, hosts a Sleela CPU as the executor, and runs a C/C++/Java/Sleela program through it. - SleelaVMGenerationCatalog.sleela — canonical version-to-name/path catalog (**implemented**). - SleelaVMCore.sleela — /impl Core contract. SLVMFoundation .. SLVMSovereign — the per-generation build-side contracts (`/1` .. `/11`). The creator reads the canonical VM configuration, selects one generation, resolves its source modules, builds a SleelaVMBuildPlan, invokes the compiler, verifies the artifact, and packages the result. `SleelaVMCreator` additionally instantiates the result as a running `SLVM` (lib/vm/SLVM.sleela) so the VM can be used immediately, not just packaged. ## Construction model configuration -> generation catalog -> named VM source -> architecture/options -> build plan -> compiler -> C/C++ native boundary -> VM artifact -> verification -> package All generations use the common source models under /lib/vm. A generation class adds the responsibilities appropriate to its documented VM architecture. ## Running the full stack: Creator → SLVM → Sleela CPU → program The Creator Edition's purpose is to produce a VM you can then *run guest code on*. The executor is a **Sleela CPU model** (any `SLCPURuntime` / `SLCPU` in `/lib/cpu`), and the guest code is a **C, C++, Java, or Sleela** program: ``` SleelaVMCreator → SLVM (Secondary VM, on the Native Sleela VM substrate) → hostCpu(SLCPU) (the executor, nested on the SLVM substrate) → runGuestWorkload(C | C++ | Java | Sleela program) ``` The whole chain resolves in one call: ``` SLCPUResource grant = new SLCPUResource(); grant.configure(4096, 100000, grant.PRIORITY_NORMAL); SL6502CPU cpu = new SL6502CPU(); cpu.configure(); SLWorkload job = new SLWorkload(); job.configure("app", "examples/hello.c", job.LANG_C, grant); SleelaVMCreator creator = new SleelaVMCreator(); creator.configure(); int out = creator.run(5, cpu, job, 1000000); // generation 5 "Manager"; returns the program's output ``` How the layers connect (the bridge): - `SleelaVMCreator.create()` builds and boots the `SLVM`. - `SLVM.hostCpu(cpu)` lends the CPU the VM's `SLSleelaVM` substrate, and the CPU calls `attachSubstrate(...)` so it lowers its program onto **that** substrate — the CPU runs *nested* on the Secondary VM, not on a private engine. - `SLVM.runGuestWorkload(job, budget)` has the CPU compile the program (`SLCompilerDriver` → `SLProgram`, language-independent) and map it onto the shared substrate (`SLOpcodeMap`), then SLVM drives the opcode stream and services I/O VM-exits, returning the observable result. See `examples/creator-full-stack.sleela` for a runnable demonstration (C and Java programs through a 6502 executor on a Manager-generation SLVM). ## Build options Request these on the creator before `create()`/`run()`; they flow into the built VM and its hosted CPU: - `requestDMA()` — direct memory-access engine (bulk transfers without the CPU copying word by word). - `requestGPU()` — native GPU access (offload compute kernels to a host GPU over the bridge, or a modelled SIMT engine when none is present). - `requestNativeRam()` — run the VM's linear memory on **real host RAM** (`SLNativeMemory`) instead of the simulated `SLRAM` store, for running outside simulation for procedural layment. ``` SleelaVMCreator creator = new SleelaVMCreator(); creator.configure(); creator.requestNativeRam(); // run on real host RAM creator.requestDMA(); // direct DMA creator.requestGPU(); // native GPU int out = creator.run(5, cpu, job, 1000000); ``` These correspond to the `DMA`, `GPU`, and `NATIVE_RAM` capability bits in `../SleelaVMFeatureBits.sleela`. See `examples/native-ram-vm.sleela`. ## Source authority The .sleela definitions describe what the VM Creator is constructing. Native C/C++ implements required low-level services. The creator must not silently invent modules, capabilities, memory limits, or host authority.