How damiramirez/lc3-vm-rust works
Main Components
• Entry Point (main.rs): Acts as the startup script that initializes the Virtual Machine.
• CPU Module (cpu.rs): Simulates the central processing unit. This module is likely responsible for interpreting the opcodes, managing the execution cycle, and applying instructions.
• Memory Module (memory.rs): Represents the system’s memory where the program (object code) is loaded and manipulated.
• Flags Module (flags.rs): Manages status flags (likely conditions from executed instructions, such as negative, zero, positive) used by the CPU during instruction evaluation.
• Opcode Module (opcode.rs): Defines the supported LC3 instructions and their behavior.
• Examples: The object files (e.g., 2048.obj, hello-world.obj) that serve as input programs to run on the VM.
• Build & Run Tools: Cargo.toml and Makefile indicate how the project is built and executed.
Relationships and Interactions
• The entry point (main.rs) orchestrates the initialization of the VM. It loads an object file from the examples directory based on the user's input.
• Once the program is loaded, the CPU module begins its fetch-decode-execute cycle:
• The CPU fetches instructions from the memory module.
• It uses the opcode definitions (from opcode.rs) to decode each instruction.
• It applies the instruction while updating statuses in the flags module as needed.
• The memory module both provides storage for the program code/data and acts as the runtime environment for operations.
• The entire flow is demonstrated through example object files, which are run using the make commands highlighted in the README.
Architectural Patterns and Design Principles
• Modular Design: Each major function is split into separate files (e.g., cpu.rs, memory.rs) allowing for clearer separation of concerns and easier testing.
• Instruction Cycle Model: The overall structure resembles a classic fetch-decode-execute cycle typical in virtual machine or emulator architectures.
• Educational/Proof-of-Concept: The overall design serves to illustrate the operation of a CPU in a controlled, simplified setting.
Including Specific Technologies and Tools
• Rust: The language of implementation, emphasizing safety and performance.
• Cargo & Makefile: Used for dependency management and execution. The Makefile facilitates running individual examples or the main demonstration.
• Example Programs: They serve as test cases to validate the VM’s correct implementation of the LC3 instruction set.