Getting Started#

This project provides two equivalent implementations of the ASCON-128 algorithm. Choose the implementation that best fits your needs:

  • SystemVerilog Flow: Uses Verilator simulator with Cocotb testbenches

  • VHDL Flow: Uses NVC simulator with VUnit testbenches

Note

You can install both flows if you want to compare implementations or work with both HDLs.

Common 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 Python#

Python is used for running scripts and managing dependencies for both flows:

sudo apt install python3 python3-pip python3-venv

Create a virtual environment and install the required packages:

python3 -m venv .venv
source .venv/bin/activate
pip install .

This will install dependencies for both flows including Cocotb, VUnit, Ruff, and other testing tools.

If you want to install the documentation dependencies you can do so with:

pip install -e ".[docs]"

SystemVerilog Flow#

Choose this flow if you want to work with the SystemVerilog implementation.

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

Running SystemVerilog Tests#

Test the SystemVerilog implementation with Cocotb:

# Run all SystemVerilog tests
cd src/bench/cocotb
make

# Run specific module tests
cd src/bench/cocotb/ascon
make

VHDL Flow#

Choose this flow if you want to work with the VHDL implementation. If you want to use GHDL, you can use the one provided in the OSS-CAD-Suite. Otherwise, you can use NVC.

Install NVC (VHDL Simulator)#

NVC is a free open-source VHDL simulator that supports VHDL-93, VHDL-2002, VHDL-2008, and VHDL-2019.

OSS CAD Suite (Recommended)#

NVC is included in the OSS-CAD-Suite. If you haven’t installed it yet:

# Example for the 2025-02-13 release
wget https://github.com/YosysHQ/oss-cad-suite-build/releases/download/2025-02-13/oss-cad-suite-linux-x64-20250213.tgz
tar -xzf oss-cad-suite-linux-x64-20250213.tgz
source oss-cad-suite/environment

Build from Source#

For the latest version, you can build NVC from source:

sudo apt-get install -y \
      build-essential autotools-dev automake autoconf \
      flex bison check llvm-dev pkg-config zlib1g-dev \
      libdw-dev libffi-dev libzstd-dev

git clone https://github.com/nickg/nvc.git
cd nvc
./autogen.sh
mkdir build && cd build
../configure
make
sudo make install

Ubuntu Repository#

sudo apt install nvc

Running VHDL Tests#

Test the VHDL implementation with VUnit:

# Run all VHDL tests
python src/bench/vunit/test_ascon_modules.py

# Run specific module tests
cd src/bench/vunit/ascon
python run.py

Optional Tools#

Install lcov (Code Coverage)#

lcov is used to generate code coverage reports for SystemVerilog flow only:

sudo apt install lcov

Tools Information#

This project supports both SystemVerilog and VHDL implementations of the ASCON-128 encryption algorithm. Each flow uses different tools optimized for the respective HDL.

SystemVerilog Flow Tools#

Verilator#

Verilator is a free software Verilog/SystemVerilog simulator used for the SystemVerilog implementation.

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 SystemVerilog modules and run simulations.

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.

VHDL Flow Tools#

NVC#

NVC is a free open-source VHDL simulator that supports VHDL-93, VHDL-2002, VHDL-2008, and VHDL-2019. It’s used for simulating the VHDL implementation of the ASCON modules. NVC provides excellent performance and supports modern VHDL features.

VUnit#

VUnit is an open-source unit testing framework for VHDL/SystemVerilog. It’s used to write and run unit tests for the VHDL modules. VUnit provides features like test discovery, automatic test runner generation, and comprehensive test reporting.

Common Tools#

These tools are used across both flows:

Ruff#

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

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.

lcov#

lcov is a tool used to generate HTML coverage reports for both SystemVerilog and VHDL flows.

Surfer#

Most testbenches generate a *.vcd or *.fst 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.

Note

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