Ariadne

This tool helps you create structural RTL hierarchy levels

Etymology

While writing RTL, you can often divide your design in two parts. One is the core functionality which you want to focus on. The other part is the structural connection between all these blocks. Ariadne helps you automate the second part

All creations of extra wrapper levels, connections between modules, propagation of extra signals, ... these can now be handled by Ariadne. It makes the design phase less error-prone, cleans up your code and lets you focus on the relevant parts

For example, lets take the following view of our current architecture

This example can be found at test/vhdl_tests/vhdl_port_propagation

You have a block called my_block.vhd several hierarchy levels deep in your design. During your project you realise that one of its output ports needs to be propagated to the toplevel. Normally you would need to manually change all intermediate files. This is time consuming and error-prone. If instead we made all these structural RTL levels with Ariadne, the propagation can be done automatically

Another common example would be when you want to connect two modules. Most of the corresponding ports will only differ by the port direction or a simple pattern. Ariadne can help you to make all these connection with only a few lines of code

This example can be found at test/vhdl_tests/vhdl_spi

Supported languages:

• VHDL
• Verilog
• SystemC

Not supported:

• SystemVerilog

Documentation

The full documentation can be found here

It's written in Asciidoc.

You can process it with Asciidoctor to a different output format like HTML, PDF, ...

Using the Asciidoctor.js browser extension, you can render the documentation on the fly

Firefox prevents the extension from including other files. If you see this rendering issue with the documentation, you can do the following steps to circumvent it:

• Open the Firefox configuration with the URL about:config
• Find the parameter security.fileuri.strict_origin_policy
• Set the value of this parameter to false

Installation

Warning We do not support Ruby version 2.7.x

Warning We use Git submodules so don't forget to run the following command before compiling

git submodule update --init

Compilation

Compilation is done with CMake

Generate the project build system:

cmake -B build -S ./ -D SCRIPT_RUBY=ON -D SCRIPT_PYTHON=ON

You must define either to build for RUBY script support, Python script support or both

By default the build system will use Makefiles. To use Ninja files you can run the following command:

cmake -B build -S ./ -G Ninja -D SCRIPT_RUBY=ON -D SCRIPT_PYTHON=ON

Build the project:

cmake --build build

To specify the maximum number of concurrent processes when building, you can use the following option:

cmake --build build -j 4

Packages

For Ubuntu and Debian the following packages are required:

• cmake
• For Ninja builds: build-essential
• python3-dev
• ruby-dev
• flex
• bison
• asciidoctor (for documentation)

Tests and regressions

A regression testbench can be found at . Here we have a collection of tests subdivided into different categories

The tests are integrated in the CMake flow with CTest

A short summary of how to work with CTest can be found here

Running tests

To run all the tests you must first compile everything and then run the following command:

ctest --test-dir build

If you want to display the output of a test when it fails, you can add the following flag:

ctest --test-dir build --output-on-failure

To specify the maximum number of concurrent processes when running the tests, you can use the following option:

ctest --test-dir build -j 4

All the tests are subdivied into different categories. The test names are prefixed with the category. This lets you filter for certain tests. For example, the next command will run all tests that contain the string "vhdl_"

ctest --test-dir build -R vhdl_

All tests are accompanied with a label. These are used to subdivide the tests in certain groups. For example, the next command will run all tests where the label contains the string "vhdl"

ctest --test-dir build -L vhdl

License

Ariadne is distributed under the GNU General Public License v3.0

Contact info

Created by easics

Tool specific questions: tools@easics.be