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, 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 Program

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

// 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;

// WELCOME SCRIPT

MOV C 0;

INPUT A;

STORE A [C];
ADD C 1;
INPUT A;
JNZ 2;          // If nothing in the input continue, else go back

// Welcome message

MOV D 'H';       // H
PRINTCH D -N;
MOV D 'e';      // e
PRINTCH D -N;
MOV D 'l';      // l
PRINTCH D -N;
PRINTCH D -N;
MOV D 111;      // o
PRINTCH D -N;
MOV D ',';       // ,
PRINTCH D -N;
MOV D 32;       //  
PRINTCH D -N;

// Hello, 

MOV D 0;
MOV A [D];
PRINTCH A -N;   // No line break
ADD D 1;
MOV B C;
SUB B D;
JNZ 20;

// Hello, (name)

HALT

// "16" bits factorial

MOV A 0        // A = 0 (high byte)
MOV B 1        // B = 1 (low byte)
MOV C 6        // C = 6 (or 2, 5, etc.)
MOV D B        // D = B
MUL D C        // D = B * C (low 8 bits)
STORE D [0]    // Store low byte
MULH D B C     // D = B * C (high 8 bits)
STORE D [1]    // Store high byte
MOV D A        // D = A
MUL D C        // D = A * C (low 8 bits)
ADD D [1]      // D = (A * C) + high byte of B * C
MOV A D        // A = new high byte
MOV B [0]      // B = new low byte
SUB C 1        // C--
LOOP 3 C       // Loop to instruction 3 if C != 0


// if 6 (just examples to know how to calculate)
PRINT A        // 2
PRINT B        // 208
// 256 * 2 = 512
// 512 + 208 = 720
// 6! = 720


HALT

// DRAWING A "BOX"

CLS;               // Clear the screen
MOV A 5;           // X = 5
MOV B 5;           // Y = 5
MOV C '#';         // Char = '#'
DRAW A B C;        // Draw '#' at (5, 5)

MOV A 10;          // X = 10
DRAW A B C;        // Draw '#' at (10, 5)

MOV B 10;          // Y = 10
DRAW A B C;        // Draw '#' at (10, 10)

MOV A 5;           // X = 5
DRAW A B C;        // Draw '#' at (5, 10)

RENDER;            // Render the screen
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.

   Or if no file is specified, it will run IDLE mode, where you can enter directly the instructions.

   -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 semicolon and can include comments starting with //. Refer to the example program 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

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.