How starbuck7410/computerproject works
1. Overall shape
- This repo is a small toolchain plus emulator for a custom ISA called SIMP.
- The main execution flow is: source program → assembler or Brainfuck-to-SIMP translator → SIMP simulator/emulator → optional interactive X11-based UI.
2. Assembler subsystem (Assembler/)
- This is the standalone assembler for SIMP assembly files.
- main.c is the entry point, with support code in extras.c and opcode/lookup-table logic in luts.c.
- The assembler’s responsibility is to turn .asm programs into the binary/artifact format that the simulator consumes.
3. Simulator subsystem (Simulator/)
- This is the core emulator for the ISA.
- It is split into CPU-like stages and platform services: fetch.c, decode.c, execute_instruction.c, execute_disk.c, irq2_check.c, memory.c, and extra.c.
- That split suggests a fairly explicit processor model: instruction fetch/decode/execute, memory access, disk/device execution, and interrupt checking.
4. Hardware-model boundaries inside the simulator
- The simulator is not just a generic interpreter; it appears to model separate concerns such as:
- instruction flow,
- memory subsystem,
- disk I/O / device behavior,
- interrupt handling.
- This is important for architecture diagrams because the simulator behaves like a virtual machine with peripheral/state boundaries rather than a single monolithic loop.
5. Brainfuck toolchain (bf-simp/)
- This is a higher-level compiler/translator layer that converts Brainfuck programs into SIMP assembly.
- main.c, instructions.c, and functions.h form the translator/runtime, while procs.asm appears to be shared support code emitted or linked into the generated SIMP program.
- The pipeline here is: .bf input → SIMP assembly output → assembler → simulator.
6. Program examples (assembly-programs/ and bf-programs/)
- assembly-programs/ contains several representative SIMP assembly apps: fib, binom, mulmat, circle, terminal, disktest, test.
- bf-programs/ contains Brainfuck examples such as calc and parrot.
- These folders are important because they demonstrate the expected inputs and the kinds of workloads the ISA/emulator is meant to support.
7. Orchestration scripts at the repo root
- The root-level executables/scripts nass, assemble, compile, and simulate are the user-facing entry points.
- From the README, nass is the main wrapper: it can assemble and run a program in one step, optionally compile Brainfuck first, and clean generated artifacts.
- These scripts glue the subsystems together and define the normal developer/runtime flow.
8. Interactive/runtime environment
- The README notes that the updated simulator uses X11 for interactive parts.
- This means the runtime is Linux-oriented and includes a graphical/terminal-like emulator experience rather than just batch execution.
- That GUI boundary belongs to the simulator side, not the assembler.
9. Documentation and project context
- DOCUMENTATION.md is the authoritative design document for the custom ISA and emulator behavior.
- The README indicates the repo evolved from a university assignment into a more complete “interactive emulator” project.
- For diagramming, the docs likely define the ISA semantics, but the code structure shows the implementation split above.
10. Data flow summary
- Assembly path: .asm → Assembler → simulator input → Simulator
- Brainfuck path: .bf → bf-simp → generated SIMP assembly → Assembler → Simulator
- Program artifacts/examples sit on the side as inputs and test cases, while the root scripts manage the end-to-end pipeline.
11. Practical architecture boundary
- The repo is essentially two core engines plus a compiler frontend:
- Frontend: assembler and Brainfuck translator
- Execution engine: SIMP simulator with memory/device/interrupt modeling
- Samples and tooling: scripts, example programs, docs
- The key architectural distinction is between translation and emulation, with the simulator providing the actual machine behavior.
Main entry points: Simulator/main.c Simulator · Assembler/main.c Assembler · bf-simp/main.c BF translator · nass nass
Components 21
Translation
Assembly and Brainfuck-to-SIMP frontend tools.
- Assembler · Entry point for assembling SIMP source programs.
Assembler/main.c - Op tables · Opcode and lookup-table support for the assembler.
Assembler/luts.c - Asm utils · Auxiliary assembler support routines.
Assembler/extras.c - BF translator · Converts Brainfuck programs into SIMP assembly.
bf-simp/main.c - BF mapping · Brainfuck instruction translation and emission logic.
bf-simp/instructions.c - Support asm · Shared SIMP assembly support used by translated Brainfuck programs.
bf-simp/procs.asm
Emulation
SIMP execution engine and machine-state services.
- Simulator · Top-level SIMP emulator entry point.
Simulator/main.c - Fetch · Instruction fetch stage for the virtual CPU.
Simulator/fetch.c - Decode · Instruction decode stage for SIMP execution.
Simulator/decode.c - Execute · Core instruction execution logic.
Simulator/execute_instruction.c - Disk I/O · Disk and device behavior for the simulator.
Simulator/execute_disk.c - Interrupts · IRQ2 and interrupt-condition checking.
Simulator/irq2_check.c - Memory · Virtual memory subsystem and state access.
Simulator/memory.c - VM helpers · Additional simulator support routines.
Simulator/extra.c
Examples
Representative SIMP and Brainfuck programs.
Scripts
Root-level orchestration entry points.
- Docs · Project README and ISA documentation.
DOCUMENTATION.md - nass · Main wrapper that assembles, optionally translates Brainfuck, runs, and cleans artifacts.
nass - assemble · Script for assembling SIMP source into simulator-ready artifacts.
assemble - compile · Script for compiling Brainfuck input through the SIMP toolchain.
compile - simulate · Script for running the simulator on prepared SIMP artifacts.
simulate
Connections 23
- BF translator → BF mapping: translates · Brainfuck source is lowered into SIMP assembly through translation rules.
- BF translator → Support asm: emits/links · Generated Brainfuck programs rely on shared SIMP support code.
- BF apps → BF translator: input · Brainfuck sample programs exercise the translator.
- BF translator → Assembler: produces asm · Translator output is passed to the assembler as SIMP source.
- Assembler → Op tables: uses · Assembler relies on opcode and lookup tables.
- Assembler → Asm utils: uses · Assembler entry point depends on helper routines.
- ASM apps → Assembler: input · Assembly examples are direct inputs to the assembler.
- Assembler → Simulator: produces input for · Assembled artifacts are executed by the simulator.
- Simulator → Fetch: drives · The simulator runtime starts with instruction fetch.
- Simulator → Decode: drives · Fetched instructions are decoded by the VM pipeline.
- Simulator → Execute: drives · Decoded instructions flow into the execution engine.
- Simulator → Memory: uses · Execution reads and writes virtual memory state.
- Simulator → Disk I/O: uses · Simulator models disk/device behavior as a separate boundary.
- Simulator → Interrupts: checks · Interrupt conditions are checked during execution.
- Simulator → VM helpers: uses · Additional runtime support is provided by helper routines.
- nass → assemble: wraps · Root wrapper invokes assembly tooling.
- nass → compile: wraps · Root wrapper can compile Brainfuck through the toolchain.
- nass → simulate: wraps · Root wrapper can launch the simulator on generated artifacts.
- assemble → Assembler: calls · Assembly script delegates to the assembler.
- compile → BF translator: calls · Compile script delegates to the Brainfuck translator.
- simulate → Simulator: calls · Simulation script delegates to the emulator.
- Docs → nass: describes · Documentation defines the intended end-to-end workflow.
- Docs → Simulator: describes · Documentation covers the ISA and emulator behavior.