Quick Start Guide

Get the MHX™ Ternary RISC-V Core running in simulation in under 10 minutes.

Prerequisites

Before you begin, ensure you have the following installed:

• Verilator 4.210+ - For RTL simulation
• Python 3.8+ - For build scripts and analysis tools
• FuseSoC 2.0+ - For build management
• RISC-V Toolchain - For compiling test programs

Installation

1. Clone the Repository

git clone https://github.com/TheusHen/ternary-ibex.git
cd ternary-ibex
git submodule update --init --recursive

2. Install Dependencies

# On Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y verilator python3-pip

# Install Python dependencies
pip3 install -r python-requirements.txt

# Install FuseSoC
pip3 install fusesoc

3. Setup FuseSoC

# Add required libraries
fusesoc library add fusesoc_cores https://github.com/fusesoc/fusesoc-cores

Running Simulation

Basic Ternary Test

# Build and run the ternary test suite
fusesoc --cores-root . run --target=sim --tool=verilator lowrisc:ibex:mhx_ternary_test

Running Individual Test Suites

# ALU tests only
./run_ternary_tests.sh --suite alu

# Neural unit tests
./run_ternary_tests.sh --suite neural

# Full integration tests
./run_ternary_tests.sh --suite integration

Running Lint Checks

# Verilator lint
fusesoc --cores-root . run --target=lint --tool=verilator lowrisc:ibex:mhx_ternary_test

# Verible lint
fusesoc --cores-root . run --target=lint --tool=veriblelint lowrisc:ibex:mhx_ternary_test

Example: Ternary Addition

Here's a simple assembly example demonstrating ternary operations:

# Load ternary values into registers
t.li    t0, 0x0001      # Load ternary 1 (positive)
t.li    t1, 0xFFFF      # Load ternary -1 (negative)

# Ternary addition
t.add   t2, t0, t1      # t2 = t0 + t1 = 0

# Neural MAC operation
n.mac   t3, t0, t1, t2  # t3 = t0 * t1 + t2

Next Steps

• Explore the architecture - Understand the core design
• ISA Reference - Complete instruction documentation
• Integration Guide - Integrate into your SoC