Picker: Pick your favorite language to verify your chip.

A codegen tool for chip verification, which can provide C++/Python interfaces for the RTL designs.

English | 中文

Introduction

picker is a chip verification auxiliary tool with two main functions:

1. Export RTL designs into verification modules: Picker can convert RTL design verification modules (.v/.scala/.sv) into dynamic libraries and provide programming interfaces in multiple high-level languages (currently supporting C++, Python, Java, Scala, Golang, Lua) to drive the circuits.
2. Pack UVM-TLM transaction with other languages: Picker can automatically encapsulate TLM code based on user-provided UVM sequence_items, providing communication interfaces between UVM and other high-level languages (such as Python).

This tool allows users to perform chip unit testing based on existing software testing frameworks, such as pytest, junit, TestNG, go test, etc.

Advantages of verification based on picker:

1. No RTL design leakage: After conversion by picker, the original design files (.v) are transformed into binary files (.so). Verification can still be performed without the original design files, and the verifier cannot access the RTL source code.
2. Reduced compilation time: When the DUT (Design Under Test) is stable, it only needs to be compiled once (packaged into a .so file).
3. Wide user range: Provides multiple programming interfaces, covering developers of different languages.
4. Utilizes rich software ecosystems: Supports ecosystems such as Python3, Java, Golang.
5. Automated UVM transaction encapsulation: Achieves communication between UVM and Python through automated UVM transaction encapsulation.

Currently supported RTL simulators by picker:

1. Verilator
2. Synopsys VCS
3. GSIM
4. UniVista Simulator (UVS)

How to Use

Dependency Installation

1. CMake (>=3.11)
2. GCC (needs to support C++20, at least version 10, recommended version 11 or above)
3. Python3 (>=3.8)
4. Verilator (>=5.020)
5. SWIG (>=4.2.0, multi-language support)

Source Code Download

git clone https://github.com/XS-MLVP/picker.git --depth=1
cd picker
make init

make init fetches the git-based dependencies under dependence/, including xcomm, slang, and fmt.

Build and Install

cd picker
make
# You can enable support for other languages by
#   using `make BUILD_XSPCOMM_SWIG=python,java,scala,golang,lua`.
# Each language requires its own development environment,
#   which needs to be configured separately, such as `javac` for Java.
# Install to the default prefix (/usr/local)
sudo -E make install

# Or install to a custom prefix, for example:
# make install ARGS="-DCMAKE_INSTALL_PREFIX=$HOME/picker"

Install Prefix

The default installation prefix is /usr/local.

To install picker somewhere else, pass ARGS to the install target:

make install ARGS="-DCMAKE_INSTALL_PREFIX=$HOME/picker"

Installed files follow the selected prefix:

• <prefix>/bin/picker
• <prefix>/share/picker
• <prefix>/lib/libxspcomm.so

If you are installing on macOS and want a complete example that uses a user-owned prefix, see doc/install-macos.en.md.

Use sudo -E make install only when the target prefix requires elevated permissions. If you install under a user-owned directory such as $HOME/picker, sudo is usually unnecessary.

