GammaCPU

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 14 Open GitHub ↗

VHDL-based CPU which supports running raw WASM instructions.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# GammaCPU

GammaCPU is a simple, 32-bit, stack-based CPU implemented in VHDL. It is designed to execute a subset of the **WebAssembly (WASM) instruction set**, focusing on 32-bit integer operations.

The project follows a modular design, separating the core CPU logic, the Arithmetic Logic Unit (ALU), and the data stack into distinct, testable components. A Python-based test runner is included to automate the simulation and verification process using GHDL.

## Project Components

The project is structured into several key files:

-   `GammaCPU.vhdl`: The top-level CPU entity. It implements a state machine for the fetch-decode-execute cycle, orchestrating interactions between the ALU and the stack to process instructions.
-   `GammaALU.vhdl`: The Arithmetic Logic Unit. This component is responsible for all computational tasks, including arithmetic, comparison, bitwise, and shift/rotate operations.
-   `GammaStack.vhdl`: A 32-entry, 32-bit wide descending stack. It is used to store operands for the ALU and the results of computations.
-   `run.py`: A Python script that acts as a test runner. It automatically analyzes and elaborates the VHDL source files, runs all testbenches found in the `test/` directory, and reports a summary of the results.
-   `clean.py`: A utility script to remove simulation artifacts and log files (`.vcd`, `.cf`, `.o`, `.txt`, etc.).
-   `test/`: A directory containing testbenches for each module (`cpu`, `alu`, `stack`) to ensure correctness.

## Architecture Overview

-   **Stack-Based Machine**: Instructions operate on values popped from the top of the stack, and the result is pushed back onto the stack. For example, `i32.add` pops two values, adds them, and pushes the sum.
-   **State Machine**: The `GammaCPU` is controlled by a multi-state state machine that implements the instruction pipeline: `Fetch`, `Decode`, `Execute`, `StackOperation`, and other intermediate states. The state machine handles operand fetching from the stack, enabling the ALU, and pushing results.
-   **Instruction Format**: The CPU decodes instructions based on the most significant byte (`instruction(31 downto 24)`). For immediate instructions like `i32.const`, the value is embedded in the lower bytes of the instruction word.

## Supported WASM Instructions

The GammaCPU currently supports the following 32-bit integer instructions:

## How to Use

### Prerequisites

-   **GHDL**: A VHDL simulator. The scripts are written for GHDL. You can find installation instructions on the [GHDL website](https://ghdl.github.io/ghdl/getting.html).
-   **Python 3**: To run the helper scripts (`run.py`, `clean.py`).

### Running the Tests

To compile the VHDL code and run the entire test suite, execute the `run.py` script:

```bash
python3 run.py
```

The script will:
1.  Analyze all `.vhdl` source files in the root directory.
2.  Recursively search the `test/` directory for testbenches.
3.  For each testbench found:
    -   Analyze, elaborate, and run the simulation.
    -   Generate a waveform file (`.vcd`) and a simulation log (`simulation_output.txt`) in the test's directory.
    -   Check the output for test failures.
4.  Print a summary of the results and exit with a status code `0` for success or `1` for failure.

### Cleaning Up

To remove all generated files (logs, waveforms, object files, etc.), run the `clean.py` script:

```bash
python3 clean.py
```

### Viewing Waveforms

After running the tests, you can inspect the signal behavior using a VCD viewer like GTKWave. For example, to view the CPU test waveforms:

```bash
gtkwave test/cpu/changes.vcd
```

## Testing Strategy

The project includes a comprehensive test suite located in the `test/` directory, with separate subdirectories for each component (`cpu`, `alu`, `stack`).

Testbenches use VHDL's `assert` statement to verify behavior. A special string `___FAILOUT` is included in the report message of failing assertions. The `run.py` script scans the simulation output for this string to programmatically determine if a test has failed, providing detailed error messages directly in the console.

GammaCPU

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README