107 lines
2.7 KiB
Markdown
107 lines
2.7 KiB
Markdown
|
# little computer 3 (LC-3) virtual machine
|
||
|
|
|
||
|
|
LC-3 is an assembly language designed to educate students about the inner workings of computers.
|
||
|
|
This project is a virtual machine implementation,
|
||
|
|
which can run programs designed to work on LC-3 hardware.
|
||
|
|
|
||
|
|
For more information, read the [blog post](https://www.jmeiners.com/lc3-vm/) that inspired this, written by Justin Meiners and Ryan Pendleton.
|
||
|
|
Also, the [LC-3 ISA specification](https://www.jmeiners.com/lc3-vm/supplies/lc3-isa.pdf)
|
||
|
|
may help to understand the code.
|
||
|
|
|
||
|
|
## usage
|
||
|
|
|
||
|
|
```bash
|
||
|
|
git clone https://github.com/dogeystamp/lc3-vm
|
||
|
|
cd lc3-vm
|
||
|
|
```
|
||
|
|
|
||
|
|
Sample programs are provided in the `programs/` directory.
|
||
|
|
`2048.obj` and `rogue.obj` are respectively from [Meiners](https://github.com/justinmeiners/lc3-rogue) and [Pendleton](https://github.com/rpendleton/lc3-2048).
|
||
|
|
Note that these are outdated compared to the latest versions on GitHub.
|
||
|
|
To run them, use the following commands:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cargo run -- programs/2048.obj
|
||
|
|
cargo run -- programs/rogue.obj
|
||
|
|
```
|
||
|
|
|
||
|
|
For extra information about using the lc3-vm command line, run
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cargo run -- --help
|
||
|
|
```
|
||
|
|
|
||
|
|
## gallery
|
||
|
|
|
||
|
|
2048:
|
||
|
|
```
|
||
|
|
+--------------------------+
|
||
|
|
| |
|
||
|
|
| |
|
||
|
|
| |
|
||
|
|
| 2 |
|
||
|
|
| |
|
||
|
|
| |
|
||
|
|
| |
|
||
|
|
| 2 |
|
||
|
|
| |
|
||
|
|
+--------------------------+
|
||
|
|
```
|
||
|
|
|
||
|
|
Rogue:
|
||
|
|
```
|
||
|
|
################## ############
|
||
|
|
################### ########
|
||
|
|
####################### #
|
||
|
|
######################## # #
|
||
|
|
###############################D
|
||
|
|
################################
|
||
|
|
################################
|
||
|
|
@ ##############################
|
||
|
|
# #############################
|
||
|
|
## ##########################
|
||
|
|
##### #########################
|
||
|
|
###### ########################
|
||
|
|
####### ######################
|
||
|
|
######### ###################
|
||
|
|
############ ## ##############
|
||
|
|
############# #############
|
||
|
|
```
|
||
|
|
|
||
|
|
## debugging
|
||
|
|
|
||
|
|
A debug option is available in the command line, which will print execution data to stderr.
|
||
|
|
This can be piped to a separate file, and viewed with `tail -f` in a separate terminal:
|
||
|
|
```bash
|
||
|
|
$ cargo run -- --debug programs/2048.obj 2>trace
|
||
|
|
|
||
|
|
# (separate terminal)
|
||
|
|
$ tail -f trace
|
||
|
|
|
||
|
|
PC: 0x3314, op: BR, params: 0x7fd
|
||
|
|
R0: 0x0
|
||
|
|
R1: 0x1fbc
|
||
|
|
R2: 0x0
|
||
|
|
R3: 0x0
|
||
|
|
R4: 0x0
|
||
|
|
R5: 0x3017
|
||
|
|
R6: 0x3ffc
|
||
|
|
R7: 0x32db
|
||
|
|
COND: 0x2 (Z)
|
||
|
|
```
|
||
|
|
|
||
|
|
Alternatively, you can attach to a VM with `rust-gdb`.
|
||
|
|
First, start a VM:
|
||
|
|
```
|
||
|
|
cargo run -- programs/2048.obj
|
||
|
|
```
|
||
|
|
|
||
|
|
Then, in a new terminal window:
|
||
|
|
```
|
||
|
|
# (separate terminal)
|
||
|
|
rust-gdb -p (pgrep lc3)
|
||
|
|
```
|
||
|
|
|
||
|
|
Helper utilities are available in `contrib/gdb_cmds.gdb`, along with instructions for using them.
|
||
|
|
These are provided as-is, with no guarantee that they will work well.
|