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 <https://avl-core.readthedocs.io/en/latest/>`_ and \
`QEMU <https://www.qemu.org/>`_.

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

- `Python <https://www.python.org/downloads/>`_

- A HDL simulator
    - If you haven't licensed a commercial HDL simulator `Verilator <https://www.veripool.org/wiki/verilator>`_ is available as an open-source alternative.

It's also recommended that you have a basic understanding of the `cocotb <https://docs.cocotb.org/en/stable/>`_ framework.

CocoTB 2.0
----------
AVL-QEMU supports `CocoTB2.0 <https://docs.cocotb.org/en/development/upgrade-2.0.html>`_. This was introduced in v0.2.0.

Installing From pip
---------------------

.. code-block:: bash

    # 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:

.. code-block:: bash

    pip install avl-qemu==0.1.0

Installing From Source
----------------------

AVL-QEMU is available via `GitHub <https://github.com/projectapheleia/avl-qemu.git>`_.

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

.. code-block:: bash

    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:

.. code-block:: bash

    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.

.. code-block:: bash

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

This assumes you have a simulator and `Graphviz <https://graphviz.gitlab.io/download/>`_ 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 <https://www.qemu.org/download/>`_.

A script is provided to download, configure and build QEMU for the user from source. See :doc:`install-qemu-avl-device </modules/avl_qemu.tools.install_qemu_avl_device>` for more information.

.. code-block:: bash

    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
-----------------

.. code-block:: bash

    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 <https://www.veripool.org/wiki/verilator>`_.

To run all examples:

.. code-block:: bash

    cd examples
    make sim

To clean up the examples:

.. code-block:: bash

    cd examples
    make clean

Alternatively, you can run each example individually:

.. code-block:: bash

    cd examples/qemu/qemu-5
    make sim

If using Verilator all examples generate `vcd <https://en.wikipedia.org/wiki/Value_change_dump>`_ files.