# RVvM - Ruby Vivado Manager [![Gem Version](https://badge.fury.io/rb/rvvm.svg)](https://badge.fury.io/rb/rvvm)

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:

```bash
bundle add rvvm
```

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

```bash
gem install rvvm
```

## Requirements

1. [Vivado Design Suite](https://www.xilinx.com/support/download.html)
2. **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.:
```bash
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

```bash
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:

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

```bash
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](https://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](https://gitlab.com/such-hdl-much-wow/rvvm/-/blob/master/CODE_OF_CONDUCT.md?ref_type=heads).

## License

The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

## 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](https://gitlab.com/such-hdl-much-wow/rvvm/-/blob/master/CODE_OF_CONDUCT.md?ref_type=heads).