..
   Copyright (c) 2020, 2021, 2022 OpenHW Group

   Licensed under the Solderpad Hardware Licence, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

   https://solderpad.org/licenses/

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

   SPDX-License-Identifier: Apache-2.0 WITH SHL-2.0


.. _quick_start:

CORE-V-VERIF Quick Start Guide
==============================

Many people who come to `CORE-V-VERIF <https://github.com/openhwgroup/core-v-verif>`_ for the first time
are anxious to 'get something running' and this section is written to satisfy that itch.

Note: in several places in this chapter a reference is made to $CORE_V_VERIF.
This is used as short hand for the absolute path to your local working directory.
You will not need to set this shell environment variable yourself.

A good place to start is the CV32E40P core testbench since the CV32E40P is mature, and the core testbench is very simple and runs with open-source tools.
You will need:

#. A Linux machine (CORE-V-VERIF has been successfully run under Ubuntu, Debian and CentOS).
#. Python3 and a set of plug-ins. The current plug-in list is kept in `$CORE_V_VERIF/bin/requirements.txt`.
#. A GCC cross-compiler (aka "the `Toolchain <https://github.com/openhwgroup/core-v-verif/blob/master/mk/TOOLCHAIN.md#core-v-toolchain>`_"). Even if you already have a RISC-V toolchain, please do follow that link and read `TOOLCHAIN.md <https://github.com/openhwgroup/core-v-verif/blob/master/mk/TOOLCHAIN.md>`_ for recommended ENV variables to point to it.
#. `Verilator <https://veripool.org/guide/latest/install.html>`_.

An easy way to get the Python plug-ins installed on your machine is::

   $ git clone https://github.com/openhwgroup/core-v-verif.git $CORE_V_VERIF
   $ cd $CORE_V_VERIF/bin
   $ pip3 install -r requirements.txt

**Note:** Virtual python environments can be used if desired.

Once the above is in place type the following::

    $ cd $CORE-V-VERIF/cv32e40p/sim/core
    $ make

**Note:** Check the required shell environment variables (`variables <https://github.com/openhwgroup/core-v-verif/tree/master/mk#required-corev-environment-variables>`_).

The above will compile the RTL and the core testbench using Verilator, compile the 'hello-world' test-program using the Toolchain and run it on the "Verilated" model.
The simulation run should produce the following::

    HELLO WORLD!!!
    This is the OpenHW Group CV32E40P CORE-V processor core.
    CV32E40P is a RISC-V ISA compliant core with the following attributes:
        mvendorid = 0x602
        marchid   = 0x4
        mimpid    = 0x0
        misa      = 0x40001104
        XLEN is 32-bits
        Supported Instructions Extensions: MIC

The README in the cv32e40p/sim/core directory will explain how to run other tests and use other simulators.

Where is the RTL?
-----------------

As CORE-V-VERIF is a single repository for the verification of several different CORE-V cores, you will not find the RTL here.
Each CORE-V core is managed in its own repository, and is automatically cloned into $CORE_V_VERIF/core-v-cores/<core_name> by the Makefiles, as needed.
If you have successfully run the hello-world test above, then you may have noticed that the RTL was cloned to $CORE_V_VERIF/core-v-cores/cv32e40p/rtl (take a look!).
The URL, branch and hash of the cloned RTL is obtained from $CORE_V_VERIF/cv32e40p/sim/ExternalRepos.mk (again, take a look!).
You can override these variables on the `make` command line or by setting shell environment variables.

UVM
---

Up to this point, the discussion has been about the "core" testbench, which is intended as demonstration vehicle only.
The primary verification environments implemented in CORE-V-VERIF are all based on the UVM.
The UVM enviroment for CV32E40P is completely separate from the core testbench and uses a different set of Makefiles.

