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

usage

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

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:

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