Skip to main content

Viv Overview

Introduction​

Viv is an AI agent for digital verification. Starting from a failing test case, Viv uses code, logs, waveform files, and specifications in order to find the root cause of the bug.

This diagram shows a simplified overview of how Viv works.

Viv Overview

Instructions​

Prerequisites​

The starting point for Viv is always a failing test case.

In this document, we will assume you're working in a Git repo at ~/project/, containing RTL, test benches, scripts, and any other code used during the test run. We'll assume that the test failed on the version of the project corresponding to Git revision ba88f5a, and that any log files, waveform dumps, traces, and other artifacts from the test run are located in the directory ~/logs/run-0/. However, you do not necessarily need to use Git or any other version control system for Viv to work.

The following must be accessible on the file system that Viv is running on:

  1. The code directory: The code that was used in the test case. For this example, this would be the project directory, with ba88f5a checked out. Again, you don't need to be running Git; any version control system is OK.

    Note: Viv assumes that your code is in a single repo. If this is not the case for you, let us know and we can help.

  2. The logs directory: All the logs, artifacts, etc for the failing test in a single directory or .tar.gz file. This can be inside or outside the code workspace from the previous step. In this example, this would be run-0.

Installation and setup​

Detailed instructions for how to install and set up Viv are located at:

Viv CLI Setup Instructions

Debug a failing test case​

  1. Ensure that the proper version of the code is in place in your code directory (~/project in our example), e.g. by running git checkout ba88f5a.
  2. While still inside the repository, run viv submit --code-directory <path to your code directory> --artifact-path <path to the logs directory>. If you do not supply --code-directory, the current working directory will be used instead.
    1. If you haven't installed your license at this point, you will be prompted to provide a path to it now.
  3. If it's your first time running viv, you will be prompted to paste your API key. Do so now.
  4. Wait for Viv to finish debugging the issue.
  5. Once Viv is finished and has generated a root cause, it will display the root cause. Press the left and right arrow keys to switch between the bug report and the sequence of steps that Viv took to debug the bug.

You can also start a debug run by running viv and selecting "Submit." You can use the default value for the job name. For the artifact path, provide a relative or absolute path to the logs directory.

VIV.md setup (optional)​

If a file called VIV.md is present in the root of the working directory, Viv will use it as a guide to the repo and commonly found log files. This helps Viv guide its investigation and avoid wasting time figuring out how the codebase is structured. A very simple VIV.md might look like:

# VIV.md

This repo contains RTL and testbench for a flux capacitor control module.

## Code architecture overview

### Core components

** RTL (`path/to/rtl/`)**
- RTL code written in Verilog
- etc.

** Testbench (`path/to/tb`) **
- Testbenches written in cocotb
- etc.

## Commonly found log files

- **sim.log** is the stdout/stderr from the simulation.
- **core_trace.csv** is a trace of the instructions handled by the golden model.
- etc.

You can create a VIV.md by yourself if you like, but we recommend creating one automatically and refining it afterwards. To create a VIV.md, run viv and select 2. Generate VIV.md. This will create a markdown file describing the structure of your repo, which you can edit manually after it is created. The more detailed this file is, the more efficiently Viv will be able to debug failing test cases.

MCP setup (optional)​

Viv supports adding third party data sources in the form of Model Context Protocol (MCP) servers. Currently, only the HTTP+SSE transport for MCP servers is supported, but we are working on supporting stdio and streamable HTTP as well. To connect a server, simply run viv mcp add <MCP server URL>. For example, the URL for the Atlassian MCP server is https://mcp.atlassian.com/v1/sse. You will need to consult each third party's documentation to find its MCP URL.

If the server requires OAuth, Viv will open a browser tab to ask for permission to access the resources.

You can list MCP servers using viv mcp list and remove a server using viv mcp remove <server ID>.

This functionality is also accessible by running viv, selecting "Manage MCP servers", and adding / inspecting / removing servers.

Uninstall​

To uninstall Viv, just run npm uninstall -g @silogy/viv.