Update Breker documentation

Makefile

@@ -39,6 +39,7 @@ coverage:
 cvw-arch-verif:
 	$(MAKE) -C ${WALLY}/addins/cvw-arch-verif
 
+# Requires a license for the Breker tool. See tests/breker/README.md for details
 breker:
 	$(MAKE) -C ${WALLY}/testbench/trek_files
 	$(MAKE) -C ${WALLY}/tests/breker

bin/regression-wally

@@ -401,7 +401,7 @@ parser.add_argument("--nightly", help="Run large nightly regression", action="st
 parser.add_argument("--buildroot", help="Include Buildroot Linux boot test (takes many hours, done along with --nightly)", action="store_true")
 parser.add_argument("--testfloat", help="Include Testfloat floating-point unit tests", action="store_true")
 parser.add_argument("--fp", help="Include floating-point tests in coverage (slower runtime)", action="store_true") # Currently not used
-parser.add_argument("--breker", help="Run Breker tests", action="store_true")
+parser.add_argument("--breker", help="Run Breker tests", action="store_true") # Requires a license for the breker tool. See tests/breker/README.md for details
 parser.add_argument("--dryrun", help="Print commands invoked to console without running regression", action="store_true")
 args = parser.parse_args()
 

bin/wsim

@@ -110,7 +110,7 @@ def prepSim(args, ElfFile):
     if args.lockstep or args.lockstepverbose or args.fcov:
         prefix = lockstepSetup(args)
         defineList.append("+define+USE_IMPERAS_DV")
-    if args.config == "breker":
+    if args.config == "breker": # Requires a license for the breker tool. See tests/breker/README.md for details
         ElfFileNoExtension = os.path.splitext(ElfFile)[0]
         flagsList.append("--breker")
         defineList.append("+define+USE_TREK_DV")

config/derivlist.txt

@@ -1432,6 +1432,8 @@ UART_SUPPORTED      0
 PLIC_SUPPORTED      0
 SPI_SUPPORTED       0
 
+# Breker tests require a different memory configuration
+# See tests/breker/README.md for details on the testsuite
 derive breker rv64gc
 EXT_MEM_SUPPORTED   1
 EXT_MEM_BASE        64'h90000000

sim/questa/wally.do

@@ -130,6 +130,7 @@ if {[lcheck lst "--lockstep"] || $FunctCoverage == 1} {
 }
 
 # if --breker found set flag and remove from list
+# Requires a license for the breker tool. See tests/breker/README.md for details
 if {[lcheck lst "--breker"]} {
     set breker 1
     set BREKER_HOME $::env(BREKER_HOME)

testbench/testbench.sv

@@ -46,6 +46,7 @@ module testbench;
   parameter RVVI_SYNTH_SUPPORTED=0;
   parameter MAKE_VCD=0;
 
+  // TREK Requires a license for the Breker tool. See tests/breker/README.md for details
   `ifdef USE_TREK_DV
     event trek_start;
     always @(testbench.trek_start) begin

testbench/trek_files/README.md

@@ -0,0 +1,9 @@
+Jordan Carlin, jcarlin@hmc.edu, December 2024
+
+# Breker Trek Tests Support Files for CVW
+
+[Breker's Trek Test Suite](https://brekersystems.com/products/trek-suite/) is a proprietary set of tests that require a license to use (this license is not generally available to noncommercial users).
+
+This directory contains the support files necessary to run Breker's Trek Tests on CVW. For additional details on the tests see [`$WALLY/tests/breker/README.md`](../../tests/breker/README.md)
+
+To generate the Breker support files (with a license), run `make` in the `testbench/trek_files` directory (this one). Before running, make sure to set `$BREKER_HOME` in your system's `site-setup.sh` file. This Makefile only needs to be run once.

tests/breker/README.md

@@ -0,0 +1,18 @@
+Jordan Carlin, jcarlin@hmc.edu, December 2024
+
+# Breker Tests for CVW
+
+[Breker's Trek Test Suite](https://brekersystems.com/products/trek-suite/) is a proprietary set of tests that require a license to use (this license is not generally available to noncommercial users).
+
+To generate the Breker tests (with a license), run `make` in both the `tests/breker` and `testbench/trek_files` directories. Alternatively, running `make breker` from the top-level `$WALLY` directory will run both of these. Before running, make sure to set `$BREKER_HOME` in your system's `site-setup.sh` file. The `testbench/trek_files` Makefile only needs to be run once, but the tests that are generated can be different each time so rerunning the `tests/breker` Makefile is worthwhile.
+
+This will generate a testsuite for each of the constraint yaml files in the `constraints` directory. These generated tests are produced in the `tests/breker/work` directory. To run a single test use `wsim` to run the elf. The `breker` configuration must be used. For example,
+
+```bash
+$ wsim breker $WALLY/tests/breker/riscv/riscv.elf
+```
+
+To run all of the generated Breker tests use 
+```bash
+$ regression-wally --breker
+```