SAPsim

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

Install

pip install SAPsim

Python 3.9+ is required. If your pip command doesn't work, use pip3¹.

Usage

Write a SAP program in a CSV file using the format shown below.

ex1.csv

Two commented example programs are in public_prog/. Also, there's an empty template file here. Lastly, I recommend editing the CSV using VSCode's Edit csv extension or Excel.

To run the SAP program, open a Python terminal and use SAPsim.run().

>>> from SAPsim import run
>>> run("ex1.csv")                  # Run 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 tests/public_prog/ex1.csv
...
Debug mode: press Enter to execute next instruction ( > ).
...

Note: There is a debug (step) mode that runs an instruction each time you press Enter, as shown above. The default behavior is to run at full speed.

SAP instruction set

Settings

To customize table appearance, use table_format. Options.

>>> run("ex1.csv", table_format="github")
| 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.

>>> run("ex1.csv", change={14: 4, 13: 2})      # Change initial byte at address 14 to 4 and at 13 to 2
┌──────┬────────┬───────────────┬───────┬───────┐
│ 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 2         │     2 │ 0x02  │
│      │     14 │ NOP 4         │     4 │ 0x04  │
│      │     15 │ NOP 0         │     0 │ 0x00  │
└──────┴────────┴───────────────┴───────┴───────┘
┌───────┬───┐
│ PC    │ 5 │
│ Reg A │ 0 │
│ Reg B │ 2 │
│ FlagC │ 1 │
│ FlagZ │ 0 │
└───────┴───┘

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