# AVL RISCV Coverage - Apheleia Verification Library RISCV Coverage Framework

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.7%2B-blue)](https://www.python.org/)


AVL  RISCV Coverage has been developed by experienced, industry professional verification engineers to provide a framework \
and library of base classes for developing functional coverage for RISCV processors in [Python](https://www.python.org/) using \
the compiled test code and trace files. Coverage can be generated from higher level models with no HDL intermediate.

- Although a default instr_dict.json is provided, it can be overridden on the commandline.

- An elf file and spike trace are required.

- Additional coverage packages can be added from the commandline.

- Output is generated in AVL coverage.json and optionally rendered into html.

```sh
usage: avl-riscv-coverage [-h] [--ref REF] [--extensions [EXTENSIONS ...]] [--packages [PACKAGES ...]] [--elf ELF] [--trace TRACE] [--output OUTPUT] [--html] [--verbose]

options:
  -h, --help            show this help message and exit
  --ref REF             Pointer to instr_dict.json (generated from https://github.com/riscv/riscv-opcodes) (default: ./avl-riscv-coverage/avl_riscv_coverage/instr_dict.json)
  --extensions [EXTENSIONS ...
                        List of extensions
  --packages [PACKAGES ...]
                        List of python packages containing covergroups
  --elf ELF             Elf file for testcase
  --trace TRACE         List of trace files
  --output OUTPUT       Output directory for report
  --html                Generate HTML report
  --verbose             Verbose messages
```

---

## 📦 Installation

### Using `pip`
```sh
# Standard build
pip install avl-riscv-coverage

# Development build
pip install avl-riscv-coverage[dev]
```

### Install from Source
```sh
git clone https://github.com/projectapheleia/avl-riscv-coverage.git
cd avl-riscv-coverage

# Standard build
pip install .

# Development build
pip install .[dev]
```

Alternatively if you want to create a [virtual environment](https://docs.python.org/3/library/venv.html) rather than install globally a script is provided. This will install, with edit privileges to local virtual environment.

This script assumes you have  [Verilator](https://www.veripool.org/verilator/), [GTKWave](https://gtkwave.sourceforge.net/) and [Graphviz](https://graphviz.org/download/) installed, so all examples and documentation will build out of the box.


```sh
git clone https://github.com/projectapheleia/avl-riscv-coverage.git
cd avl-riscv-coverage
source avl-riscv-coverage.sh
```

## 📖 Documentation

In order to build the documentation you must have installed the development build.

### Build from Source
```sh
cd docs
make html
<browser> build/html/index.html
```
## 🏃 Examples

In order to run all the examples you must have installed the development build.

To run all examples:

```sh
cd examples

# To run
make -j 8 sim

# To clean
make -j 8 clean
```

To run an individual example:

```sh
cd examples/THE EXAMPLE YOU WANT

# To run
make sim

# To clean
make clean
```

---


## 🧹 Code Style & Linting

This project uses [**Ruff**](https://docs.astral.sh/ruff/) for linting and formatting.

Check code for issues:

```sh
ruff check .
```

Automatically fix common issues:

```sh
ruff check . --fix
```

## 📧 Contact

- Email: avl@projectapheleia.net
- GitHub: [projectapheleia](https://github.com/projectapheleia)
