README.md

SAPsim

Simulation of SAP (Simple-As-Possible computer) programs from COMP 311 (Computer Organization) @ UNC.

Install

pip install SAPsim

If you get pip not found, use pip3 instead¹. Python 3.9+ is required.

Usage

In a CSV file, write a SAP program in this format (template):

ex1.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. The default behavior is to run at full speed.

If you successfully installed SAPsim earlier (check with pip show SAPsim) but get a ModuleNotFoundError when importing SAPsim, run Python with python3 instead of python (or vice versa).

I recommend editing the CSV in VSCode or Excel. I recommend the VSCode extensions Edit CSV (Excel-like editing) and Rainbow CSV (adds color to columns).

Lastly, there are two commented example programs here.

SAP instruction set

All instructions are supported.

Settings

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.

Rules

It's easy to just mimic the example programs, but if you need it, here are the rules for SAPsim programs.

Documentation

https://SAPsim.readthedocs.io

Code structure

Footnotes

1. Consider aliasing pip to pip3 and similar for python. Also consider using pyenv. Relevant XKCD ↩