LC-3-rs

An LC-3 virtual machine, implemented in Rust. Most features are implemented with a couple of exceptions, see Missing Features.

Example Usage

Running a program

cargo run -r --bin lc3-cli --all-features -- run examples/hello2.obj

Progress

Feature	Info
Virtual Machine	✅
Assembler	🚧
Disassembler	soon™️
C Compiler	soon™️

• Assembler is very basic at the moment, not ready yet.

References

• Introduction To Computing Systems: From Bits & Gates To C/C++ & Beyond (3rd Edition)

• https://www.jmeiners.com/lc3-vm/supplies/lc3-isa.pdf (pretty good source)

• https://en.wikipedia.org/wiki/Little_Computer_3 (A little inaccurate, and missing key information)

Virtual Machine

Instructions

Instruction	Implemented
ADD	✅
AND	✅
BR	✅
JMP	✅
JSR	✅
JSRR	✅
LD	✅
LDI	✅
LDR	✅
LEA	✅
NOT	✅
RET	✅
RTI	✅
ST	✅
STI	✅
STR	✅
*TRAP	✅
**reserved	✅

* not all standard TRAP vectors are implemented
** reserved causes an exception when used (which is handled by the OS, and the behavior can be changed by modifying the interrupt vector and/or its implementation)

Other VM features

Feature	Status
Interrupts/Exceptions	✅
*Memory Protection	✅
Memory Device IO Callbacks for external bindings	✅
Keyboard status and data register	✅
Display status and data register	✅

• Memory protection relies on how the interrupt is handled. If the default OS is removed, strange behavior may occur if not handled correctly.

Missing features

• Virtual Machine
  • putsp TRAP vector
  • And maybe a few other things.
• Assembler
  • Revamp error messages (completely terrible at the moment)
  • Raw output format planned (currently outputs the same format as LC3Tools, without symbols or debug)
  • Linking