Python 3.9+ badge PyPI version badge tests GitHub action badge codecov badge documentation badge
Simulation of SAP (Simple-As-Possible computer) programs from COMP 311 (Computer Organization) @ UNC.
pip install SAPsim
If you get the error pip not found, use pip3 instead1 . Similarly, for later commands that use python, you'll need to use python3 instead.
Python 3.9+ is required.
In a .csv file, write a SAP program in this format (use these exact column names):
Screenshot of ex1.csv in VSCode Edit CSV
In a Python shell, import SAPsim and use SAPsim.run to run the program.
❯ python >>> from SAPsim import run >>> run("ex1.csv") # Run ex1.csv at full speed (default) ┌──────┬────────┬───────────────┬───────┬───────┐ │ PC │ Addr │ Instruction │ Dec │ Hex │ ├──────┼────────┼───────────────┼───────┼───────┤ │ │ 0 │ LDA 14 │ 30 │ 0x1e │ │ │ 1 │ SUB 13 │ 61 │ 0x3d │ │ │ 2 │ JZ 6 │ 134 │ 0x86 │ │ │ 3 │ LDI 0 │ 80 │ 0x50 │ │ │ 4 │ STA 15 │ 79 │ 0x4f │ │ │ 5 │ HLT 0 │ 240 │ 0xf0 │ │ │ 6 │ LDI 1 │ 81 │ 0x51 │ │ │ 7 │ STA 15 │ 79 │ 0x4f │ │ > │ 8 │ HLT 0 │ 240 │ 0xf0 │ │ │ 13 │ NOP 3 │ 3 │ 0x03 │ │ │ 14 │ NOP 3 │ 3 │ 0x03 │ │ │ 15 │ NOP 1 │ 1 │ 0x01 │ └──────┴────────┴───────────────┴───────┴───────┘ ┌───────┬───┐ │ PC │ 8 │ │ Reg A │ 1 │ │ Reg B │ 3 │ │ FlagC │ 1 │ │ FlagZ │ 1 │ └───────┴───┘ >>> run("ex1.csv", debug=True) # Run in debug (step) mode Initial state of simulation of ex1.csv ... Debug mode: press Enter to execute next instruction ( > ). ...
SAPsim running in Python terminal
Debug mode: There is a debug (step) mode that runs one instruction at a time, as shown above. By default, the program is run at full speed.
I recommend editing the CSV in VSCode or Excel. If you use VSCode, I recommend the extensions Edit CSV (Excel-like editing) and Rainbow CSV (adds color to columns).
Lastly, here's a blank template that includes only the column names and addresses 0-15 and two commented example programs.
All instructions are supported.
To customize table appearance, use table_format. Options.
>>> run("ex1.csv", table_format="outline") +------+--------+---------------+-------+-------+ | PC | Addr | Instruction | Dec | Hex | +======+========+===============+=======+=======+ | | 0 | LDA 14 | 30 | 0x1e | | | 1 | SUB 13 | 61 | 0x3d | | | 2 | JZ 6 | 134 | 0x86 | | | 3 | LDI 0 | 80 | 0x50 | | | 4 | STA 15 | 79 | 0x4f | | | 5 | HLT 0 | 240 | 0xf0 | | | 6 | LDI 1 | 81 | 0x51 | | | 7 | STA 15 | 79 | 0x4f | | > | 8 | HLT 0 | 240 | 0xf0 | | | 13 | NOP 3 | 3 | 0x03 | | | 14 | NOP 3 | 3 | 0x03 | | | 15 | NOP 1 | 1 | 0x01 | +------+--------+---------------+-------+-------+ +-------+---+ | PC | 8 | | Reg A | 1 | | Reg B | 3 | | FlagC | 1 | | FlagZ | 1 | +-------+---+
To modify values in the SAP program without editing the CSV, use the change keyword argument. For example, run("ex1.csv", change={14: 4, 13: 2}) would change the byte at address 14 to 4 and at 13 to 2 before execution.
It's easy to just mimic the example programs, but if you need it, here are the rules for SAPsim programs.
Footnotes
-
Consider aliasing
piptopip3and similar forpython. Also consider usingpyenv. Relevant XKCD ↩