In order to use the UVM environments you will need items 1, 2 and 3 from the list above, plus a SystemVerilog simulator capable of supporting the UVM and the Imperas OVPsim Instruction Set Simulator (ISS).
You should also review the README in $CORE_V_VERIF/mk for a description of the `shell ENV vars used by the UVM environment <https://github.com/openhwgroup/core-v-verif/blob/master/mk/README.md#required-corev-environment-variables>`_.
With these in place you can do the following::

    $ git clone https://github.com/openhwgroup/core-v-verif.git
    $ cd core-v-verif/cv32e40p/sim/uvmt
    $ make test TEST=hello-world CV_SIMULATOR=<xrun|vcs|vsim|riveria|dsim>

The above will compile the RTL and the UVM testbench using the selected simulator and run the 'hello-world' test-program.
Note that this is the same test-program as was used in the core testbench example above.
The simulation run will produce similar results, with lots of additional UVM messaging.

If you do not have access to the Imperas ISS you can disable it at run-time::

    $ make test TEST=hello-world CV_SIMULATOR=<xrun|vcs|vsim|riveria|dsim> USE_ISS=NO

Why UVM?
~~~~~~~~

There are three reasons why the UVM was selected as the verification methodology used by CORE-V-VERIF:

#. Using a standard methodology provides a common framework making it practical for verification IP from multiple and diverse teams to inter-operate.
#. To date, all of the cores in the OpenHW Group CORE-V family are implemented in SystemVerilog and the SystemVerilog implementation of the UVM is both complete and robust.
#. CORE-V-VERIF was specifically created to bring industrial practises to bear for CORE-V verification, and the UVM is the most popular simulation verification methodology used in industry today.

Do I need an ISS?
~~~~~~~~~~~~~~~~~

The short answer is **yes**.
CORE-V-VERIF uses an Instruction Set Simulator (ISS) as a reference model of the CORE-V core (the Device Under Test).
A key feature of the CORE-V-VERIF UVM environments is that the state of the DUT is compared to the state of the reference model after each instruction is retired.
Without a comparison to a reference model, the pass/fail status of a given simulation is mostly vacuous.

There are several popular options for a RISC-V ISS, including `Spike <https://github.com/riscv-software-src/riscv-isa-sim>`_, `Whisper <https://github.com/chipsalliance/SweRV-ISS>`_ and `Imperas OVPsim <https://www.ovpworld.org/technology_ovpsim>`_.
Both Spike and Whisper are open-source ISS models.
At the time of this update (2022-11-08) CORE-V-VERIF uses a commercial version of Imperas OVPsim for the CV32E4 cores.
A contribution to integrate another reference model into CORE-V-VERIF would be welcome.

Doing More in CORE-V-VERIF
--------------------------

As far as is practical, CORE-V-VERIF maintains "in place" documentation.
That is, most directries will have a `README.md` that provides information relavent to that directory and/or its sub-directories.
GitHub renders these to HTML automatically, providing easy to read and use content.
In keeping with the `DRY <https://en.wikipedia.org/wiki/Don%27t_repeat_yourself>`_ principle of good documentation, whenever practical this document will point you to an in-place README.

At the top-level of CORE-V-VERIF, there is a subdirectory for each supported core.
All of the verification code specific to that core will be in this directory.
Look at the README in `cv32e40p` to get a sense of the directory structure of the cv32e40p-specific testbenches.
The structure of the other cores will be similar, but need not be identical.

The cv32e40p sub-tree supports a simple "core" testbench and a complete UVM environment.
Partial instructions to run the core testbench are provided above; see the README at `$CORE_V_VERIF/cv32e40p/sim/core` for full details.
To run the CV32E40P UVM environment, go to `$CORE_V_VERIF/cv32e40p/sim/uvmt` and read the README.

This chapter uses the CV32E40P as its example, but there are equivalent READMEs in directories for the other supported cores.

Supported Simulators
~~~~~~~~~~~~~~~~~~~~

It is a goal of the OpenHW Verification Task Group for core-v-verif to support all known SystemVerilog 1800-2017 compliant simulators.
The Makefiles for the UVM environments have a variable `CV_SIMULATOR` which is used to select the simulator used to compile and run a testcase.
So you can run hello-world with Cadence Xcelium like this::

    $ make test TEST=hello-world CV_SIMULATOR=xrun

To run the same test with Metrics Dsim::

    $ make test TEST=hello-world CV_SIMULATOR=dsim

