# chip8-in-c

**Repository Path**: ddaren/chip8-in-c

## Basic Information

- **Project Name**: chip8-in-c
- **Description**: 一个简单的 CHIP-8 模拟器。实现了运行、反汇编及汇编功能。
- **Primary Language**: C
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-12-23
- **Last Updated**: 2025-01-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Usage
- Get chip8:

```make```, then you got an executable file ```main``` in current directory.

- Run game:

```./main run GAMEFILE```

- Disassemble game:

```./main disassemble GAMEFILE```

- Assemble:

```./main assemble ASMFILE```

- Get Help:

```./main help```

# Dev
## Test
```make && make testall``` or ```make tasm0``` to test tasm0 test case.

# Instruction Set
## An Instruction
Example: 0NNN, 3XNN.

|Operand | Description |
|:---|:---|
|X|Virtual register (V0-VF)|
|Y|Virtual register (V0-VF)|
|N|4-bit nibble literal|
|NN|8-bit byte literal|
|NNN|12-bit literal address(typically a label)|

## CHIP-8 Instructions

|Opcode|Mnemonic|Description
|:---| :---|:---
|00E0	|CLS	    |Clear video memory
|00EE	|RET	    |Return from subroutine
|0NNN	|SYS NNN	|Call CDP1802 subroutine at NNN
|2NNN	|CALL NNN	|Call CHIP-8 subroutine at NNN
|1NNN	|JP NNN	    |Jump to address NNN
|BNNN	|JP V0, NNN	|Jump to address NNN + V0
|3XNN	|SE VX, NN	|Skip next instruction if VX == NN
|4XNN	|SNE VX, NN	|Skip next instruction if VX != NN
|5XY0	|SE VX, VY	|Skip next instruction if VX == VY
|9XY0	|SNE VX, VY	|Skip next instruction if VX != VY
|EX9E	|SKP VX	    |Skip next instruction if key(VX) is pressed
|EXA1	|SKNP VX	|Skip next instruction if key(VX) is not pressed
|FX0A	|LD VX, K	|Wait for key press, store key pressed in VX
|6XNN	|LD VX, NN	|VX = NN
|8XY0	|LD VX, VY	|VX = VY
|FX07	|LD VX, DT	|VX = DT
|FX15	|LD DT, VX	|DT = VX
|FX18	|LD ST, VX	|ST = VX
|ANNN	|LD I, NNN	|I = NNN
|FX29	|LD F, VX	|I = address of 4x5 font character in VX (0..F)
|FX55	|LD [I], VX	|Store V0..VX (inclusive) to memory starting at I; I remains unchanged
|FX65	|LD VX, [I]	|Load V0..VX (inclusive) from memory starting at I; I remains unchanged
|FX1E	|ADD I, VX	|I = I + VX; VF = 1 if I > 0xFFF else 0 
|7XNN	|ADD VX, NN	|VX = VX + NN 
|8XY4	|ADD VX, VY	|VX = VX + VY; VF = 1 if overflow else 0 
|8XY5	|SUB VX, VY	|VX = VX - VY; VF = 1 if not borrow else 0 
|8XY7	|SUBN VX, VY|VX = VY - VX; VF = 1 if not borrow else 0 
|8XY1	|OR VX, VY	|VX = VX OR VY 
|8XY2	|AND VX, VY	|VX = VX AND VY 
|8XY3	|XOR VX, VY	|VX = VX XOR VY 
|8XY6	|SHR VX, VY |VF = LSB(VX); VX = VX » 1; VX >>= VY. (see **Note)
|8XYE	|SHL VX, VY |VF = MSB(VX); VX = VX « 1; VX <<= VY
|FX33	|BCD VX	    |Store BCD representation of VX at I (100), I+1 (10), and I+2 (1); I remains unchanged
|CXNN	|RND VX, NN	|VX = RND() AND NN
|DXYN	|DRW VX, VY, N	|Draw 8xN sprite at I to VX, VY; VF = 1 if collision else 0

