Getting Started#

Installation guide#

Prerequisites#

Before you begin, ensure you have the following:

  • A Linux system or WSL installed on Windows

Note

The project can work on Windows, but tools are usually easier to install on Linux. If you are using Windows, I recommend using WSL.

Setup WSL (Windows Users Only)#

Install WSL with Ubuntu 24.04 in a PowerShell:

wsl --install -d Ubuntu-24.04

For more information, refer to the WSL documentation.

Clone the Repository#

Open the Ubuntu terminal and clone the repository:

git clone https://github.com/CharrierTim/ascon-verilog.git

Change to the project directory:

cd ascon-verilog

Upgrade the System

sudo apt update
sudo apt upgrade

Install Verilator#

Note

Verilator Version Information

  • The project was tested with Verilator 5.031

  • Base version: v5.030

  • Build revision: gc7355b405

  • Minimum recommended version: 5.030

If you encounter issues, ensure your Verilator version is up to date.

Verilator is the SystemVerilog Simulator used to compile and run the testbenches. Choose one of the following methods to install Verilator:

Build from Source#

For the latest version, you can build Verilator from source (see Verilator Installation Guide):

sudo apt-get install -y \
      git help2man perl python3 make autoconf g++ flex bison ccache \
      libgoogle-perftools-dev numactl perl-doc \
      libfl2 libfl-dev \
      zlib1g zlib1g-dev

unset VERILATOR_ROOT
git clone https://github.com/verilator/verilator.git
cd verilator
git checkout stable

autoconf         # Create ./configure script
./configure      # Configure and create Makefile
make -j `nproc`  # Build Verilator itself (if error, try just 'make')
sudo make install

Install Python#

Python is used for running scripts and managing dependencies. Install Python 3 and the required packages:

sudo apt install python3 python3-pip python3-venv

Then, create a virtual environment and install the required packages:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Install lcov#

lcov is used to generate code coverage reports. Install it with:

sudo apt install lcov

Tools Informations#

This project relies entirely on open-source software for the development and testing of hardware modules. The following tools are used:

Cocotb#

Cocotb is a coroutine-based co-simulation testbench environment for verifying VHDL/Verilog/SystemVerilog RTL using Python. It is used to write testbenches for the VHDL modules and run simulations.

lcov#

lcov is a tool used to generate html coverage reports.

Pytest#

Pytest is a testing framework that makes it easy to write simple tests and scales to support complex functional testing for applications and libraries.

Surfer#

Most testbenches generate a *.vcd file that can be visualized using a waveform viewer.

Surfer is a waveform viewer used to visualize simulation results (*.vcd or *.fst files). I used a VSCode workflow, so I used the Surfer VSCode Extension. It can also be downloaded from the Surfer Gitlab or alternatively use GTKWave.

Ruff#

Ruff is a linter and formatter for Python source code. It is used to ensure the code is clean and readable.

Verible#

Verible is a suite of SystemVerilog tools that includes a linter and formatter. I used it as a linter and formatter for the SystemVerilog code. The tool is not required to run the project. The formatting rules are defined in the .vscode/settings.json file. If you want to use it, you can install the Verible VSCode Extension.

Note

My VSCode recommended extensions can be found in the .vscode/extensions.json file.

Verilator#

Verilator is a free software Verilog/SystemVerilog simulator.