Skip to content

Latest commit

 

History

History
86 lines (56 loc) · 5 KB

development.md

File metadata and controls

86 lines (56 loc) · 5 KB
Raw

Prerequisites

  1. Vivado 2019.2
  2. Python 3
  3. A few python packages: pip install tqdm rich

Development

The Vivado project file can be found in proj/regex_copro/regex_copro.xpr.

Testing the architecture for a single regex/input

To test if a single regex matches a single input

  1. Generate input/regex files running python3 scripts/generate_single/generate.py 'exampleinput' 'exampleregex'
  2. Update the file paths in hdl_src/sim/AXI_top_tb_from_compiled.sv, so that they match the ones generated by previous step
  3. From Vivado, run the testbench hdl_src/sim/AXI_top_tb_from_compiled.sv

Testing the architecture for many regexes/inputs

To test the correctness of the architecture, you can provide a set of inputs and regexes. A Python script will check the match of each regex with each input, and generate CSV with all the results:

  1. cd scripts/generate_functional_tests
  2. Run python3 generate.py to see usage. For example, you can run python3 generate.py input_protomata_selected.txt protomata_filtered.txt compiled_regexes ../../cicero_compiler/ 0
  3. Update base_path in hdl_src/sim/AXI_top_tb_multiple_tests_from_csv.sv to match the path of scripts/generate_functional_tests
  4. From Vivado, run the testbench hdl_src/sim/AXI_top_tb_multiple_tests_from_csv.sv. It will run all the combination of inputs/regexes and print in case the architecture gives incorrect output.

Synthesis

To synthesize many configuration of the architecture, use scripts/synth/synth.py. For each configuration, it will create a folder within the builds folder. You can specify the configurations you want to synthesize by updating CONFIGURATIONS into scripts/synth/synth.py. To start the synthesis, run python3 scripts/synth/synth.py True True.

After the synthesis, you may want to copy the bitstreams to the FPGA board. An helper script is provided to automatically copy all the bitstreams into a zip file that can easily be copied to the board. For example, if you want to copy all the bitstreams from the builds directory and put the content in a file called myzip.zip, run:

python3 scripts/synth/extract_bitstreams.py "builds/*" myzip.zip

You may also want to compare board usage, Total On-Chip Power (W), and maximum theoretical clock frequency for each configuration. You can use scripts/synth/extract_usage_and_timings.py to output a CSV file that contains relevant information for each configuration you want. For example, you can run:

python3 scripts/synth/extract_usage_and_timings.py "builds/*" cicero_confs_usage_power.csv

Run on board

First, you need to download the regexes and the inputs. Refer to scripts/measurements/README.md for specific instructions.

To run on a board, you can use scripts/measurements/benchmark/measure.py. Make sure to be root, and have all the Python dependencies installed (pip install rich tqdm and pynq). The usage is the following:

Usage: measure.py <bitstream_file_path> <strings_file_path> <regexes_file_path> <output_file_path> <compiler_path> <regexes_count> <inputs_count>

Where:

  1. <bitstream_file_path> is the path of the .bit file, there must also exist a .hwh file alongside it
  2. <strings_file_path> is the path of the file containing the input strings. Each input string must be on a separate line.
  3. <regexes_file_path> is the path of the file containing the regex patterns to be matched against the input strings. Each regex pattern must be on a separate line.
  4. <output_file_path> is the path of the output CSV file.
  5. <compiler_path> is the path to the compiler from Regex to Cicero ISA
  6. <regexes_count> limits the number of regexes to be read from <regexes_file_path>.
  7. <inputs_count> limits the number of input strings to be read from <strings_file_path>.

For example:

python3 measure.py /path/to/bitstream.bit protomata.input protomata.regex results.csv /path/to/cicero_compiler_cpp/ 100 100

To check the correctness of the results, use scripts/measurements/benchmark/check_results.py, by specifying the .csv file and the file with the inputs that was used, for example:

python3 scripts/measurements/benchmark/check_results.py results.csv brill.input

Benchmark on board

For benchmarking, we essentially execute scripts/measurements/benchmark/measure.py over all the desired bitstreams/regexes/inputs/compilers.

A wrapper script is provided, scripts/measurements/benchmark/test_top.py. First, update the constants in scripts/measurements/benchmark/bench_config.py to match the desired configurations you want to benchmark, and then execute test_top.py. A .csv file will be created alongside each .bit file for each compiler/benchmark.

You can then use scripts/measurements/benchmark/aggregate.py to aggregate all the results of the benchmarks. For example, if you want the aggregated output in output.csv and all the .csv from previous step are in the measurements folder, run:

python3 scripts/measurements/benchmark/aggregate.py output.csv "measurements/*.csv"