3. Quickstart

This section is meant to serve as a quick-guide to setup RISCOF and perform a sample validation check between spike (DUT in this case) and SAIL-RISCV (Reference model in this case).

3.1. Install Python

Ubuntu 17.10 and 18.04 by default come with python-3.6.9 which is sufficient for using riscv-config.

If you are are Ubuntu 16.10 and 17.04 you can directly install python3.6 using the Universe repository

$ sudo apt-get install python3.6
$ pip3 install --upgrade pip

If you are using Ubuntu 14.04 or 16.04 you need to get python3.6 from a Personal Package Archive (PPA)

$ sudo add-apt-repository ppa:deadsnakes/ppa
$ sudo apt-get update
$ sudo apt-get install python3.6 -y
$ pip3 install --upgrade pip

You should now have 2 binaries: python3 and pip3 available in your $PATH. You can check the versions as below

$ python3 --version
Python 3.6.9
$ pip3 --version
pip 20.1 from <user-path>.local/lib/python3.6/site-packages/pip (python 3.6)

The CentOS 7 Linux distribution includes Python 2 by default. However, as of CentOS 7.7, Python 3 is available in the base package repository which can be installed using the following commands

$ sudo yum update -y
$ sudo yum install -y python3
$ pip3 install --upgrade pip

For versions prior to 7.7 you can install python3.6 using third-party repositories, such as the IUS repository

$ sudo yum update -y
$ sudo yum install yum-utils
$ sudo yum install https://centos7.iuscommunity.org/ius-release.rpm
$ sudo yum install python36u
$ pip3 install --upgrade pip

You can check the versions

$ python3 --version
Python 3.6.8
$ pip --version
pip 20.1 from <user-path>.local/lib/python3.6/site-packages/pip (python 3.6)

3.1.1. Using Virtualenv for Python

Many a times users face issues in installing and managing multiple python versions. This is actually a major issue as many gui elements in Linux use the default python versions, in which case installing python3.6 using the above methods might break other software. We thus advise the use of pyenv to install python3.6.

For Ubuntu and CentosOS, please follow the steps here: https://github.com/pyenv/pyenv#basic-github-checkout

RHEL users can find more detailed guides for virtual-env here: https://developers.redhat.com/blog/2018/08/13/install-python3-rhel/#create-env

Once you have pyenv installed do the following to install python 3.6.0:

$ pyenv install 3.6.0
$ pip3 install --upgrade pip
$ pyenv shell 3.6.0

You can check the version in the same shell:

$ python --version
Python 3.6.0
$ pip --version
pip 20.1 from <user-path>.local/lib/python3.6/site-packages/pip (python 3.6)

3.2. Install RISCOF

To install RISCOF, run this command in your terminal:

$ pip3 install git+https://gitlab.com/incoresemi/riscof.git

This is the preferred method to install RISCOF, as it will always install the most recent stable release.

If you don’t have pip installed, this Python installation guide can guide you through the process.

Note

If you are using pyenv as mentioned above, make sure to enable that environment before performing the following steps.

$ pip3 install riscof

To update an already installed version of RISCOF to the latest version:

$ pip3 install -U riscof

To checkout a specific version of RISCOF:

$ pip3 install riscof==1.x.x

The sources for RISCOF can be downloaded from the GitLab repo.

You can clone the repository:

$ git clone https://gitlab.com/incoresemi/riscof.git

Once you have a copy of the source, you can install it with:

$ cd riscof
$ pip3 install --editable .

3.3. Test RISCOF

Once you have installed RISCOF you can execute riscof --help to print the help routine:

usage: riscof [-h] [--version] [--verbose]
              {gendb,setup,validateyaml,run,testlist} ...

This program checks compliance for a DUT.

optional arguments:
  --verbose             [Default=info]
  --version, -v         Print version of RISCOF being used
  -h, --help            show this help message and exit

Action:
  The action to be performed by riscof.

  {gendb,setup,validateyaml,run,testlist}
                        List of actions supported by riscof.
    gendb               Generate Database for the standard suite.
    setup               Initiate setup for riscof.
    validateyaml        Validate the Input YAMLs using riscv-config.
    run                 Run the tests on DUT and reference and compare
                        signatures.
    testlist            Generate the test list for the given DUT and suite.
                        Uses the architectural suite by default.
Action 'gendb'

      usage: riscof gendb [-h] [--suite PATH]

      optional arguments:
        --suite PATH  The Path to the custom suite directory.
        -h, --help    show this help message and exit

Action 'setup'

      usage: riscof setup [-h] [--dutname NAME] [--refname NAME]

      optional arguments:
        --dutname NAME  Name of DUT plugin. [Default=spike]
        --refname NAME  Name of Reference plugin. [Default=riscvOVPsim]
        -h, --help      show this help message and exit