The variable is used to select one of a set of simulator-specific Makefiles that are located at `$CORE_V_VERIF/mk/uvmt <https://github.com/openhwgroup/core-v-verif/tree/master/mk/uvmt>`_.

Note that CORE-V-VERIF tries to support all simulators and this requires support from OpenHW Group members.
From time to time a Makefile for a specific simulator will not see a lot of use and will inevidibly suffer from bit-rot.
If you notice an issue with a simulator-specific Makefile, please either raise a GitHub issue, or better yet, a pull-request with a fix.

Verifying other Cores
~~~~~~~~~~~~~~~~~~~~~

At the time of this update (2022-11-08), CORE-V-VERIF supports verification of multiple CORE-V cores:

* **CV32E40P**: the UVM environment is stable and v1.0.0 is complete.  Work on v2.0.0 has started.  A simple "core" testbench which can be run with open-source tools is available.
* **CV32E40X**: the UVM environment is stable, and verification is on-going.
* **CV32E40S**: the UVM environment is stable, and verification is on-going.
* **CVA6**: the UVM environment is in the early stages of development.
* **CVE2**: Coming soon!

CV32E40P Directory Tree (simplified)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Below $CORE_V_VERIF you will find a directory named *cv32e40p*.
This directory contains all of the CV32E40P-specific sources to compile and run simulations on the CV32E40P CORE-V core.
The tree below is a somewhat simplified expansion of the directory highlighting the names, locations and purposes of key directories and files.
Other cores, e.g. CV32E40X will implement a similar directory tree.
::

  cv32e40p
    ├── bsp                                         // Board-support Package
    ├── docs
    │   └── VerifPlans
    ├── env                                         // UVM environment
    │   ├── corev-dv
    │   └── uvme
    │       ├── cov
    │       └── vseq
    ├── regress                                     // Regression configurations
    ├── sim
    │   ├── README.md
    │   ├── Common.mk
    │   ├── core                                    // Place to run simulations of the "core" testbench
    │   ├── TOOLCHAIN.md
    │   ├── tools
    │   └── uvmt                                    // Place to run simulations of the "uvm" environment
    │       ├── Makefile
    │       └── README.md
    ├── tb
    │   ├── README.md
    │   ├── core                                    // the "core" testbench
    │   │   ├── dp_ram.sv
    │   │   ├── mm_ram.sv
    │   │   ├── tb_top.sv
    │   │   ├── tb_top_verilator.cpp
    │   │   └── tb_top_verilator.sv
    │   └── uvmt                                    // the UVM environment
    │       ├── uvmt_cv32e40p_constants.sv
    │       ├── uvmt_cv32e40p_tb.sv
    │       ├── ...
    │       └── uvmt_cv32e40p_pkg.sv
    ├── tests                                       // test-programs and UVM testcases.
    │   ├── cfg
    │   │   ├── default.yaml
    │   │   ├── no_pulp.yaml
    │   │   ├── num_mhpmcounter_29.yaml
    │   │   ├── ovpsim_no_pulp.ic
    │   │   └── pulp.yaml
    │   ├── programs
    │   │   ├── corev-dv                            // configurations for randomly generated test-programs
    │   │   │   ├── corev_rand_arithmetic_base_test
    │   │   │   │   ├── corev-dv.yaml
    │   │   │   │   └── test.yaml
    │   │   |   ├── ...
    │   │   |   |
    │   │   │   └── corev_rand_jump_stress_test
    │   │   │       ├── corev-dv.yaml
    │   │   │       └── test.yaml
    │   │   └── custom                              // "custom" (manually written) test-programs
    │   │       ├── hello-world
    │   │       │   ├── hello-world.c
    │   │       │   └── test.yaml
    │   │       ├── ...
    │   │       |
    │   │       └── debug_test
    │   │           ├── debug_test.c
    │   │           └── test.yaml
    │   └── uvmt                                    // UVM testcase(s) and virtual sequences
    │
    └── vendor_lib                                  // Libraries from third-parties
        ├── README.md
        ├── google
        ├── imperas
        ├── riscv
        └── verilab

