third_party/tests/BlackParrot/GETTING_STARTED.md

# 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