🚀 Quick Start Guide

This guide will help you set up the development environment and run your first simulation in minutes. I use a containerized environment to ensure toolchain consistency across the entire team.

---

1️⃣ Clone the Repository

First, clone the project and enter the root directory:

git clone git@github.com:esreftech/cv32e40p_core.git
cd cv32e40p_core

---

2️⃣ Build & Enter the Environment

I provide a setup script that get the Docker image from Docker Hub and build then launches the container. Make sure you have Docker installed and running on your host machine.

# This script builds the image and enters the container
./scripts/setup.sh

Build Cache & Issues

In most cases, you only need to run this once. If you encounter environment issues or toolchain errors, please open an issue on GitHub instead of trying to modify the Dockerfile manually.

---

3️⃣ Verify the Workflow

Once the setup is successful, your terminal will chabnge and look like that: engineer@cv32e40p-dev:/work$

Now, run the integration script to verify that the software compiler, RTL simulator, and tracers are all working correctly:

./ci/run_all.sh

Simulation Complete

If you see [SUCCESS] Simulation Complete. Waveforms available in /work/sim/waves, your environment is fully functional. You are ready to start designing!

---

Linting & Syntax Checks

Before committing any RTL changes, always run the linter to catch syntax errors or non-synthesizable code:

./ci/lint.sh

---

📂 Command Summary Table

Here is a quick reference for the available scripts and their purposes:

Category	Script	Description
Setup	./scripts/setup.sh	Builds/Enters the Docker environment.
CI / Global	./ci/run_all.sh	Compiles SW + RTL and runs the full simulation.
CI / Lint	./ci/lint.sh	Runs Verilator linting and syntax checks.
Simulation	./scripts/sim_unit.sh	Runs specific unit tests for modules.
Synthesis	./scripts/synth.sh	Entry point for the synthesis flow.
FPGA (Gowin)	./scripts/gowin/flash_tang9k.sh	Flashes the bitstream to Tang Nano 9K.

---

Troubleshooting & Notes

Waveform Visualization

While the simulation runs inside Docker, the generated .vcd files are mapped to your host machine. You should open GTKWave on your host OS and point it to sim/waves/simulation.vcd.

Root Privileges

If you get a "Permission Denied" error when running ./scripts/setup.sh, ensure your user is added to the docker group or run with sudo.