Action 'validateyaml'

      usage: riscof validateyaml [-h] [--config PATH]

      optional arguments:
        --config PATH  The Path to the config file. [Default=./config.ini]
        -h, --help     show this help message and exit

Action 'run'

      usage: riscof run [-h] [--config PATH] [--suite PATH] [--no-browser]

      optional arguments:
        --config PATH  The Path to the config file. [Default=./config.ini]
        --no-browser   Do not open the browser for showing the test report.
        --suite PATH   The Path to the custom suite directory.
        -h, --help     show this help message and exit

Action 'testlist'

      usage: riscof testlist [-h] [--config PATH] [--suite PATH]

      optional arguments:
        --config PATH  The Path to the config file. [Default=./config.ini]
        --suite PATH   The Path to the custom suite directory.
        -h, --help     show this help message and exit

3.4. Install RISCV-GNU Toolchain

This guide will use the 32-bit riscv-gnu tool chain to compile the architectural suite. If you already have the 32-bit gnu-toolchain available, you can skip to the next section.

Note

The git clone and installation will take significant time. Please be patient. If you face issues with any of the following steps please refer to https://github.com/riscv/riscv-gnu-toolchain for further help in installation.

$ sudo apt-get install autoconf automake autotools-dev curl python3 libmpc-dev \
      libmpfr-dev libgmp-dev gawk build-essential bison flex texinfo gperf libtool \
      patchutils bc zlib1g-dev libexpat-dev
$ git clone --recursive https://github.com/riscv/riscv-gnu-toolchain
$ git clone --recursive https://github.com/riscv/riscv-opcodes.git
$ cd riscv-gnu-toolchain
$ ./configure --prefix=/path/to/install --with-arch=rv32gc --with-abi=ilp32d # for 32-bit toolchain
$ [sudo] make # sudo is required depending on the path chosen in the previous setup
$ sudo yum install autoconf automake python3 libmpc-devel mpfr-devel gmp-devel \
      gawk  bison flex texinfo patchutils gcc gcc-c++ zlib-devel expat-devel
$ git clone --recursive https://github.com/riscv/riscv-gnu-toolchain
$ git clone --recursive https://github.com/riscv/riscv-opcodes.git
$ cd riscv-gnu-toolchain
$ ./configure --prefix=/path/to/install --with-arch=rv32gc --with-abi=ilp32d # for 32-bit toolchain
$ [sudo] make # sudo is required depending on the path chosen in the previous setup

Make sure to add the path /path/to/install to your $PATH in the .bashrc/cshrc With this you should now have all the following available as command line arguments:

riscv32-unknown-elf-addr2line      riscv32-unknown-elf-elfedit
riscv32-unknown-elf-ar             riscv32-unknown-elf-g++
riscv32-unknown-elf-as             riscv32-unknown-elf-gcc
riscv32-unknown-elf-c++            riscv32-unknown-elf-gcc-8.3.0
riscv32-unknown-elf-c++filt        riscv32-unknown-elf-gcc-ar
riscv32-unknown-elf-cpp            riscv32-unknown-elf-gcc-nm
riscv32-unknown-elf-gcc-ranlib     riscv32-unknown-elf-gprof
riscv32-unknown-elf-gcov           riscv32-unknown-elf-ld
riscv32-unknown-elf-gcov-dump      riscv32-unknown-elf-ld.bfd
riscv32-unknown-elf-gcov-tool      riscv32-unknown-elf-nm
riscv32-unknown-elf-gdb            riscv32-unknown-elf-objcopy
riscv32-unknown-elf-gdb-add-index  riscv32-unknown-elf-objdump
riscv32-unknown-elf-ranlib         riscv32-unknown-elf-readelf
riscv32-unknown-elf-run            riscv32-unknown-elf-size
riscv32-unknown-elf-strings        riscv32-unknown-elf-strip

3.5. Install Plugin Models

This section will walk your throguh installing 2 important RISC-V reference models: Spike and SAIL. These are often used as reference models in RISCOF.

$ git clone https://github.com/riscv/riscv-isa-sim.git
$ cd riscv-isa-sim
$ mkdir build
$ cd build
$ ../configure --prefix=/path/to/install
$ make
$ [sudo] make install #sudo is required depending on the path chosen in the previous setup

Make sure to add the path /path/to/install to your $PATH in the .bashrc/cshrc Once installed, executing spike on the terminal should print the following:

