Rust implementation of Little Computer 3 (LC-3) as a virtual machine.

Go to file

dogeystamp e87e9bb233 chore: format		2024-01-20 15:38:00 -05:00
contrib	fix NOT logical error	2024-01-20 12:56:21 -05:00
programs	cleanup for upload on GitHub	2024-01-20 13:53:55 -05:00
src	chore: format	2024-01-20 15:38:00 -05:00
.gitignore	implemented register getter/setter	2024-01-04 22:29:34 -05:00
Cargo.lock	add proper arg parsing	2024-01-14 20:57:14 -05:00
Cargo.toml	add proper arg parsing	2024-01-14 20:57:14 -05:00
LICENSE	cleanup for upload on GitHub	2024-01-20 13:53:55 -05:00
README.md	cleanup for upload on GitHub	2024-01-20 13:53:55 -05:00
TODO.txt	added extras	2024-01-20 12:58:35 -05:00

README.md

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.