Home /Modules/cpu/CPU.md

CPU.md

lib/cpu/CPU.md · 216 line(s) · markdown

lib/cpu — A Complete CPU, OS, and Program Stack in SLeeLa Source

This package builds an entire computer out of SLeeLa classes: from individual logic gates up through a multi-core CPU, a class-driven operating system, and the programs that run on top of it. Every layer is composed from the layer beneath it, so the whole machine is object-oriented SLeeLa source that bottoms out at Boolean logic.

The design is faithful to how real Intel/AMD-class processors are organized — standard cells → functional blocks → cores → chip, with caches, an I/O bus, DMA, interrupts, and drivers — while staying a readable behavioral model. Where real silicon uses carry-lookahead adders, deep pipelines, or out-of-order execution, the classes document the real technique and model the equivalent observable semantics.

The stack (bottom to top)

Layer 0 — Digital logic

ClassRole
SLGateOne Boolean gate (AND/OR/NOT/NAND/NOR/XOR/XNOR/BUF). The universal primitive.
SLCircuitA named combinational circuit; composes gates and sub-circuits; reports a transistor estimate and critical path.
SLHalfAdder1-bit sum (XOR) + carry (AND).
SLFullAdder1-bit add of a, b, carry-in → sum, carry-out (two half adders + OR).
SLAdderN-bit ripple-carry adder over a machine word.
SLALUArithmetic Logic Unit: add/sub/and/or/xor/not/shift/compare with status flags.

Layer 1 — Storage

ClassRole
SLLatchLevel-sensitive 1-bit cell.
SLFlipFlopEdge-triggered 1-bit cell (master/slave).
SLRegisterN-bit clocked, load-enabled register.
SLRegisterFileThe bank of architectural registers (r0 hardwired zero).
SLRAMWord-addressable main memory (native backing store).
SLCacheL1/L2/L3 cache with hit/miss accounting over a backing store.
SLHardDrivePersistent block storage (HDD/SSD), native file-backed.

Layer 2 — Core

ClassRole
SLClockOscillator; issues cycles (rising edges).
SLBusAddress/data/control interconnect.
SLProgramCounterNext-instruction address register (increment / branch).
SLInstructionSetThe ISA: a RISC-style opcode catalog, aligned with the VM ISA.
SLInstructionOne decoded instruction (opcode, rd, rs, imm) + encode().
SLInstructionDecoderSplits a fetched word into an SLInstruction.
SLStatusRegisterFLAGS: zero/negative/carry/overflow + mode/interrupt bits.
SLControlUnitThe fetch-decode-execute conductor; runs the ISA semantics.
SLInterruptControllerFields IRQ lines (timer, keyboard, disk, network); vectors to handlers.
SLCoreOne execution core: clock + regs + ALU + PC + status + L1 + IRQ + control.
SLCPUMulti-core chip: N cores sharing L3 and main memory.

Layer 3 — I/O and drivers

ClassRole
SLIOPortA port-mapped I/O register (IN/OUT).
SLIOBusPeripheral bus routing IN/OUT to registered ports.
SLDMAControllerDirect Memory Access block transfers.
SLDeviceDriverBase driver: probe/attach/open/read/write/close/detach + ISR.
SLConsoleDriverCharacter output (console/tty).
SLDiskDriverBlock storage via SLHardDrive + DMA.
SLKeyboardDriverInterrupt-driven character input.
SLNetworkDriverNIC frame transmit/receive via DMA.
SLDriverManagerRegisters drivers and dispatches interrupts to them.

Layer 4 — Operating system

ClassRole
SLBootloaderPOST, load the kernel image from disk, hand off to the boot core.
SLMemoryManagerPages, allocation, kernel/user split.
SLProcessProcess control block: state + saved context.
SLSchedulerRound-robin preemptive scheduler with a time quantum.
SLSystemCallThe syscall ABI (write/read/open/close/exit/spawn/yield).
SLFileSystemNamed files over disk blocks; the loader reads images through it.
SLKernelThe OS core: scheduler + memory + drivers + syscalls + filesystem; runs the main loop.
SLOperatingSystemFull OS assembly over a CPU; install() + spawn() + run().

Layer 2.5 — Hardware stack

ClassRole
SLStackThe hardware call/data stack (grows downward) for PUSH/POP and CALL/RET return addresses.

Layer 2.7 — Voltages, variable clocks, and expert timings

ClassRole
SLVoltageRailOne named, adjustable supply rail — actual voltages in mV, with load-line droop and a safe window.
SLTimingA named, careful timing budget (setup/hold/propagation/jitter/guardband in ps) with slack and max-frequency reporting.
SLBusTimingA bus's variable clock speed + named address/data-strobe/control budgets; voltage caps the trustworthy clock.
SLCpuTimingExpert CPU core timings: variable clock + Vcore + per-stage pipeline budgets; the critical stage sets the honest max clock.
SLIOTimingExpert timings for control of I/O: handshake/turnaround/recovery budgets + clock-domain-crossing synchronizer latency.
SLRamTimingExpert RAM timings: CL/tRCD/tRP/tRAS/tRC/command-rate with derived real-nanosecond access latency.
SLTimingClassThe expertise tier as a Class Object — Novice/Basic/Advanced/Expert — carrying brand/medium and the dialing policy.
SLTimingProfileGathers all rails + expert timings under one tier, dials them, checks honored(), seals an SLTimingManifest.
SLTimingManifestThe serializable operating point a compiled .sleela image carries so the VM/loader honor declared timings.

