Getting started

git clone https://github.com/black-parrot/pre-alpha-release.git
# make tools will clone, build and install toolchains needed for BlackParrot
# For faster builds, make tools -j is parallelizable!
make tools
# make tidy_tools will remove all tool build directories, while leaving the installation
# make progs will build all open source test programs that ship with BlackParrot
make progs
# make ucode will build the CCE microcode used for BlackParrot's coherence engine
# This is necessary whenever changes are made to CCE ucode. Eventually, CCE ucode
#  will be built 'on demand' and so this command may become unnecessary
make ucode

The master branch contains most recent stable version. This is the recommended branch for someone wishing to try out BlackParrot.

The dev branch contains the most recent development version, being tested internally. This branch may have bugfixes or improvements not yet propagated to master.

Other branches are used for internal development and are not recommended for casual usage.

Running your first test

cd bp_top/syn
make build.sc sim.sc PROG=hello_world

Prerequisites

BlackParrot requires Python, Verilator and a RISCV GNU toolchain in order to build and run tests. The easiest way to get these and ensure compatibility is by using the tools in external/, which the Makefiles are automatically set up to use. One can also override these paths in Makefile.common. Dependencies for riscv-gnu-toolchain are listed below:

Centos

yum install autoconf automake libmpc-devel mpfr-devel gmp-devel gawk  bison flex texinfo patchutils gcc gcc-c++ zlib-devel expat-devel

Ubuntu

sudo apt-get install autoconf automake autotools-dev curl libmpc-dev libmpfr-dev libgmp-dev gawk build-essential bison flex texinfo gperf libtool patchutils bc zlib1g-dev libexpat-dev

BlackParrot has been tested extensively on CentOS 7. Please raise issues with problems found on this or other platforms!

Running tests

BlackParrot is designed to be modular. The main testbenches are at the FE, BE, ME and TOP levels. The general syntax for running a testbench is:

cd bp_<end>/syn
make <ACTION>.<TOOL> [TB=] [CFG=] [PROG=] [DUMP=] [COV=] [<TRACER>_P=]

Supported ACTIONs

  • lint (lints the DUT of a single testbench)
  • build (builds a single testbench)
  • sim (runs a single test)
  • check_design (checks for DC elaborability, which is a proxy for synthesizability)
  • regress (runs a suite of tests, only defined for select testbenches)

Supported TOOLs

  • Verilator
  • Synopsys VCS
  • Synopsys DC

NOTE: Verilator is the free, open-source tool used to evaluate BlackParrot. VCS and DC are used for simulation and synthesis. If you wish to use these tools, set up the appropriate environment variables in Makefile.common

Supported TBs

  • Found in bp_<end>/test/tb/

Supported CFGs

  • Found in bp_common/src/include/bp_common_aviary_pkg.vh
  • List of system parameters passed to most modules in BlackParrot

Supported PROGs

  • Found in bp_common/test/mem
  • Verilog hex format, generated by make progs

Supported DUMP

  • 1 to dump a vcd

Supported COV

  • 1 to generate line and toggle coverage data

Supported TRACERs

  • CMT_TRACE_P = trace each commit which writes to a GPR, used for automatic spike diffing
  • CALC_TRACE_P = trace the Calculator pipeline (warning, large logfiles)
  • CCE_TRACE_P = trace coherence traffic between the LCEs and CCEs

Example commands

make build.v sim.v PROG=hello_world DUMP=1  # Run hello_world in VCS with dumping
make dve.v PROG=hello_world                 # Open hello_world waveform in dve
make build.sc sim.sc PROG=hello_world COV=1 # Run hello_world in Verilator with coverage

make regress.sc -j 10                       # Run riscv-tests in Verilator with 10 threads
make regress_beebs.v -j 5                   # Run beebs suite in VCS with 5 threads

NOTE: pardon our dust as we update our testbenches. The main testbench bp_top testbench is well supported.

Examining results

Running a test will generate a ton of subdirectories in bp_<end>/syn/

    bp_<end>/syn/results/<tool>/<tb>.<cfg>.build/sim{v,sc}
    bp_<end>/syn/results/<tool>/<tb>.<cfg>.sim.<prog>/(symlink to sim{v,sc})
    bp_<end>/syn/results/<tool>/<tb>.<cfg>.sim.<prog>/dump.vcd
    bp_<end>/syn/results/<tool>/<tb>.<cfg>.sim.<prog>/testbench.v
    bp_<end>/syn/results/<tool>/<tb>.<cfg>.sim.<prog>/etc.
    bp_<end>/syn/results/<tool>/<tb>.<cfg>.cov/*.dat

    bp_<end>/syn/logs/<tool>/<tb>.<cfg>.build.log
    bp_<end>/syn/logs/<tool>/<tb>.<cfg>.sim.<prog>.log
    bp_<end>/syn/logs/<tool>/<tb>.<cfg>.cov.log

    bp_<end>/syn/reports/<tool>/<tb>.<cfg>.build.{rpt,err}
    bp_<end>/syn/reports/<tool>/<tb>.<cfg>.sim.<prog>.{rpt,err}
    bp_<end>/syn/reports/<tool>/<tb>.<cfg>.cov.<prog>.{rpt,err}

results

Run directory for tools, generating output artifacts

logs

Full output of tool runs

reports

Summary of tool runs. For example, whether tests pass or fail