usage: spike [host options] <target program> [target options]
Host Options:
  -p<n>                 Simulate <n> processors [default 1]
  -m<n>                 Provide <n> MiB of target memory [default 2048]
  -m<a:m,b:n,...>       Provide memory regions of size m and n bytes
                          at base addresses a and b (with 4 KiB alignment)
  -d                    Interactive debug mode
  -g                    Track histogram of PCs
  -l                    Generate a log of execution
  -h                    Print this help message
  -H                    Start halted, allowing a debugger to connect
  --isa=<name>          RISC-V ISA string [default RV64IMAFDC]
  --pc=<address>        Override ELF entry point
  --hartids=<a,b,...>   Explicitly specify hartids, default is 0,1,...
  --ic=<S>:<W>:<B>      Instantiate a cache model with S sets,
  --dc=<S>:<W>:<B>        W ways, and B-byte blocks (with S and
  --l2=<S>:<W>:<B>        B both powers of 2).
  --extension=<name>    Specify RoCC Extension
  --extlib=<name>       Shared library to load
  --rbb-port=<port>     Listen on <port> for remote bitbang connection
  --dump-dts            Print device tree string and exit
  --disable-dtb         Don't write the device tree blob into memory
  --progsize=<words>    Progsize for the debug module [default 2]
  --debug-sba=<bits>    Debug bus master supports up to <bits> wide accesses [default 0]
  --debug-auth          Debug module requires debugger to authenticate
$ sudo apt-get install opam
$ opam switch create 4.06.1
$ eval $(opam config env)
$ sudo apt-get install build-essential libgmp-dev z3 pkg-config zlib1g-dev
$ git clone https://github.com/rems-project/sail-riscv.git
$ cd sail-riscv
$ make
$ ARCH=RV32 make

