4-bit CPU Emulator

Welcome to the 4-bit CPU Emulator! This project is a web-based emulator for a simple CPU that supports both 4-bit and 8-bit operations. It allows you to load, execute, and debug programs in a simulated environment with features like registers, flags, memory, and output LEDs.

This emulator is perfect for learning about low-level programming, CPU architecture, and how basic instructions are executed in a processor.

---

Features

• 4-bit and 8-bit Operation Modes: Switch between 4-bit and 8-bit modes for different levels of complexity.
• Registers and Flags: Simulates CPU registers (AX, BX, CX, etc.) and flags (Zero, Carry, Overflow, etc.).
• Memory Simulation: 256 bytes of memory for program storage and execution.
• Instruction Set: Supports a variety of instructions, including arithmetic, logical, jump, and bitwise operations.
• Program Control: Load, run, step through, and reset programs with intuitive controls.
• Output LEDs: Visualize the output of the CPU using LEDs.
• Interactive Debugging: View and update registers, flags, and memory in real-time.

---

Table of Contents

1. Getting Started
2. Installation
3. Usage
4. Instruction Set
5. File Structure
6. Contributing
7. License

---

Getting Started

This emulator runs directly in your browser. You can use it to load and execute programs written in a simple assembly-like language. The interface provides real-time feedback on the state of the CPU, including registers, flags, and memory.

Prerequisites

To run the emulator, you need:

• A modern web browser (e.g., Chrome, Firefox, Edge).
• Basic knowledge of assembly language and CPU architecture (optional but helpful).

---

Installation

1. Clone the repository to your local machine:

   git clone https://github.com/mrFavoslav/4bit-cpu-emulator.git
   cd 4bit-cpu-emulator

2. Open the cpu.html file in your browser to start the emulator.

---

Usage

Loading a Program

1. Write your program in the prog.ass file using the supported instruction set.
2. Click the Load Program button in the emulator interface to load the program into memory.

Running the Emulator

• Run: Executes the program continuously until it halts or encounters an error.
• Step: Executes the program one instruction at a time, allowing you to debug.
• Stop: Halts the execution of the program.
• Reset: Resets the CPU, memory, and program state.

Viewing the State

• Registers: Displays the current values of all CPU registers.
• Flags: Shows the status of the CPU flags (e.g., Zero, Carry).
• Memory: Visualizes the contents of the 256-byte memory.
• Output LEDs: Displays the output of the CPU in binary form using LEDs.

---

Instruction Set

Here’s the complete instruction set for the emulator:

Instruction Format

Each instruction consists of an opcode and optional operands. The format varies based on the instruction type.

Registers

• AX (AH:AL) - General purpose register
• BX (BH:BL) - General purpose register
• CX (CH:CL) - General purpose register
• DX (DH:DL) - General purpose register
• MA (MAH:MAL) #HIDDEN - Memory addressing
• DT (DTH:DTL) #HIDDEN - Memory data transfer
• PC (PH:PL) - Program Counter
• IR (IH:IL) - Instruction Register

Flags

• CF - Carry Flag
• ZF - Zero Flag
• SF - Sign Flag
• OF - Overflow Flag
• PF - Parity Flag
• IF - Interrupt Flag
• MOP - Memory Operation Mode (0 = 8-bit, 1 = 4-bit)

MOV (Move) Instructions

Opcode	Type	Description	Example
0x01 00	reg, reg	Move between registers	MOV AX, BX
0x01 01	reg, [mem]	Move from memory to register	MOV AX, [10]
0x01 02	[mem], reg	Move from register to memory	MOV [10], AX
0x01 03	reg, #imm	Move immediate to register	MOV AX, #42
0x01 05	[mem1], [mem2]	Move between memory locations	MOV [10], [20]
0x01 06	[mem], #imm	Move immediate to memory	MOV [10], #42

ADD Instructions

Opcode	Type	Description	Example
0x02 00	reg, reg	Add registers	ADD AX, BX
0x02 01	reg, [mem]	Add memory to register	ADD AX, [10]
0x02 02	[mem], reg	Add register to memory	ADD [10], AX
0x02 03	reg, #imm	Add immediate to register	ADD AX, #42
0x02 05	[mem1], [mem2]	Add memory locations	ADD [10], [20]
0x02 06	[mem], #imm	Add immediate to memory	ADD [10], #42

SUB (Subtract) Instructions

Opcode	Type	Description	Example
0x03 00	reg, reg	Subtract registers	SUB AX, BX
0x03 01	reg, [mem]	Subtract memory from register	SUB AX, [10]
0x03 02	[mem], reg	Subtract register from memory	SUB [10], AX
0x03 03	reg, #imm	Subtract immediate from register	SUB AX, #42
0x03 05	[mem1], [mem2]	Subtract memory locations	SUB [10], [20]
0x03 06	[mem], #imm	Subtract immediate from memory	SUB [10], #42

AND Instructions

Opcode	Type	Description	Example
0x04 00	reg, reg	AND registers	AND AX, BX
0x04 01	reg, [mem]	AND memory with register	AND AX, [10]
0x04 02	[mem], reg	AND register with memory	AND [10], AX
0x04 03	reg, #imm	AND immediate with register	AND AX, #42
0x04 05	[mem1], [mem2]	AND memory locations	AND [10], [20]
0x04 06	[mem], #imm	AND immediate with memory	AND [10], #42

