Quickstart Guide

This guide will help you get started with the AVL APB library. It will show you how to install the library, compile and run the examples, and how to use the library in your own projects.

Before you start this guide, you should have a basic understanding of AVL.

In order to run the examples you will need to have installed:

  • Python

  • A HDL simulator

    • If you haven’t licensed a commercial HDL simulator Verilator is available as an open-source alternative.

  • A waveform viewer

    • If you haven’t licensed a commercial HDL simulator GTKWave is a popular open-source waveform viewer.

It’s also recommended that you have a basic understanding of the cocotb framework.

CocoTB 2.0

AVL-APB now supports CocoTB2.0. This was introduced in v0.2.0.

All older versions support v1.9.1 and will fail if run with CocoTB 2.0.

To upgrade follow the instructions given on the link above.

Installing From pip

# Standard build
pip install avl-apb

# Development build
pip install avl-apb[dev]

This will install the latest version of the library and all required dependencies. If you want to install a specific version, you can specify the version number:

pip install avl-apb==0.5.0

Installing From Source

AVL is available via GitHub.

All required libraries including cocotb are included in the pyproject.toml file.

git clone https://github.com/projectapheleia/avl-apb.git
cd avl

# Standard build
pip install .

# Development build
pip install .[dev]

Or if you plan on editing the source code, you can install in editable mode:

git clone https://github.com/projectapheleia/avl-apb.git
cd avl
pip install --editable .[dev]

A script is provided to setup a python virtual environment and install all dependencies for development.

git clone https://github.com/projectapheleia/avl-apb.git
cd avl
source avl.sh

This assumes you have a simulator and Graphviz installed, to ensure all examples and documentation can be built out of the box.

Note

avl.sh updated to work on Linux and macOS.

Building The Docs

cd doc
make html
<browser> build/html/index.html

Running the Examples

The examples are located in the examples directory. To run the examples, you will need to have a HDL simulator installed, the default is Verilator.

To run all examples:

cd examples
make sim

To clean up the examples:

cd examples
make clean

Alternatively, you can run each example individually:

cd examples/adder/template
make sim

If using Verilator all examples generate vcd files.