Skip to main content

Writing a VIV.md

A VIV.md file is a guide to your repository that helps Viv debug more efficiently. When present in the root of a code directory, Viv reads it at the start of every analysis to understand how the codebase is structured and where to find important files.

Why it matters​

Without a VIV.md, Viv must explore the directory structure and read files to figure out how the project is organized. This takes time and tool calls that could be spent investigating the actual bug. A good VIV.md gives Viv a head start by answering common questions upfront: where is the RTL? What framework does the testbench use? What do the log files contain?

Generating a VIV.md​

The easiest way to create a VIV.md is to let Viv generate one for you:

viv init --code-directory <path to your code>

You can also pass an artifact directory so that Viv can inspect your log files and include descriptions of them in the generated VIV.md:

viv init \
  --code-directory <path to your code> \
  --artifact-path <path to your logs directory>

Without --artifact-path, the generated VIV.md will cover your code structure but won't include a log output section. With it, Viv examines the log files to document their formats and contents, which helps future analyses skip the step of figuring out what each log file is.

You can then edit the generated file to add details or correct anything that was inferred incorrectly. You can also create a VIV.md entirely by hand if you prefer.

Code architecture overview​

Describe the major components of your project and where they live. Focus on what each directory contains at a high level.

## Code architecture overview

### Core components

**RTL (`rtl/`)**
- SystemVerilog RTL for the AXI interconnect
- Top-level module: `axi_xbar.sv`
- Protocol logic in `rtl/axi_protocol/`

**Testbench (`tb/`)**
- UVM testbench with constrained-random stimulus
- Scoreboards in `tb/scoreboards/`
- Sequences in `tb/sequences/`

**Shared utilities (`common/`)**
- Shared packages and parameter definitions

Key patterns​

Call out any architectural patterns, frameworks, or conventions that would help an investigator understand the code.

### Key patterns

- **UVM methodology**: The testbench uses UVM with a standard agent-based architecture. Scoreboards compare DUT output against a golden model.
- **Parameterized design**: The DUT is heavily parameterized. Test-specific parameters are set in `tb/test_configs/`.
- **Assertions**: SVA assertions are in `rtl/assertions/` and bind to the DUT in `tb/bind_assertions.sv`.

Log output overview​

Describe the log files that Viv will find in the artifacts directory. This helps Viv understand what each file contains without having to open and read every file.

## Log output overview

- **sim.log**: Simulator stdout/stderr. Contains UVM reports, assertion messages, and final test status.
- **trace.csv**: Instruction trace from the golden reference model. Columns: cycle, PC, instruction, register writes.
- **coverage.vdb**: Functional coverage database (binary, not human-readable).
- **waves.fsdb**: Waveform capture of all top-level signals.

Specifications (optional)​

If your project includes PDF specifications, list them here so that Viv can cross-reference the design against the spec during analysis.

## Specifications

- **docs/axi4_spec.pdf**: AXI4 protocol specification. Contains signal definitions, handshake rules, and burst types.
- **docs/register_map.pdf**: Register map for the DUT. Contains addresses, field definitions, and reset values.

Guidelines​

  • Use relative paths. Paths should be relative to the code root, not absolute. Write rtl/, not /home/user/project/rtl/.
  • Keep it concise. VIV.md is consumed by an AI agent, not a human reader. Brief, factual descriptions are more useful than long explanations.
  • Focus on structure, not implementation. Describe what's where, not how the code works in detail. Viv will read the code itself.
  • List log filenames. Even a simple list of filenames with one-line descriptions saves Viv time.
  • Update it when the project changes. If you add a new major component or change the directory layout, update VIV.md to match.

Full example​

# VIV.md

This repository contains RTL and testbench for an AXI4 crossbar interconnect.

## Code architecture overview

### Core components

**RTL (`rtl/`)**
- SystemVerilog RTL for a configurable AXI4 crossbar
- Top-level module: `axi_xbar.sv`
- Protocol handling in `rtl/axi_protocol/`
- Arbiter logic in `rtl/arbiter/`

**Testbench (`tb/`)**
- UVM-based verification environment
- Scoreboards compare DUT transactions against golden model in `tb/golden/`
- Constrained-random sequences in `tb/sequences/`
- Test configurations in `tb/tests/`

**Common (`common/`)**
- Shared packages: `axi_pkg.sv`, `test_params_pkg.sv`

### Key patterns

- UVM agent-based architecture with separate read/write agents
- Golden model is a cycle-accurate C++ model called via DPI
- Assertions bind to DUT in `tb/bind/assert_bindings.sv`

## Log output overview

- **sim.log**: Simulator output with UVM reports and test pass/fail status.
- **trace.log**: Transaction-level trace from the scoreboard.
- **waves.fsdb**: Full waveform capture.

## Specifications

- **docs/axi4_spec.pdf**: ARM AXI4 protocol spec. Covers handshake protocol, burst types, and ordering rules.