e8Bit Emulator

This project is a simple 8-bit virtual machine (VM) emulator written in Rust. It simulates a basic CPU with registers, memory, and a set of instructions for performing arithmetic, memory operations, and control flow.

Features

• Registers: Five general-purpose 8-bit registers (A, B, C, D, E).
• Memory: 256 bytes of memory.
• Instruction Set:
  • Arithmetic: ADD, SUB, MUL, DIV, MOD, MULH
  • Data Movement: MOV, STORE
  • Memory Access: Supports [0], [A], [B], etc.
  • Control Flow: JMP, JZ, JNZ, LOOP
  • Input/Output: INPUT, PRINT, PRINTCH
  • Program Termination: HALT
  • Screen Operations: DRAW, CLS, RENDER
  • Comparison: CMP
• Zero Flag: Indicates whether the result of the last operation is zero, often used for conditional branching or logical evaluations. Comparisons evaluate to false (non-zero) or true (zero), enabling conditional logic.
• Custom Parsing: Accepts comments (//) and instruction separation via ; or by lines.
• Character Literals: Supports character literals in instructions, e.g., MOV A 'p'. Characters are internally treated as their ASCII numeric values and must fit within 8 bits (0–255), just like any other number.
• Debug Mode: Optional debug mode for detailed output during execution.
• IDLE Mode: Allows direct input of instructions for testing and debugging.
• Screen Rendering: Supports drawing characters on an 80 by 25 virtual screen and rendering it to the console.

Example Programs

The files example.e8, example2.e8, example3.e8, example4.e8, example5.e8, example6.e8, example7.e8, and others contain example programs that demonstrate the use of registers, arithmetic operations, memory storage, loops, and conditional logic.

Even or Odd Example:

// EVEN OR ODD

INPUT A     // get number from user input
MOD A 2     // get remainder of A divided by 2
CMP A 0     // compare A with 0, if true, zero flag set to true
JZ 10        // EVEN (jump to 10th instruction if zero)

MOV C 'O'   // ODD
PRINTCH C -N
MOV C 'D'
PRINTCH C -N
PRINTCH C -N
JMP 18

MOV C 'E'   // EVEN (10 index)
PRINTCH C -N
MOV C 'V'
PRINTCH C -N
MOV C 'E'
PRINTCH C -N
MOV C 'N'
PRINTCH C -N

HALT        // end program

Factorial Example:

// FACTORIAL SCRIPT

// registers
MOV A 1;           // A = 1 (result)
MOV B 5;           // B = 5 (number to get factorial)

// loop starts here (index 2)
MUL A B;           // A *= B
SUB B 1;           // B -= 1
LOOP 2 B;           // if B != 0 go to index 2 (MUL A B)

// END
PRINT A;           // shows result
HALT;

...

How to Run

1. Install Rust: Ensure you have Rust installed. You can download it from rust-lang.org.

2. Compile the Program:

   cargo build --release
   

3. Run the Emulator:

   cargo run example.e8 -d
   

   Replace example.e8 with the path to your program file.

   If no file is specified, it will run in IDLE mode, where you can enter instructions directly.

   The -d flag is optional and enables debug mode, which provides additional output for debugging purposes.

How to Write Programs

Programs for the emulator are written in a custom assembly-like language. Each instruction is written on a new line or separated by a semicolon and can include comments starting with //. Refer to the example programs above for syntax.

Instruction Set

Args Types

Note: Square brackets ([]) are used to specify memory addresses. For example:

• MOV A [0] loads the value from memory address 0 into register A.
• STORE A [0] stores the value of register A into memory address 0.

Args Types Supported

Tips

• Use the MOD instruction to easily check for even/odd numbers or perform modular arithmetic.
• The CMP instruction is useful for conditional branching with JZ and JNZ.
• Use PRINTCH for ASCII output and PRINT for numeric output.
• The virtual screen is 80 columns by 25 rows; use DRAW, CLS, and RENDER for simple graphics.

Future Improvements

• Add support for more instructions.
• Implement debugging tools.
• Enhance error handling for invalid programs.

License

This project is open-source and available under the MIT License.