Bringup and Verification

MIAOW was developed using Synopsys VCS. As such the majority of the infrastructure for running tests and analysis is built around VCS. When building or running the tests, it is assumed that the user has sourced the environment script that comes with a VCS install. The build also makes use of PERL for template expansion of certain files. Building of MIAOW has been tested on Linux systems only.

####Building MIAOW Dependencies involved:

• PERL
• Synopsys VCS Simulator

The following are the step by step instructions for building MIAOW and running various unit tests and benchmarks.

1. Clone MIAOW to a local directory. We will reference it as $TOP_DIR in the following steps.
2. Go to the testbench folder
   cd $TOP_DIR/src/verilog/tb
3. Source the environment script of a VCS install. Ex: source setup_synopsys (setup_synopsis is the environment script for VCS)
4. make clean - Ensure a clean working directory.
5. make build - Creates verilog files from .vp files in $TOP_DIR/src/verilog/rtl/<module>. Creates build directory with verilog files under each <module>.
6. make compile - Compiles all the verilog files and creates a vcs executable ./simv in the tb dir. If there is no file named simv, then there was an error in the compilation process. Check the build logs to determine the cause and resolve it before trying again.

Running VCS simulations (unit tests and benchmarks):

MIAOW comes with a collection of unit tests and benchmarks. The unit tests are for verifying functional correctness and conformance with the Southern Islands instructions. The benchmarks are a collection of programs drawn from the AMD APP SDK as well as the rodinia suite. Included with the benchmarks and unit tests are instruction traces and memory dumps generated by Multi2Sim. These traces are the references used to verify functional correctness of MIAOW. How to generate these reference traces are detailed in the Extending Walkthrough.

• The steps here assume that the instruction traces and configuration files are already generated and are available at:
  $TOP_DIR/src/sw/{benchmarks, miaow_unit_tests}.
• It is also assumed that you have already compiled the verilog files and have a vcs executable ready.

Following steps will walk you through to run unit tests and benchmarks in MIAOW:

1. cd $TOP_DIR/src/verilog/tb

2. The run.pl file in the tb directory is the script to run tests and benchmarks on MIAOW GPU. Below is how to use the script to specify the test from a specified category and produce the results in an OUT_DIR.

   run.pl -r <TEST_GROUP> -t <TEST_NAME> -o <OUT_DIR>

   where:
   TEST_GROUP - is the test group present at $TOP_DIR/src/sw/ hierarchy
   0 - benchmarks
   1 - miaow_unit_tests
   2 - rodinia

   TEST_NAME: regular expression that matches the test name. If you want only one test, just type the name of the test. If you want all the tests to be executed, type *.
   Ex: "Binary" executes the BinarySearch benchmark
   "test_00" executes all the unit tests whose name starts with test_00
   [See $TOP_DIR/src/sw/{benchmarks, miaow_unit_tests} directory for other test names]

   OUT_DIR: name of the directory where the results will be written. After the test finishes, the OUT_DIR will be in this path: $TOP_DIR/src/verilog/tb/results/<OUT_DIR> folder.

Example: run.pl -r 0 -t BinarySearch -o bs_1 - Runs binary search and dumps the results in $TOP_DIR/src/verilog/tb/results/bs_1 folder.

Use run.pl -h for details about other options, including -w for dumping waveforms.

The content of the $TOP_DIR/src/verilog/tb/results/<OUT_DIR> is explained below:

• Trace comparison summary and to check whether the test/s FAILED or PASSED can be found at: results/<OUT_DIR>/summary.txt
• Test run log can be found at: results/<OUT_DIR>/<test_name>/run.log
• Generated trace with list of instructions can be found at: results/<OUT_DIR>/<test_name>/tracemon.out
• Reference (Golden) trace with list of instructions can be found at: results/<OUT_DIR>/<test_name>/<test_name>_trace
• If there are multiple kernels in a test, then traces will be generated in each kernel folder i.e, results/<OUT_DIR>/<test_name>/kernel_X/tracemon_X_X_X.out
  where, kernel_X refers to kernel_number and tracemon_X_X_X refers to {kernel_number, workgroup_number and wavefront_number respectively.}
• Generated trace with only opcodes can be found at: results/<OUT_DIR>/<test_name>/<test_name>/kernel_X/<test_name>_trace_X_X_X.verilog
• Reference (Golden) trace with only opcodes can be found at: results/<OUT_DIR>/<test_name>/<test_name>/kernel_X/<test_name>_trace_X_X_X.gold
• To do a diff and find out, where the test is failing, do:
  diff <test_name>_trace_X_X_X.gold <test_name>_trace_X_X_X.verilog

Opening waveforms using vcs DVE for debugging:
Running benchmarks and tests produce variety of outputs, including instruction traces and waveforms. To view the waveform using VCS, follow the steps below:

1. Make sure the vcs dve is in your $PATH.
2. cd $TOP_DIR/src/verilog/tb/results/<OUT_DIR>/<test_name>
3. make browse

###Synthesis - TO BE UPDATED SOON
To perform hardware analysis such as area and power, a separate set of scripts is needed.