This layer is documented in detail in TIMING.md. It lets a compiled .sleela file state the actual voltages, variable clocks, and expert bus/CPU/I/O/RAM timings it was built for, so the compilers and VM operate those stated numbers rather than assuming the quality of the hardware.

Layer 5 — Programs and the multi-language toolchain

ClassRole
SLProgramAn executable image (encoded instructions + entry point).
SLAssemblerEmits encoded instructions from mnemonics into a program.
SLIRInstruction / SLIRThe common, language-neutral intermediate representation.
SLFrontendBase frontend: source → SLIR.
SLFrontendSleela / SLFrontendC / SLFrontendCpp / SLFrontendJavaPer-language frontends lowering C, C++, Java, and Sleela to the shared IR.
SLLoweringShared backend: SLIR → machine code (register allocation + label resolution).
SLCompilerDriverSelects a frontend by language/extension and runs frontend→IR→backend.
SLProgramLoaderLoads a compiled program or compiles source in any supported language and spawns it.
SLMachineThe capstone: composes the whole stack and runs it end to end.

Layer 6 — Virtualization (Linux-style guest)

ClassRole
SLHypervisorType-2 hosted hypervisor: creates/schedules guest VMs; TRAP = VM-exit.
SLGuestVMOne guest: a vCPU over a guest-physical memory window with VM-exit handling.
SLGuestLinuxA Linux-style guest kernel (boot protocol + Linux syscall ABI), emulated on VM-exit.

Execution, the multi-language loader, and the Linux-guest boundary are documented in detail in EXECUTION.md. The ISA (SLInstructionSet) is now a real multi-language lowering target with a full call/stack protocol; SLControlUnit executes the complete set.

The end-to-end chain

SLMachine demonstrates exactly what this package is for — a Sleela CPU built from Sleela source that boots a Sleela class-driven OS that then loads and runs Sleela programs:

buildHardware()   gates → ALU → registers/RAM/cache → cores → SLCPU
boot()            SLBootloader loads the kernel; SLOperatingSystem installs
                  the kernel, drivers, scheduler, memory manager, filesystem
loadDemoProgram() SLAssembler builds a program; SLProgramLoader loads it
run()             SLKernel schedules the process and runs it on the CPU,
                  servicing its SYS_WRITE / SYS_EXIT syscalls

powerOnAndRun(cores, bits, mhz, rounds) performs the whole sequence.

Minimal usage

SLMachine m = new SLMachine();
m.powerOnAndRun(4, 32, 3200, 8);   // 4 cores, 32-bit, 3.2 GHz, 8 scheduling rounds

Relationship to the rest of SLeeLa

Note on fidelity

These classes are a clear, teachable behavioral model of a modern CPU and OS, not a gate-accurate netlist of a specific Intel or AMD part. They capture the real structure and semantics (combinational logic, clocked state, the fetch-decode-execute cycle, the memory hierarchy, interrupts, DMA, drivers, scheduling, syscalls, and loading) at a level that stays readable as SLeeLa source.

What the model does and does not claim

Being explicit about the guarantees, since the point of the stack is that it is honest about its own boundaries:

  1. Running a CPU as a model models that CPU, its codes, and its features. Each SL<ARCH>CPU (including the AMD Threadripper 9000 SKUs) extends SLCPURuntime and supplies the architecture's real programmer model — its register set, data/address widths, flags — and a genuine decode() that maps the architecture's own instruction encoding onto the ALU and the substrate. SLControlUnit.step() is a real fetch-decode-execute cycle. Cache levels, the MMU/TLB, the bus, and the interrupt controller are modeled as that part's actual features (see each arch folder's CPU.md/CACHE.md/BUS.md). So the instruction semantics — the result and observable effect of executing each instruction — are faithfully represented.
  1. Instruction timing is a behavioral, conservative estimate — not cycle-accurate. The model states this plainly: `instruction latency != clock period`, and per-instruction cost depends on addressing mode, operand transfers, read/write sequence, branch outcome, and wait/interrupt state (see TIMING.md). Clock rate, the per-stage/bus/RAM/I-O timing budgets (SLCpuTiming, SLBusTiming, SLRamTiming, SLIOTiming), and cycle counts are timing hints and net-result accounting, recorded as observable/derived values. They are deliberately not presented as a cycle-accurate or transistor-level count; the model never claims an exact per-cycle silicon reproduction.
  1. The opcode mapping (Sleela → model CPU → native VM) is careful, conservative, and verified — it invents nothing. Every register-ISA instruction and every OS syscall is lowered onto the canonical opcode substrate (SLSleelaOpcode), whose codes and mnemonics mirror the native enum exactly (impl/core/sleela_core.h SLOp). The native substrate currently defines 156 opcodes (codes 0..155), organized in SLSleelaOpcode as a double shelf of three tiers — base computational/service core (0..48), substrate extensions (49..97), and host-facing services (98..155) — each with its own TIER_* flag and *_COUNT bound for the monitoring/storage layer. All are acceptable opcodes; the CPU model lowers onto the Turing-complete base core and does not fabricate a parallel instruction set. Because that substrate is already executed by the native VM and is Turing complete, the mapping is a reduction, not an invention — and it is checkable: SLTuringBridge.proveEquivalence(c, cpp, java, sleela) lowers the same computation from all four frontends to the substrate, runs each, and returns true only when every one produces the identical result. That is what makes "a program on the model CPU" and "a program on the native VM" 1:1 in Turing effect rather than an unverified assertion.