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 that inspired this, written by Justin Meiners and Ryan Pendleton. Also, the LC-3 ISA specification may help to understand the code.

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 and Pendleton. Note that these are outdated compared to the latest versions on GitHub. To run them, use the following commands:

cargo run -- programs/2048.obj cargo run -- programs/rogue.obj

For extra information about using the lc3-vm command line, run

cargo run -- --help

2048:

+--------------------------+ | | | | | | | 2 | | | | | | | | 2 | | | +--------------------------+ 

Rogue:

################## ############ ################### ######## ####################### # ######################## # # ###############################D ################################ ################################ @ ############################## # ############################# ## ########################## ##### ######################### ###### ######################## ####### ###################### ######### ################### ############ ## ############## ############# ############# 

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:

$ 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.