The installation will also install the xspcomm base library (https://github.com/XS-MLVP/xcomm), which is used to encapsulate the basic types of RTL modules. If you compile against it manually, you may need to add the corresponding library search path, such as -L<prefix>/lib.

If support for languages such as Java is enabled, the corresponding xspcomm multi-language packages are installed under the same prefix.

picker can also be compiled into a wheel file and installed via pip

To package picker into a wheel installation package, use the following command:

pip install pipx==1.10.0 # install dependency
make wheel # or BUILD_XSPCOMM_SWIG=python,java,scala,golang,lua make wheel

After compilation, the wheel file will be located in the dist directory. You can then install it via pip, for example:

# Manually install whl packages
pip install dist/xspcomm-0.0.1-cp311-cp311-linux_x86_64.whl
pip install dist/picker-0.0.1-cp311-cp311-linux_x86_64.whl
# Or install using the following make command
make wheel_install

After installation, execute the picker command to expect the following output:

XDut Generate.
Convert DUT(*.v/*.sv) to C++ DUT libs.

Usage: ./build/bin/picker [OPTIONS] [SUBCOMMAND]

Options:
  -h,--help                   Print this help message and exit
  -v,--version                Print version
  --show_default_template_path
                              Print default template path
  --show_xcom_lib_location_cpp
                              Print xspcomm lib and include location
  --show_xcom_lib_location_java
                              Print xspcomm-java.jar location
  --show_xcom_lib_location_scala
                              Print xspcomm-scala.jar location
  --show_xcom_lib_location_python
                              Print python module xspcomm location
  --show_xcom_lib_location_golang
                              Print golang module xspcomm location
  --show_xcom_lib_location_lua
                              Print lua module xspcomm location
  --check                     check install location and supported languages

Subcommands:
  export                      Export RTL Projects Sources as Software libraries such as C++/Python
  pack                        Pack UVM transaction as a UVM agent and Python class

Installation Test

picker currently has two subcommands: export and pack.

The export subcommand is used to convert RTL designs into "libraries" corresponding to other high-level programming languages, which can be driven through software.

$picker export --help

Export RTL Projects Sources as Software libraries such as C++/Python
Usage: picker export [OPTIONS] file...

Positionals:
  file TEXT ... REQUIRED      DUT .v/.sv source file, contain the top module

Options:
  -h,--help                   Print this help message and exit
  --fs,--filelist TEXT ...    DUT .v/.sv source files, contain the top module, split by comma.
                              Or use '*.txt' file  with one RTL file path per line to specify the file list
  --sim TEXT [verilator]      vcs, gsim or verilator as simulator, default is verilator
  --lang,--language TEXT:{python,cpp,java,scala,golang,lua} [python]
                              Build target project with assigned language, default python
  --sdir,--source_dir TEXT [/home/yaozhicheng/workspace/picker/template]
                              Template Files Dir, default is ${picker_install_path}/../picker/template
  --sname,--source_module_name TEXT ...
                              Pick the module in DUT .v file, default is the last module in the -f marked file
  --tname,--target_module_name TEXT
                              Set the module name and file name of target DUT, default is the same as source.
                              For example, -T top, will generate UTtop.cpp and UTtop.hpp with UTtop class
  --tdir,--target_dir TEXT    Target directory to store all the results. If it ends with '/' or is empty,
                              the directory name will be the same as the target module name
  --internal TEXT             Exported internal signal config file, default is empty, means no internal pin
  --checkpoints               Enable checkpoints, save/restore , default is OFF
  --vpi                       Enable VPI, for flexible internal signal access default is OFF
  -F,--frequency TEXT [100MHz]
                              Set the frequency of the **only VCS** DUT, default is 100MHz, use Hz, KHz, MHz, GHz as unit
  -w,--wave_file_name TEXT    Wave file name, empty means don't dump wave
  -c,--coverage               Enable coverage, default is not selected as OFF
  --cp_lib,--copy_xspcomm_lib BOOLEAN [1]
                              Copy xspcomm lib to generated DUT dir, default is true
  -V,--vflag TEXT             User defined simulator compile args, passthrough.
                              Eg: Using vcs simulator for exporting line coverage, -V '"-cm line -cm_dir /abs_path_to_store_coverage_data"'
  -C,--cflag TEXT             User defined gcc/clang compile command, passthrough.
                              Eg: -C '"-O3 -std=c++17 -I./include"'
  --verbose                   Verbose mode
  -e,--example                Build example project, default is OFF
  --autobuild BOOLEAN [1]     Auto build the generated project, default is true
  -j,--build-threads INT [0]  Maximum parallel build threads; 0 uses all available CPU cores

Static Multi-Module Support:

When generating the wrapper for dut_top.sv/v, picker allows specifying multiple module names and their corresponding quantities using the --sname parameter. For example, if there are modules A and B in the design files a.v and b.v respectively, and you need 2 instances of A and 3 instances of B in the generated DUT, and the combined module name is C (if not specified, the default name will be A_B). This can be achieved using the following command:

picker export path/a.v,path/b.v --sname A,2,B,3 --tname C

Environment Variables:

• DUMPVARS_OPTION: Sets the option parameter for $dumpvars. For example, DUMPVARS_OPTION="+mda" picker .... enables array waveform support in VCS.

The pack subcommand is used to convert UVM sequence_item into other languages and then communicate through TLM (currently supports Python, other languages are under development).

$picker pack --help

Pack uvm transaction as a uvm agent and python class
Usage: picker pack [OPTIONS] file...

Positionals:
  file TEXT ... REQUIRED      Sv source file, contain the transaction define

Options:
  -h,--help                   Print this help message and exit
  -e,--example                Generate example project based on transaction, default is OFF
  -c,--force                  Force delete folder when the code has already generated by picker
  -r,--rename TEXT ...        Rename transaction name in picker generate code
  -d,--generate-dut           Generate DUT abstraction class with pin-level interface
  -f,--filelist TEXT ...      File list containing transaction files
  --from-rtl TEXT             RTL source file (.v/.sv) to auto-generate transaction from module ports

Test Examples

After picker compilation, execute the following commands in the picker directory to test the examples:

bash example/Adder/release-verilator.sh --lang cpp
bash example/Adder/release-verilator.sh --lang python

# Default enable cpp and python
#  for other languages support：make BUILD_XSPCOMM_SWIG=python,java,scala,golang,lua
bash example/Adder/release-verilator.sh --lang java
bash example/Adder/release-verilator.sh --lang scala
bash example/Adder/release-verilator.sh --lang golang
bash example/Adder/release-verilator.sh --lang lua

bash example/RandomGenerator/release-verilator.sh --lang cpp
bash example/RandomGenerator/release-verilator.sh --lang python
bash example/RandomGenerator/release-verilator.sh --lang java

More Documents

For guidance on chip verification with picker, please refer to: https://open-verify.cc/mlvp/en/docs/