{"id":26889715,"url":"https://github.com/mrfavoslav/4bit-cpu-emulator","last_synced_at":"2026-05-05T05:32:14.149Z","repository":{"id":285360863,"uuid":"955583592","full_name":"mrFavoslav/4bit-cpu-emulator","owner":"mrFavoslav","description":"4bit CPU Emulator – A simple 4-bit processor emulator written in JavaScript. Run assembly code directly in your browser! Perfect for learning the basics of computer architecture and low-level programming.","archived":false,"fork":false,"pushed_at":"2025-03-31T08:59:42.000Z","size":26,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-31T09:36:27.734Z","etag":null,"topics":["4-bit-cpu","assembler","assembly","assembly-language","computer-architecture","cpu-design","cpu-emulator","educational","emulator","javascript","learning-tool","low-level-programming","open-source","programming","simulation","web-emulator"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mrFavoslav.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-26T21:45:32.000Z","updated_at":"2025-03-31T08:59:46.000Z","dependencies_parsed_at":"2025-03-31T09:36:30.742Z","dependency_job_id":"aabe0ae8-0dc9-4009-8a87-da310bd819e1","html_url":"https://github.com/mrFavoslav/4bit-cpu-emulator","commit_stats":null,"previous_names":["mrfavoslav/4bit-cpu-emulator"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrFavoslav%2F4bit-cpu-emulator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrFavoslav%2F4bit-cpu-emulator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrFavoslav%2F4bit-cpu-emulator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrFavoslav%2F4bit-cpu-emulator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mrFavoslav","download_url":"https://codeload.github.com/mrFavoslav/4bit-cpu-emulator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246540528,"owners_count":20793930,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["4-bit-cpu","assembler","assembly","assembly-language","computer-architecture","cpu-design","cpu-emulator","educational","emulator","javascript","learning-tool","low-level-programming","open-source","programming","simulation","web-emulator"],"created_at":"2025-03-31T21:19:12.946Z","updated_at":"2026-05-05T05:32:14.142Z","avatar_url":"https://github.com/mrFavoslav.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ⚠️ Disclaimer\n\n\u003e **This project is no longer actively maintained.**\n\u003e It was originally created as a small experimental/test project.\n\u003e At this point, it mainly serves as a reference for a future project where I plan to design and build a custom 8-bit CPU from scratch.\n\n---\n\n# 4-bit CPU Emulator\n\nWelcome 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.\n\nThis emulator is perfect for learning about low-level programming, CPU architecture, and how basic instructions are executed in a processor.\n\n---\n\n## Features\n\n- **4-bit and 8-bit Operation Modes**: Switch between 4-bit and 8-bit modes for different levels of complexity.\n- **Registers and Flags**: Simulates CPU registers (AX, BX, CX, etc.) and flags (Zero, Carry, Overflow, etc.).\n- **Memory Simulation**: 256 bytes of memory for program storage and execution.\n- **Instruction Set**: Supports a variety of instructions, including arithmetic, logical, jump, and bitwise operations.\n- **Program Control**: Load, run, step through, and reset programs with intuitive controls.\n- **Output LEDs**: Visualize the output of the CPU using LEDs.\n- **Interactive Debugging**: View and update registers, flags, and memory in real-time.\n\n---\n\n## Table of Contents\n\n1. [Getting Started](#getting-started)\n2. [Installation](#installation)\n3. [Usage](#usage)\n4. [Instruction Set](#instruction-set)\n5. [File Structure](#file-structure)\n6. [Contributing](#contributing)\n7. [License](#license)\n\n---\n\n## Getting Started\n\nThis 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.\n\n### Prerequisites\n\nTo run the emulator, you need:\n\n- A modern web browser (e.g., Chrome, Firefox, Edge).\n- Basic knowledge of assembly language and CPU architecture (optional but helpful).\n\n---\n\n## Installation\n\n1. Clone the repository to your local machine:\n\n   ```bash\n   git clone https://github.com/mrFavoslav/4bit-cpu-emulator.git\n   cd 4bit-cpu-emulator\n   ```\n\n2. Open the `cpu.html` file in your browser to start the emulator.\n\n---\n\n## Usage\n\n### Loading a Program\n\n1. Write your program in the `prog.ass` file using the supported instruction set.\n2. Click the **Load Program** button in the emulator interface to load the program into memory.\n\n### Running the Emulator\n\n- **Run**: Executes the program continuously until it halts or encounters an error.\n- **Step**: Executes the program one instruction at a time, allowing you to debug.\n- **Stop**: Halts the execution of the program.\n- **Reset**: Resets the CPU, memory, and program state.\n\n### Viewing the State\n\n- **Registers**: Displays the current values of all CPU registers.\n- **Flags**: Shows the status of the CPU flags (e.g., Zero, Carry).\n- **Memory**: Visualizes the contents of the 256-byte memory.\n- **Output LEDs**: Displays the output of the CPU in binary form using LEDs.\n\n---\n\n## Instruction Set\n\nHere’s the complete instruction set for the emulator:\n\n### Instruction Format\nEach instruction consists of an opcode and optional operands. The format varies based on the instruction type.\n\n### Registers\n- `AX` (AH:AL) - General purpose register\n- `BX` (BH:BL) - General purpose register\n- `CX` (CH:CL) - General purpose register\n- `DX` (DH:DL) - General purpose register\n- `MA` (MAH:MAL) #HIDDEN - Memory addressing\n- `DT` (DTH:DTL) #HIDDEN - Memory data transfer\n- `PC` (PH:PL) - Program Counter\n- `IR` (IH:IL) - Instruction Register\n\n### Flags\n- `CF` - Carry Flag\n- `ZF` - Zero Flag\n- `SF` - Sign Flag\n- `OF` - Overflow Flag\n- `PF` - Parity Flag\n- `IF` - Interrupt Flag\n- `MOP` - Memory Operation Mode (0 = 8-bit, 1 = 4-bit)\n\n### MOV (Move) Instructions\n| Opcode | Type | Description | Example |\n|--------|------|-------------|---------|\n| 0x01 00 | reg, reg | Move between registers | `MOV AX, BX` |\n| 0x01 01 | reg, [mem] | Move from memory to register | `MOV AX, [10]` |\n| 0x01 02 | [mem], reg | Move from register to memory | `MOV [10], AX` |\n| 0x01 03 | reg, #imm | Move immediate to register | `MOV AX, #42` |\n| 0x01 05 | [mem1], [mem2] | Move between memory locations | `MOV [10], [20]` |\n| 0x01 06 | [mem], #imm | Move immediate to memory | `MOV [10], #42` |\n\n### ADD Instructions\n| Opcode | Type | Description | Example |\n|--------|------|-------------|---------|\n| 0x02 00 | reg, reg | Add registers | `ADD AX, BX` |\n| 0x02 01 | reg, [mem] | Add memory to register | `ADD AX, [10]` |\n| 0x02 02 | [mem], reg | Add register to memory | `ADD [10], AX` |\n| 0x02 03 | reg, #imm | Add immediate to register | `ADD AX, #42` |\n| 0x02 05 | [mem1], [mem2] | Add memory locations | `ADD [10], [20]` |\n| 0x02 06 | [mem], #imm | Add immediate to memory | `ADD [10], #42` |\n\n### SUB (Subtract) Instructions\n| Opcode | Type | Description | Example |\n|--------|------|-------------|---------|\n| 0x03 00 | reg, reg | Subtract registers | `SUB AX, BX` |\n| 0x03 01 | reg, [mem] | Subtract memory from register | `SUB AX, [10]` |\n| 0x03 02 | [mem], reg | Subtract register from memory | `SUB [10], AX` |\n| 0x03 03 | reg, #imm | Subtract immediate from register | `SUB AX, #42` |\n| 0x03 05 | [mem1], [mem2] | Subtract memory locations | `SUB [10], [20]` |\n| 0x03 06 | [mem], #imm | Subtract immediate from memory | `SUB [10], #42` |\n\n### AND Instructions\n| Opcode | Type | Description | Example |\n|--------|------|-------------|---------|\n| 0x04 00 | reg, reg | AND registers | `AND AX, BX` |\n| 0x04 01 | reg, [mem] | AND memory with register | `AND AX, [10]` |\n| 0x04 02 | [mem], reg | AND register with memory | `AND [10], AX` |\n| 0x04 03 | reg, #imm | AND immediate with register | `AND AX, #42` |\n| 0x04 05 | [mem1], [mem2] | AND memory locations | `AND [10], [20]` |\n| 0x04 06 | [mem], #imm | AND immediate with memory | `AND [10], #42` |\n\n### OR Instructions\n| Opcode | Type | Description | Example |\n|--------|------|-------------|---------|\n| 0x05 00 | reg, reg | OR registers | `OR AX, BX` |\n| 0x05 01 | reg, [mem] | OR memory with register | `OR AX, [10]` |\n| 0x05 02 | [mem], reg | OR register with memory | `OR [10], AX` |\n| 0x05 03 | reg, #imm | OR immediate with register | `OR AX, #42` |\n| 0x05 05 | [mem1], [mem2] | OR memory locations | `OR [10], [20]` |\n| 0x05 06 | [mem], #imm | OR immediate with memory | `OR [10], #42` |\n\n### XOR Instructions\n| Opcode | Type | Description | Example |\n|--------|------|-------------|---------|\n| 0x06 00 | reg, reg | XOR registers | `XOR AX, BX` |\n| 0x06 01 | reg, [mem] | XOR memory with register | `XOR AX, [10]` |\n| 0x06 02 | [mem], reg | XOR register with memory | `XOR [10], AX` |\n| 0x06 03 | reg, #imm | XOR immediate with register | `XOR AX, #42` |\n| 0x06 05 | [mem1], [mem2] | XOR memory locations | `XOR [10], [20]` |\n| 0x06 06 | [mem], #imm | XOR immediate with memory | `XOR [10], #42` |\n\n### NOT Instructions\n| Opcode | Type | Description | Example |\n|--------|------|-------------|---------|\n| 0x07 00 | reg | NOT register | `NOT AX` |\n| 0x07 01 | [mem] | NOT memory | `NOT [10]` |\n\n### Jump Instructions\n| Opcode | Type | Description | Example |\n|--------|------|-------------|---------|\n| 0x08 00 | reg | Jump to register address | `JMP AX` |\n| 0x08 01 | [mem] | Jump to memory address | `JMP [10]` |\n| 0x08 03 | #imm | Jump to immediate address | `JMP #42` |\n\n### JZ (Jump if Zero) Instructions\n| Opcode | Type | Description | Example |\n|--------|------|-------------|---------|\n| 0x09 00 | reg | Jump if zero to register address | `JZ AX` |\n| 0x09 01 | [mem] | Jump if zero to memory address | `JZ [10]` |\n| 0x09 03 | #imm | Jump if zero to immediate address | `JZ #42` |\n\n### JC (Jump if Carry) Instructions\n| Opcode | Type | Description | Example |\n|--------|------|-------------|---------|\n| 0x0A 00 | reg | Jump if carry to register address | `JC AX` |\n| 0x0A 01 | [mem] | Jump if carry to memory address | `JC [10]` |\n| 0x0A 03 | #imm | Jump if carry to immediate address | `JC #42` |\n\n### SHL (Shift Left) Instructions\n| Opcode | Type | Description | Example |\n|--------|------|-------------|---------|\n| 0x0B 00 | reg, reg | Shift left register by register count | `SHL AX, BX` |\n| 0x0B 01 | reg, [mem] | Shift left register by memory count | `SHL AX, [10]` |\n| 0x0B 02 | [mem], reg | Shift left memory by register count | `SHL [10], AX` |\n| 0x0B 03 | reg, #imm | Shift left register by immediate count | `SHL AX, #2` |\n| 0x0B 05 | [mem1], [mem2] | Shift left memory by memory count | `SHL [10], [20]` |\n| 0x0B 06 | [mem], #imm | Shift left memory by immediate count | `SHL [10], #2` |\n\n### SHR (Shift Right) Instructions\n| Opcode | Type | Description | Example |\n|--------|------|-------------|---------|\n| 0x0C 00 | reg, reg | Shift right register by register count | `SHR AX, BX` |\n| 0x0C 01 | reg, [mem] | Shift right register by memory count | `SHR AX, [10]` |\n| 0x0C 02 | [mem], reg | Shift right memory by register count | `SHR [10], AX` |\n| 0x0C 03 | reg, #imm | Shift right register by immediate count | `SHR AX, #2` |\n| 0x0C 05 | [mem1], [mem2] | Shift right memory by memory count | `SHR [10], [20]` |\n| 0x0C 06 | [mem], #imm | Shift right memory by immediate count | `SHR [10], #2` |\n\n### CMP (Compare) Instructions\n| Opcode | Type | Description | Example |\n|--------|------|-------------|---------|\n| 0x0D 00 | reg, reg | Compare registers | `CMP AX, BX` |\n| 0x0D 01 | reg, [mem] | Compare register with memory | `CMP AX, [10]` |\n| 0x0D 02 | [mem], reg | Compare memory with register | `CMP [10], AX` |\n| 0x0D 03 | reg, #imm | Compare register with immediate | `CMP AX, #42` |\n| 0x0D 05 | [mem1], [mem2] | Compare memory locations | `CMP [10], [20]` |\n| 0x0D 06 | [mem], #imm | Compare memory with immediate | `CMP [10], #42` |\n\n### Special Instructions\n| Opcode | Description | Example |\n|--------|-------------|---------|\n| 0x00 | No Operation (NOP) | `NOP` |\n| 0xFF | Halt execution (HLT) | `HLT` |\n\n### Notes\n- All memory addresses are 8-bit (0-255)\n- Immediate values are 8-bit (0-255)\n- Register operations can be 4-bit or 8-bit depending on MOP flag\n- All arithmetic and logical operations update the flags automatically\n\n---\n\n## File Structure\n\n```\n4bit-cpu-emulator/\n├── .gitignore          # Files and directories to ignore in Git\n├── LICENSE             # License for the project\n├── README.md           # Project documentation\n├── cpu.html            # Main HTML file for the emulator interface\n├── emulator.js         # JavaScript implementation of the CPU emulator\n├── package.json        # Project metadata and dependencies\n├── package-lock.json   # Dependency lock file\n├── prog.ass            # Example program file (assembly-like language)\n```\n\n---\n\n## Contributing\n\nContributions are welcome! If you'd like to improve the emulator, fix bugs, or add new features, follow these steps:\n\n1. Fork the repository.\n2. Create a new branch for your feature or bugfix.\n3. Commit your changes and push them to your fork.\n4. Submit a pull request with a detailed description of your changes.\n\n---\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE). You are free to use, modify, and distribute this project as long as you include the original license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrfavoslav%2F4bit-cpu-emulator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrfavoslav%2F4bit-cpu-emulator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrfavoslav%2F4bit-cpu-emulator/lists"}