shell
Ubuntu
Ubuntu 17.10 and 18.04 by default come with python-3.6.9 which is sufficient for using riscv-isac.
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)
CentOS7
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)
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)
.. tab:: via git To install RISC-V ISA Coverage Tool, run this command in your terminal:
$ python3 -m pip3 install git+https://github.com/riscv/riscv-isac.git
This is the preferred method to install RISC-V ISA Coverage, 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.
via pip
Note
If you are using pyenv as mentioned above, make sure to enable that environment before performing the following steps.
$ pip3 install riscv_isacTo update an already installed version of RISCV-ISAC to the latest version:
$ pip3 install -U riscv_isacTo checkout a specific version of riscv_isac:
$ pip3 install riscv_isac==1.x.xfor Dev
The sources for RISC-V ISA Coverage Tool can be downloaded from the Github repo.
You can clone the repository:
$ git clone https://github.com/riscv/riscv-isac
Once you have a copy of the source, you can install it with:
$ cd riscv_isac $ pip3 install --editable .
Once you have RISCV-ISAC installed, executing riscv_isac --help
should print the following on the terminal. :
Options:
--version Show the version and exit.
-v, --verbose [info|error|debug]
Set verbose level
--help Show this message and exit.
Commands:
coverage Run Coverage analysis on tracefile.
merge Merge given coverage files.
normalize Normalize the cgf.
RISCV-ISAC has three commands : coverage
, merge
and normalize
which are described below. Help text for each command can be accessed by executing riscv_isac <command> --help
Coverage
Usage: riscv_isac coverage [OPTIONS]
Run Coverage analysis on tracefile.
Options:
-e, --elf PATH ELF file
-t, --trace-file PATH Instruction trace file to be analyzed
[required]
-c, --cgf-file PATH Coverage Group File(s). Multiple allowed.
[required]
-d, --detailed Select detailed mode of coverage printing
--parser-name NAME Parser plugin name. Parsers shipped with
ISAC - [c_sail, spike] [default: c_sail]
--decoder-name NAME Decoder plugin name. Decoders shipped with
ISAC - [internaldecoder] [default:
internaldecoder]
--parser-path PATH Parser file path
--decoder-path PATH Decoder file path
-o, --output-file PATH Coverage Group File
--test-label LABEL_START LABEL_END
Pair of labels denoting start and end points
of the test region(s). Multiple allowed.
--sig-label LABEL_START LABEL_END
Pair of labels denoting start and end points
of the signature region(s). Multiple
allowed.
--dump PATH Dump Normalized Coverage Group File
-l, --cov-label COVERAGE LABEL Coverage labels to consider for this run.
-x, --xlen [32|64] XLEN value for the ISA.
--help Show this message and exit.
Merge
Usage: riscv_isac merge [OPTIONS] [FILES]...
Merge given coverage files.
Options:
-d, --detailed Select detailed mode of coverage printing
-c, --cgf-file PATH Coverage Group File [required]
-o, --output-file PATH Coverage Group File.
--help Show this message and exit.
Normalize
Usage: riscv_isac normalize [OPTIONS]
Normalize the cgf.
Options:
-c, --cgf-file PATH Coverage Group File [required]
-o, --output-file PATH Coverage Group File [required]
-x, --xlen [32|64] XLEN value for the ISA.
--help Show this message and exit.
There are 3 different operations which can be performed by RISC-V ISAC namely,
- coverage - Calculate the coverage of a test using the given log and cgf file(s).
- merge - Merge different coverage reports to produce a single report with all statistics.
- normalize - Dump a cgf file without any yaml anchors and abstract functions. The output file will contain the elaborated coverpoints as specified by the input cgf file(s).
The CGF file(s) used in these examples can be obtained from here.
Example usage of each of the commands are given below: