GammaCPU

KO | EN

gitlite — search

#javascript #golang #rust #macos #java #awesome #kubernetes #awesome-list #vue #pytorch #security #mcp #ios #openai

(★ 14)

VHDL-based CPU which supports running raw WASM instructions.

GammaCPU Latest Version Download

Download Latest Version (.zip)

// 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

GammaCPU Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

GammaCPU

GammaCPU Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README