OR Instructions

Opcode	Type	Description	Example
0x05 00	reg, reg	OR registers	OR AX, BX
0x05 01	reg, [mem]	OR memory with register	OR AX, [10]
0x05 02	[mem], reg	OR register with memory	OR [10], AX
0x05 03	reg, #imm	OR immediate with register	OR AX, #42
0x05 05	[mem1], [mem2]	OR memory locations	OR [10], [20]
0x05 06	[mem], #imm	OR immediate with memory	OR [10], #42

XOR Instructions

Opcode	Type	Description	Example
0x06 00	reg, reg	XOR registers	XOR AX, BX
0x06 01	reg, [mem]	XOR memory with register	XOR AX, [10]
0x06 02	[mem], reg	XOR register with memory	XOR [10], AX
0x06 03	reg, #imm	XOR immediate with register	XOR AX, #42
0x06 05	[mem1], [mem2]	XOR memory locations	XOR [10], [20]
0x06 06	[mem], #imm	XOR immediate with memory	XOR [10], #42

NOT Instructions

Opcode	Type	Description	Example
0x07 00	reg	NOT register	NOT AX
0x07 01	[mem]	NOT memory	NOT [10]

Jump Instructions

Opcode	Type	Description	Example
0x08 00	reg	Jump to register address	JMP AX
0x08 01	[mem]	Jump to memory address	JMP [10]
0x08 03	#imm	Jump to immediate address	JMP #42

JZ (Jump if Zero) Instructions

Opcode	Type	Description	Example
0x09 00	reg	Jump if zero to register address	JZ AX
0x09 01	[mem]	Jump if zero to memory address	JZ [10]
0x09 03	#imm	Jump if zero to immediate address	JZ #42

JC (Jump if Carry) Instructions

Opcode	Type	Description	Example
0x0A 00	reg	Jump if carry to register address	JC AX
0x0A 01	[mem]	Jump if carry to memory address	JC [10]
0x0A 03	#imm	Jump if carry to immediate address	JC #42

SHL (Shift Left) Instructions

Opcode	Type	Description	Example
0x0B 00	reg, reg	Shift left register by register count	SHL AX, BX
0x0B 01	reg, [mem]	Shift left register by memory count	SHL AX, [10]
0x0B 02	[mem], reg	Shift left memory by register count	SHL [10], AX
0x0B 03	reg, #imm	Shift left register by immediate count	SHL AX, #2
0x0B 05	[mem1], [mem2]	Shift left memory by memory count	SHL [10], [20]
0x0B 06	[mem], #imm	Shift left memory by immediate count	SHL [10], #2

SHR (Shift Right) Instructions

Opcode	Type	Description	Example
0x0C 00	reg, reg	Shift right register by register count	SHR AX, BX
0x0C 01	reg, [mem]	Shift right register by memory count	SHR AX, [10]
0x0C 02	[mem], reg	Shift right memory by register count	SHR [10], AX
0x0C 03	reg, #imm	Shift right register by immediate count	SHR AX, #2
0x0C 05	[mem1], [mem2]	Shift right memory by memory count	SHR [10], [20]
0x0C 06	[mem], #imm	Shift right memory by immediate count	SHR [10], #2

CMP (Compare) Instructions

Opcode	Type	Description	Example
0x0D 00	reg, reg	Compare registers	CMP AX, BX
0x0D 01	reg, [mem]	Compare register with memory	CMP AX, [10]
0x0D 02	[mem], reg	Compare memory with register	CMP [10], AX
0x0D 03	reg, #imm	Compare register with immediate	CMP AX, #42
0x0D 05	[mem1], [mem2]	Compare memory locations	CMP [10], [20]
0x0D 06	[mem], #imm	Compare memory with immediate	CMP [10], #42

Special Instructions

Opcode	Description	Example
0x00	No Operation (NOP)	NOP
0xFF	Halt execution (HLT)	HLT

Notes

• All memory addresses are 8-bit (0-255)
• Immediate values are 8-bit (0-255)
• Register operations can be 4-bit or 8-bit depending on MOP flag
• All arithmetic and logical operations update the flags automatically

---

File Structure

4bit-cpu-emulator/
├── .gitignore          # Files and directories to ignore in Git
├── LICENSE             # License for the project
├── README.md           # Project documentation
├── cpu.html            # Main HTML file for the emulator interface
├── emulator.js         # JavaScript implementation of the CPU emulator
├── package.json        # Project metadata and dependencies
├── package-lock.json   # Dependency lock file
├── prog.ass            # Example program file (assembly-like language)

---

Contributing

Contributions are welcome! If you'd like to improve the emulator, fix bugs, or add new features, follow these steps:

1. Fork the repository.
2. Create a new branch for your feature or bugfix.
3. Commit your changes and push them to your fork.
4. Submit a pull request with a detailed description of your changes.

---

License

This project is licensed under the MIT License. You are free to use, modify, and distribute this project as long as you include the original license.