RVvM - Ruby Vivado Manager

RVvM is a Ruby based meta tool to manage, compile, elaborate and simulate SystemVerilog and UVM based projects using Xilinx Vivado xvlog, xelab, xrun and xsc tools.

Installation

Install the gem and add to the application's Gemfile by executing:

bundle add rvvm

If bundler is not being used to manage dependencies, install the gem by executing:

gem install rvvm

Requirements

Vivado Design Suite
Xilinx Vivado binaries in your PATH and XILINX_PATH env variable pointing to your Vivado install dir or sourced settings64 Vivado script

Usage

To get full rvvm usage docs use -h or --help option.

Project creation

Create a new RVvM project using -n or --new.

eg.:

rvvm -n best_rtl_project

Whitespaces in project name and or generated templates are not allowed.

Project management

To manage an RVvM project use the rvvm script inside the root of an RVvM project or its config directory.

Project structure

RvvM_project
├── design              # SV design sources
│   ├── itf
│   ├── pkg
│   └── src
├── rvvm                # RVvM project config and output directory
│   ├── rvvm_project_compile_list.f
│   ├── dpi_compile_list.f
│   ├── logs            # comp, dpi, elab, sim log dir
│   │   ├── comp
│   │   ├── dpi
│   │   ├── elab
│   │   └── sim
│   ├── rvvmconf.json   # RVvM project config file
│   └── wfcfg.tcl
└── verif               # SV verification sources
    ├── env
    │   ├── agents
    │   └── top
    ├── tb
    │   └── src         # default UVM testbench top module
    │       └── rvvm_project_tb_top.sv
    └── test
        ├── seq
        └── src

Project configuration

RVvM project configuration is stored in its config directory in the <project root>/rvvm/rvvmconf.json json file.

You can configure the project by editing its config file. Individual settings of the configuration can be owerwritten @ runtime using specific arguments (see -h/--help).

The rvvmconf.json configuration consists of:

# example configuration:
# .../best_rtl_project/rvvm/rvvmconf.json:

{
  "project": {
    "name": "best_rtl_project",
    "path": "/home/mrbya/mycodes/ruby/rvvm/best_rtl_project",
    "rvvmDir": "rvvm",
    "logDir": "logs",
    "company": " "
  },

  "compilation": {
    "list": "best_rtl_project_compile_list.f",
    "logDir": "comp",
    "log": "comp.log",
    "args": "-L uvm"
  },

  "dpi": {
    "dpilib": 0,
    "list": "dpi_compile_list.f",
    "args": " "
  },

  "elaboration": {
    "tbTop": "best_rtl_project_tb_top",
    "tb": "best_rtl_project_tb",
    "timescale": "1ns/1ps",
    "customdpilib": "",
    "logDir": "elab",
    "log": "elab.log",
    "args": " "
  },

  "simulation": {
    "logDir": "sim",
    "log": "${testname}.log",
    "verbosity": "LOW",
    "defTest": " ",
    "batch": 0,
    "testlist": [" "],
    "args": " "
  }
}

Project

Parameter	Default Value	Description
`name`	Name of the project @ creation	RVvM project name
`path`	Path to the project @ its creation	Absolute path to the project
`rvvmDir`	`rvvm`	Project config and output directory
`logDir`	`log`	Log output directory root
`company`	empty	Company name

Compilation

Parameter	Default Value	Description
`list`	`<project name>_compile_list.f`	Path to project HDL source files compile list
`logDir`	`comp`	Subdirectory for `xvlog` logs inside `project: logDir`
`log`	`comp.log`	`xvlog` log file name
`args`	`-L uvm`	Additional `xvlog` arguments

DPI

Parameter	Default value	Description
`dpilib`	`0`	Switch activating DPI-C compilation when running `--all` and dpi library linkage during elaboration
`list`	`dpi_compile_list.f`	Path to DPI-C source files compile list
`args`	empty	Additional `xsc` arguments

Elaboration

Parameter	Default value	Description
`tbTop`	`<projec name>_tb_top`	Testbench top module name
`tb`	`<project name>_tb`	Elaborated testbench snapshot name
`timescale`	`1ns/1ps`	Elaborated testbench timescale
`customdpilib`	empty	Path to a custom DPI-C library to link into a snapshot during elaboration
`logDir`	`elab`	Subdirectory for `xelab` logs inside `project: logDir`
log	`elab.log`	`xelab` log file name
`args`	empty	Additional `xelab` arguments

Simulation

Parameter	Default value	Description
`logDir`	`sim`	Subdirectory for `xsim` logs inside `project: logDir`
`log`	`${testname}.log`	`xsim` log file name
`verbosity`	`LOW`	UVM reporting verbosity
`defTest`	empty	Default UVM test to be run using `--run`
`batch`	`0`	Switch activating batch UVM test simulation: run multiple UVM tests provided in `simulation: testlist` or using `--testlist`.
`testlist`	empty array	Provide an array of UVM test names to run during a batch simulation.
`args`	empty	Additional `xsim` arguments

Tmplate file generation

RVvM can generate SystemVerilog module, interface, package and generic template files to ease your SV project development.

To generate module templates use:

-m --module <NAME> - to generate a SV module template
-i --itf <NAME> - to generate a SV interface template
-p --pkg <NAME> - to generate a SV package template
--svfile <NAME> - to generate a generic SV file template

Default paths for template file generations are:

RVvM project root
└── design
    ├── itf  # for SV interfaces
    ├── pkg  # for SV packages
    └── src  # for SV modules and generic SV files

You can modify generated template path using --path <PATH> (excluding template file name) or --here.

Using Xilinx Vivado tools

To compile/elaborate/simulate,... yout RVvM project use the rvvm script from inside an RVvM project root or its config directory.

-c --comp - to compile HDL sources
-d --dpi - to compile C/C++ DPI-C library sources
-e --elab - to elaborate project testbench into a snapshot
-r --run - to run UVM test simulation (use -b --batch to run a batch of simulations)
-a --all - to run --comp, --dpi (when configured), --elab, --run
--runsv - to run pure SV/V simulation

Use -w --wave to dump signal waveforms

-u --gui - to open dumped waveforms in Vivado GUI
-g --gencov - to generate UVM test functional coverage report
--covreport - to open coverage report dashboard

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://gitlab.com/such-hdl-much-wow/rvvm. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the RVvM project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.