**Note: check out [this reference](https://github.com/mattmikolay/chip-8/wiki/Mastering-CHIP%E2%80%908) .

## Instructions added for the Super CHIP-8 (A.K.A. SCHIP-8/CHIP-48)

|Opcode	|Mnemonic   |Description
|:---   |:---       |:---
|00BN	|SCU N	    |Scroll up N pixels (N/2 pixels in low res mode)
|00CN	|SCD N	    |Scroll down N pixels (N/2 pixels in low res mode)
|00FB	|SCR	    |Scroll right 4 pixels (2 pixels in low res mode)
|00FC	|SCL	    |Scroll left 4 pixels (2 pixels in low res mode)
|00FD	|EXIT	    |Exit the interpreter; this causes the VM to infinite loop
|00FE	|LOW	    |Enter low resolution (64x32) mode; this is the default mode
|00FF	|HIGH	    |Enter high resolution (128x64) mode
|DXY0	|DRW VX, VY, 0	|Draw a 16x16 sprite at I to VX, VY (8x16 in low res mode)
|FX30	|LD HF, VX	|I = address of 8x10 font character in VX (0..F) (* see note)
|FX75	|LD R, VX	|Store V0..VX (inclusive) into HP-RPL user flags R0..RX (X < 8)
|FX85	|LD VX, R	|Load V0..VX (inclusive) from HP-RPL user flags R0..RX (X < 8)

## Instructions added for the CHIP-8E

| Opcode | Mnemonic      | Description
|:-------|:--------------|:---------------------------------------------------------------
| 5XY1   | SGT VX, VY    | Skip next instruction if VX > VY
| 5XY2   | SLT VX, VY    | Skip next instruction if VX < VY
| 9XY1   | MUL VX, VY    | VX * VY; VF contains the most significant byte, VX contains the least significant
| 9XY2   | DIV VX, VY    | VX / VY; VF contains the remainder and VX contains the quotient
| 9XY3   | BCD VX, VY    | Store BCD representation of the 16-bit word VX, VY (where VX is the most significant byte) at I through I+4; I remains unchanged
| FX94   | LD A, VX      | Load I with the font sprite of the 6-bit ASCII value found in VX; V0 is set to the symbol length 

# References
- [References on gitee](https://gitee.com/ddaren/chip-8-ref/wikis/Home)
- 较好的教程 [How to write an emulator (CHIP-8 interpreter)](https://multigesture.net/articles/how-to-write-an-emulator-chip-8-interpreter/) ([中文版](https://blog.csdn.net/korekara88730/article/details/50987930))
- [A simple CHIP-8 emulator written in C using SDL2](https://github.com/cj1128/chip8-emulator) | [文字说明](https://cjting.me/2020/06/07/chip8-emulator/)
- [Chip-8 technical reference](https://github.com/mattmikolay/chip-8/wiki/CHIP%E2%80%908-Technical-Reference)
- [Mastering CHIP-8](https://github.com/mattmikolay/chip-8/wiki/Mastering-CHIP%E2%80%908)
- 好！[A chip-8 assembler and emulator in go](https://massung.github.io/CHIP-8/)
- [Cowgod’s Chip-8 Technical Reference v1.0](http://devernay.free.fr/hacks/chip8/C8TECH10.HTM)
- [Chip-8 Games Pack](https://www.zophar.net/pdroms/chip8/chip-8-games-pack.html)
- [Chip-8 Emulator in javascript](https://github.com/alexanderdickson/Chip-8-Emulator)
- [David Winter’s CHIP-8 emulation page](http://www.pong-story.com/chip8/)
- [Super Chip8 SUPER-CHIP v1.1](http://devernay.free.fr/hacks/chip8/schip.txt)
- [How To Write a Computer Emulator](https://fms.komkon.org/EMUL8/HOWTO.html)
- [A simple emulation project: Chip 8](https://multigesture.net/wp-content/uploads/mirror/goldroad/chip8.shtml)
- [emubook](http://emubook.emulation64.com)
- [Tutorials collection](https://multigesture.net/wp-content/uploads/mirror/zenogais/Tutorials.htm)