An LLM Assisted Disassembler

Introduction

This repository contains the source code for the Chipstral project, created for the Mistral AI Hackathon.

CHIP-8 is a simple interpreted programming language developed in the 1970s, designed to provide an easy way to write video games 8-bit microcomputer.

The Chipstral project integrates both a CHIP-8 disassembler and an emulator.

The disassembler leverages a fine-tuned version of the Mistral 7B language model to decode original CHIP-8 instructions and transcribe them into an assembly file.

The produced assembly files are compatible with the emulator, which executes the code and updates the machine's state in real-time, allowing original ROMs to be played.

How It Was Built

A dataset of 68K entries was created by generating random CHIP-8 instructions. For each entry, the expected outcome is the disassembly code, derived from the technical reference. Python was chosen as the disassembly language to facilitate direct interpretation by the emulator.

A Mistral-7b model was then fine-tuned on this dataset using the La Plateforme API.

The training and validation datasets are available at 🤗 Hugging Face.

Setup Instructions

To get started, first create a virtual environment and install the necessary dependencies:

pip install -r requirements.txt

Next, open the .env file and replace MISTRAL_API_KEY with your actual Mistral API key.

To launch the disassembler, use the following command. Add the --debug flag for debugging mode:

python run_disassembler.py roms/Chipstral.ch8 [--debug]

To launch the emulator, use the following command. Add the --debug flag for debugging mode:

python run_emulator.py roms/Chipstral.chs [--debug]

To generate the datasets, use the following command:

python dataset/generate_dataset.py

ROMs

A custom ROM was developed for this project using Octo. The source code is available in the project as Chipstral.8o.

Other ROMs included in this project are sourced from the chip8 repository.