Quickstart Guide

This guide will help you get started with the AVL-QEMU 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 and QEMU.

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.

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

CocoTB 2.0

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

Installing From pip

# Standard build
pip install avl-qemu

# Development build
pip install avl-qemu[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-qemu==0.1.0

Installing From Source

AVL-QEMU is available via GitHub.

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

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

# 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-qemu.git
cd avl-qemu
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-qemu.git
cd avl-qemu
source avl-qemu.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-QEMU currently only support LINUX. MacOS is not supported.

Configuring and Building Custom QEMU

AVL-QEMU relies on a custom device install of QEMU. This can only be done when you build QEMU from source.

A script is provided to download, configure and build QEMU for the user from source. See install-qemu-avl-device for more information.

usage: install-qemu-avl-device [-h] --path PATH [--clean] [--nproc NPROC]

Git Clone and configure qemu with the custom avl device

options:
  -h, --help     show this help message and exit
  --path PATH    Install Path
  --clean        Clean existing installation
  --nproc NPROC  Number of processors to use when building QEMU (default: 16)

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/qemu/qemu-5
make sim

If using Verilator all examples generate vcd files.