This project implements a simple virtual machine in Rust, inspired by mattbattwings' Minecraft Redstone Computer.

Original GitHub Repository: https://github.com/mattbatwings/BatPU-2

The VM supports several IO devices for interacting with programs and visualizing output:

• Character Display:

  • Allows output of ASCII characters to a virtual display.
  • Useful for printing text or debugging output from your program.
  • Accessed via memory-mapped IO addresses (see code for details).

• Number Display:

  • Displays numeric values (e.g., register or memory contents) in decimal or hexadecimal.
  • Useful for debugging or showing program results.

• Screen Device:

  • Provides a pixel-based display for graphical output.
  • Programs can write to the screen buffer to draw simple graphics or animations.

• Random Number Generator (RNG):

  • Provides random values for use in games or randomized algorithms.
  • Accessed via a special memory-mapped address.

To use these devices, write to or read from their designated memory-mapped addresses in your assembly program. See the io_devices/ module and example programs in programs/ for usage patterns.

• Parser:

  • Parses assembly-like instructions with support for labels, definitions, and robust error handling (missing/extra operands, invalid instructions, undefined labels, file errors).
  • Pseudoinstructions (e.g., INC, DEC, CMP) are expanded automatically.

• Arithmetic Logic Unit (ALU):

  • Operates on 8-bit values using a custom Bits struct (array of booleans).
  • Implements a carry-cancel adder (CCA) and supports bitwise/arithmetic ops.
  • Sets flags (zero, carry) for conditional branching.

• Register Bank:

  • Dual-read register bank with 16 registers, supporting read/write, enable/disable, and validation logic.

• Instruction Memory:

  • Stores up to 1024 instructions, each as a Bits<16>.

• Control ROM:

  • Decodes opcodes into control signals for the VM.

• Program Counter (PC):

  • Tracks the address of the current instruction.
  • Increments after each instruction unless modified by control logic (e.g., halt, jump, call/return).

• Comprehensive unit tests for all major modules (ALU, bits, parser, register, instruction memory, VM execution).
• Tests are organized by feature and error type.
• Code coverage is measured using cargo llvm-cov.

The VM supports a simple assembly-like language, where each instruction consists of an opcode followed by its operands (registers, immediate values, or memory addresses). Instructions are space-separated and support labels for control flow. For a detailed list of supported opcodes, their syntax, and binary layouts, refer to the tables below or consult the BatPU-2 ISA documentation and mattbattwings' playlist.

The assembler provides robust error handling for invalid instructions, missing or extra operands, and undefined labels. Pseudoinstructions (such as INC, DEC, CMP, etc.) are automatically expanded to real instructions during parsing, making it easier to write concise and readable assembly code.

See the tables below for a summary of supported instructions, pseudoinstructions, and branching conditions.

Below are the supported instructions and their syntax:

Pseudoinstructions:

Some instructions are provided as convenient pseudocode and are automatically expanded to real instructions during parsing:

BRH Supported Conditions:

• Labels:

  • Define labels in your assembly code using .label (either on their own line or inline with an instruction).
  • Branch/Jump/Call instructions (BRH/JMP/CAL) can use labels as targets.
  • Labels above comments or blank lines are resolved to the next instruction.

Notes:

• Registers: r0–r15 (with r0 as a zero register: always reads as 0, writes are ignored).
• Immediate values (for LDI) must fit in 8 bits.
• All instructions and operands are space-separated.
• Extra or missing operands will result in a parse error.
• CAL and RET provide basic subroutine call/return support (call stack max depth: 16).

1. Write your program in assembly-like syntax (see examples in programs/).
2. Run the VM using the provided API in lib.rs.
3. Inspect register and memory state using the display function of the register file, or visualize output using the screen device.

Run all tests:

cargo test

Generate a coverage report using cargo llvm-cov that opens in your browser:

cargo llvm-cov --open

To view code coverage directly in VS Code gutters, install the Coverage Gutters extension. After generating a coverage report (e.g., lcov.info), open your project in VS Code and use Coverage Gutters to visualize coverage in the editor.

cargo llvm-cov --lcov --output-path lcov.info

This project is licensed under the MIT License. See the license file for details.