hex-instruction-compiler

A TypeScript library for compiling, decoding, and simulating MIPS v6 hexadecimal instruction programs. Supports single-cycle execution, basic pipelined execution, and hazard-aware pipelined execution with forwarding and stall detection.

Overview

hex-instruction-compiler takes a space-separated string of hexadecimal instruction words and runs them through a MIPS v6 processor model. The library exposes a clean public API so consumers can:

1. Parse a hex program string into a Program structure.
2. Choose a runner — single-cycle, basic pipeline, or hazard-aware pipeline.
3. Inspect the output — final register state, cycle count, and execution time.

The processor model implements the classic five-stage pipeline: Fetch → Decode → Execute → Memory Access → Write-back. The hazard-aware runner additionally handles RAW data hazards through register forwarding and pipeline stalls, and clears in-flight instructions on branches/jumps.

Supported runners at a glance:

Runner	Function	Description
Single-cycle	singleCycleRun	One instruction per cycle, no pipeline overlap
Basic pipeline	pipelineRun	Five-stage pipeline, no hazard protection
Hazard-aware pipeline	pipelineHazardRun	Pipeline with forwarding, stalls, and flush

---

Development Team

Developers

Juan Borja
Samuel Camargo
Fatima Castro
Juan Rojas

QA / Testing

Oscar Gil
Jean Marthe
Alberto Niebles
Valentina Schotborgh

---

Documentation

• DOCS.md
• TESTING.md

---

Credits

This project was developed under the guidance and support of Augusto Salazar Silva.