This will create a C simulator in c_emulator/riscv_sim_RV64` and ``c_emulator/riscv_sim_RV32. You will not need to add these paths in your $PATH or an alias to it to execute them from command line.

3.6. Create Neccesary Env Files

RISCOF requires python plugins for each model (DUT and Reference) to be submitted. These plugins provide a quick and standard way of building the model, compiling the tests and executing the tests on the models. Along with the python plugins of each model, one would also have to provide the YAML configuration files of the DUT as per the norms of riscv-config. Some models might also require special macros to be executed as prelude or post-testing. These macros can be provided to RISCOF as a header file: compliance_model.h.

For the sake of this guide, we will use some of the pre-built plugins for riscof available at: riscof-plugins. We will specifically use the spike_simple and sail_cSim plugins.

Note

If you are using pyenv as mentioned above, make sure to enable that environment before performing the following steps since we will now start using riscof.

$ git clone https://gitlab.com/incoresemi/riscof-plugins.git

To create necessary environment files use the following command:

$ riscof setup --dutname=spike_simple --refname=sail_cSim

The above command will generate a file named config.ini and a folder named spike_simple. The config.ini file is used to capture specific paths of the plugins of reference and DUT model, along with the paths to isa and platform input YAMLs. The folder spike_simple contains various templates of files that would be required for compliance of any generic DUT. Components of this folder will be modified by the user as per the DUT spec. Since we are going to use pre-built plugins for this guide, we will ignore the spike_simple folder for now.

Note

For specific examples on modifications to environment files, please check the corresponding files for various targets available in the riscof-plugins directory.

Based on the path you have downloaded the riscof-plugins directory, you will need to modify the config.ini file to look similar to the following:

[RISCOF]
ReferencePlugin=sail_cSim
ReferencePluginPath=/path/to/riscof-plugins/sail_cSim
DUTPlugin=spike_simple
DUTPluginPath=/path/to/riscof-plugins/spike_simple

## Example configuration for spike plugin.
[spike_simple]
pluginpath=/path/to/riscof-plugins/spike_simple/
ispec=/path/to/riscof-plugins/spike_simple/spike_simple_isa.yaml
pspec=/path/to/riscof-plugins/spike_simple/spike_simple_platform.yaml

[sail_cSim]
pluginpath=/path/to/riscof-plugins/sail_cSim

We are now ready to run compliance via RISCOF

3.7. Running RISCOF

The RISCOF run is divided into three steps as shown in the overview Figure. The first step is to check if the input yaml files are configured correctly. This step internally calls the riscv-config on both the isa and platform yaml files indicated in the config.ini file.

riscof validateyaml --config=config.ini

This should print the following:

[INFO]    : Reading configuration from: /scratch/git-repo/incoresemi/riscof-plugins/config.ini
[INFO]    : Preparing Models
[INFO]    : Input-ISA file
[INFO]    : Loading input file: /scratch/git-repo/incoresemi/riscof-plugins/spike_simple/sample_isa.yaml
[INFO]    : Load Schema /home/neel/.pyenv/versions/3.7.0/envs/venv/lib/python3.7/site-packages/riscv_config/schemas/schema_isa.yaml
[INFO]    : Initiating Validation
[INFO]    : No Syntax errors in Input ISA Yaml. :)
[INFO]    : Dumping out Normalized Checked YAML: /scratch/git-repo/incoresemi/riscof-plugins/riscof_work/sample_isa_checked.yaml
[INFO]    : Input-Platform file
[INFO]    : Loading input file: /scratch/git-repo/incoresemi/riscof-plugins/spike_simple/sample_platform.yaml
[INFO]    : Load Schema /home/neel/.pyenv/versions/3.7.0/envs/venv/lib/python3.7/site-packages/riscv_config/schemas/schema_platform.yaml
[INFO]    : Initiating Validation
[INFO]    : No Syntax errors in Input Platform Yaml. :)
[INFO]    : Dumping out Normalized Checked YAML: /scratch/git-repo/incoresemi/riscof-plugins/riscof_work/sample_platform_checked.yaml

The next step is generate the list of tests that need to be run on the models for declaring compliance.

riscof testlist --config=config.ini

This step calls the validate-step and thus the output adds one more line to the above dump:

[INFO]    : Selecting Tests.

The tests are listed in the file: riscof_work/test_list.yaml which should probably look something similar to the following:

suite/rv32i_m/C/C-ADD.S:
  work_dir: /scratch/git-repo/incoresemi/riscof-plugins/riscof_work/rv32i_m/C/C-ADD.S
  macros: [TEST_CASE_1=True, XLEN=32]
  isa: RV32IC
  test_path: /home/neel/.pyenv/versions/3.7.0/envs/venv/lib/python3.7/site-packages/riscof/suite/rv32i_m/C/C-ADD.S
suite/rv32i_m/C/C-ADDI.S:
  work_dir: /scratch/git-repo/incoresemi/riscof-plugins/riscof_work/rv32i_m/C/C-ADDI.S
  macros: [TEST_CASE_1=True, XLEN=32]
  isa: RV32IC
  test_path: /home/neel/.pyenv/versions/3.7.0/envs/venv/lib/python3.7/site-packages/riscof/suite/rv32i_m/C/C-ADDI.S
suite/rv32i_m/C/C-ADDI16SP.S:
  work_dir: /scratch/git-repo/incoresemi/riscof-plugins/riscof_work/rv32i_m/C/C-ADDI16SP.S
  macros: [TEST_CASE_1=True, XLEN=32]
  isa: RV32IC
...
...
...

The last step is to run the tests on the each of the models and compare the signature values to guarantee correctness.

riscof run --config=config.ini

This should compile and execute the tests on each of the models and end up with the following log. The run will also open an HTML page with all the information.

...
...
...
[INFO]    : Initiating signature checking.
[INFO]    : Following 55 tests have been run :

[INFO]    : TEST NAME                                          : COMMIT ID                                : STATUS
[INFO]    : suite/rv32i_m/I/I-ADD-01.S                         : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-ADDI-01.S                        : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-AND-01.S                         : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-ANDI-01.S                        : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-AUIPC-01.S                       : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-BEQ-01.S                         : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-BGE-01.S                         : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-BGEU-01.S                        : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-BLT-01.S                         : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-BLTU-01.S                        : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-BNE-01.S                         : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-CSRRC-01.S                       : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-CSRRCI-01.S                      : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-CSRRS-01.S                       : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-CSRRSI-01.S                      : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-CSRRW-01.S                       : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-CSRRWI-01.S                      : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-DELAY_SLOTS-01.S                 : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-EBREAK-01.S                      : 3a4a3a576666d5153ae6a844e74a45f953245e57 : Passed
[INFO]    : suite/rv32i_m/I/I-ECALL-01.S                       : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-ENDIANESS-01.S                   : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-FENCE.I-01.S                     : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-IO.S                             : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-JAL-01.S                         : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-JALR-01.S                        : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-LB-01.S                          : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-LBU-01.S                         : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-LH-01.S                          : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-LHU-01.S                         : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-LUI-01.S                         : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-LW-01.S                          : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-MISALIGN_JMP-01.S                : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-MISALIGN_LDST-02.S               : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-NOP-01.S                         : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-OR-01.S                          : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-ORI-01.S                         : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-RF_size-01.S                     : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-RF_width-01.S                    : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-RF_x0-01.S                       : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-SB-01.S                          : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-SH-01.S                          : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-SLL-01.S                         : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-SLLI-01.S                        : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-SLT-01.S                         : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-SLTI-01.S                        : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-SLTIU-01.S                       : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-SLTU-01.S                        : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-SRA-01.S                         : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-SRAI-01.S                        : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-SRL-01.S                         : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-SRLI-01.S                        : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-SUB-01.S                         : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-SW-01.S                          : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-XOR-01.S                         : d50921ef64708678832770fd842355aa2b0684af : Passed
[INFO]    : suite/rv32i_m/I/I-XORI-01.S                        : d50921ef64708678832770fd842355aa2b0684af : Passed