Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/rafael-santiago/cp-8

A minimalist CHIP-8 interpreter/emulator (ANSI/TERM).
https://github.com/rafael-santiago/cp-8

c chip8-emulator chip8-interpreter diycode emulator interpreter pure-c retrocomputing retroprogramming

Last synced: about 1 month ago
JSON representation

A minimalist CHIP-8 interpreter/emulator (ANSI/TERM).

Host: GitHub
URL: https://github.com/rafael-santiago/cp-8
Owner: rafael-santiago
License: gpl-2.0
Created: 2017-01-01T18:39:47.000Z (about 8 years ago)
Default Branch: master
Last Pushed: 2017-01-28T13:01:05.000Z (almost 8 years ago)
Last Synced: 2024-11-05T13:12:35.190Z (3 months ago)
Topics: c, chip8-emulator, chip8-interpreter, diycode, emulator, interpreter, pure-c, retrocomputing, retroprogramming
Language: C
Homepage:
Size: 205 KB
Stars: 1
Watchers: 3
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: COPYING

Awesome Lists containing this project

README

# CP-8

This code is a work in progress and yes, it is about a ``CHIP-8`` emulator that uses ``ANSI/TERM`` stuff to emulate
the screen output.

Well, here follows some ``CHIP-8 ROMs`` emulated with this software:

## How to clone this repo?

Well, I use some ``git-submodules`` here so:

```
watson@BakerStreet221B:~/src/clues/rafael-santiago# git clone \
> https://github.com/rafael-santiago/CP-8
watson@BakerStreet221B:~/src/clues/rafael-santiago# cd CP-8
watson@BakerStreet221B:~/src/clues/rafael-santiago/CP-8# git \
> submodule update --init
```

If the incantations above are trickier for you, try:

```
watson@BakerStreet221B:~/src/clues/rafael-santiago# git clone \
> https://github.com/rafael-santiago/CP-8 --recursive
```

Done.

## How to build it?

My code my rules. I use my own [build system](https://github.com/rafael-santiago/hefesto). Once ``Hefesto`` well-installed and working
on your system you should move to CP-8's ``src`` sub-directory and invoke ``hefesto`` from there... Something like:

```
watson@BakerStreet221B:~/src/clues/rafael-santiago/src/CP-8# cd src
watson@BakerStreet221B:~/src/clues/rafael-santiago/src/CP-8/src# hefesto
(...)
watson@BakerStreet221B:~/src/clues/rafael-santiago/src/CP-8/src# _
```

After invoking "hefesto" you will get the binary ``cp8`` under ``../bin`` sub-directory.

## How to install/uninstall it?

Firstly all should be done under ``src`` sub-directory and then...

### Install

```
watson@BakerStreet221B:~/src/clues/rafael-santiago/src/CP-8/src# hefesto --install
```

### Uninstall

```
watson@BakerStreet221B:~/src/clues/rafael-santiago/src/CP-8/src# hefesto --uninstall
```

Answer the questions confirming your choice and you will get this software installed on your environment.

## How to use it?

This application works based on tasks. So you need to inform the ``task`` and its ``--arguments=(...)``. Each task
requires its own specific arguments.

The ``emulate`` task is pretty obvious, you will use it to play the ``CHIP-8`` games on the following way:

```
sherlock@BakerStreet221B:~/src/clues/rafael-santiago/src/CP-8/src# ../bin/cp8 emulate \
> --rom=/home/sherlock/rom/PUZZLE
```

This emulation task does not re-map any key. However, you have some special keys, look the **Table 1**.

**Table 1**: Special keys recognized during an emulation task.

| **Key** | **Action** |
|:-------------------:|:------------------------------------:|
| ``R`` | Reset/Restart the ``ROM`` execution |
| ``P`` | Pause the ``ROM`` execution |
| ``ESC`` | Exit the program |

## Additional tasks

In spite of being mainly a ``CHIP-8`` emulator I have written some minor tasks for this software.
Here in this section you can find information about them.

### The umount task

This task should be useful to anyone who wants to probe the code of a ``CHIP-8 ROM``. Using it you are able
to disassemble the machine code.

The usage is pretty straightforward:

```
sherlock@BakerStreet221B:~/src/clues/rafael-santiago/src/CP-8/src# cp8 umount \
> --rom=/home/sherlock/rom/PUZZLE
```

The default output is the ``stdout`` if you want to spit the assembly mnemonics to another file:

```
sherlock@BakerStreet221B:~/src/clues/rafael-santiago/src/CP-8/src# cp8 umount \
> --rom=/home/sherlock/rom/PUZZLE --out=Elementary.c8
```

A "umounted" ``ROM`` looks like it:

```assembly
LD VA, 0x12
LD VB, 0x01
LD V1, 0x10
LD V2, 0x00
LD V0, 0x00
LD I, 0x2b0
DRW V1, V2, 0x7
LD F, V0
SE V0, 0x00
DRW VA, VB, 0x5
ADD V1, 0x08
ADD VA, 0x08
SE V1, 0x30
JP 0x224
LD V1, 0x10
ADD V2, 0x08
LD VA, 0x12
ADD VB, 0x08
LD I, 0x300
ADD I, V0
LD [I], V0
ADD V0, 0x01
SE V0, 0x10
JP 0x20a
LD VA, 0x12
LD VB, 0x01
LD VC, 0x00
LD V2, 0xff
RND V0, 0x06
ADD V0, 0x02
CALL 0x252
(...)
```

As you can see the ``CHIP-8 Assembly`` is pretty simple with a short processor's instruction set.

If you started to write code when people usually had to compile, worry about memory, program size, etc... You may know that is
not a good idea let a data chunk in the middle of a instruction chunk... Due to it this disassembler skips the first data
chunk when the first instruction is a jump. I said "data chunk" because in the old days was common you pick up a ``ROM`` with
some copyright disclaimer before the real program "text". Then a ``ROM`` that mixes data and instructions at random in any
place will produce a "screwed up" output. However, it is considered a bad practice and uncommon because it could be dangerous
in that days...

## Issues, limitations, known bugs, raptors, etc, .*

((( Coming soon... work in progress... )))