For more theoretical background and a basis for this work take a look at
R. Götz, C. Sendner, N. Ruck, M. Rostami, A. Dmitrienko and A. -R. Sadeghi, "RLFuzz: Accelerating Hardware Fuzzing with Deep Reinforcement Learning," 2025 IEEE International Symposium on Hardware Oriented Security and Trust (HOST), San Jose, CA, USA, 2025, pp. 358-369 doi: 10.1109/HOST64725.2025.11050051
Expected directory structure:
- Dockerfile
- entrypoint.sh
- vcs_setup.sh
- install-conda.sh
- licensing.SCL_2021.12.tgz
- VCS_2021.09-SP1_RHELx86.tgz
- requirements.txt
- setup_chipyard.sh
- code/master_code/
while master_code is this repository
- 'the huzz not sourced' from install_rc.sh:
- Solution: comment out from Dockerfile
- Synopsys VCS simulator.
- Prerequisites for Chipyard SoC generator (v1.7.1) can be found in the step 1.4.1 of the Chipyard document.
- We also recommended installing the following:
- make (v4.3)
- git (recommended v2.9.5)
- jdk
- fd (recommended v7.3.0)
- Anaconda python environment manager
- We also recommended installing the following:
- Python packages:
- jsonlines (recommended v3.1.0)
- tqdm (recommended v4.43.0)
- IBM CPLEX Optimizer Studio
- Clone the repo:
git clonehttps://github.com/seth-lab-tamu/TheHuzz.gitTheHuzzcd TheHuzz; export MY_THEHUZZ_DIR=$PWD
- Update the path of
THEHUZZ_ROOTvariable in thethehuzz_setup.shfile at line 7 with the path of TheHuzz directory.
Benchmarks currently supported: Rocket Core, CVA6, and BOOM processors from the Chipyard SoC framework (v1.7.1).
-
Install Chipyard
cd $MY_THEHUZZ_DIR; source thehuzz_setup.sh; ./setup_scripts/install_chipyard.sh- This step will take about 1 hour and 20GB of memory.
source $MY_THEHUZZ_DIR/benchmarks/chipyard_v1_7_1/env.sh
-
Install Rocket Core (optional, only required if you want to fuzz Rocket Core)
cd $MY_THEHUZZ_DIR; source thehuzz_setup.sh; ./setup_scripts/install_rc.sh- This step will take about 30 min and 1GB of memory.
- Check if the installation completed successfully (optional):
cd $MY_THEHUZZ_DIR; ./setup_scripts/test_rc.sh- Make sure that
TheHuzz/sim/sim_chipyard/vcs_0/rc_trace.logfile is same asTheHuzz/docs/examples/riscv_testcase/rc_trace.log. - Make sure that
TheHuzz/sim/sim_chipyard/vcs_0/simv-chipyard-RocketConfig.vdb/snps/coverage/db/testdata/testdirectory has seven.xmlfiles.
-
Install CVA6 (optional, only required if you want to fuzz CVA6)
cd $MY_THEHUZZ_DIR; source thehuzz_setup.sh; ./setup_scripts/install_cva6.sh- This step will take about 30 min and 1GB of memory.
- Check if the installation completed successfully (optional):
cd $MY_THEHUZZ_DIR; ./setup_scripts/test_cva6.sh- Make sure that
TheHuzz/sim/sim_chipyard/vcs_0/cva6_trace.logfile is same asTheHuzz/docs/examples/riscv_testcase/cva6_trace.log. - Make sure that
TheHuzz/sim/sim_chipyard/vcs_0/simv-chipyard-CVA6Config.vdb/snps/coverage/db/testdata/testdirectory has seven.xmlfiles.
-
Install BOOM (optional, only required if you want to fuzz BOOM)
cd $MY_THEHUZZ_DIR; source thehuzz_setup.sh; ./setup_scripts/install_boom.sh- This step will take about 30 min and 1GB of memory.
- Check if the installation completed successfully (optional):
cd $MY_THEHUZZ_DIR; ./setup_scripts/test_boom.sh- Make sure that
TheHuzz/sim/sim_chipyard/vcs_0/boom_trace.logfile is same asTheHuzz/docs/examples/riscv_testcase/boom_trace.log. - Make sure that
TheHuzz/sim/sim_chipyard/vcs_0/simv-chipyard-SmallBoomConfig.vdb/snps/coverage/db/testdata/testdirectory has seven.xmlfiles.
-
Install RISC-V emulator, spike (optional, only required if you want to do bug detection)
cd $MY_THEHUZZ_DIR; source thehuzz_setup.sh; ./setup_scripts/install_spike.sh- This step will take about 4GB of memory.
- Check if the installation completed successfully (optional):
cd $MY_THEHUZZ_DIR; ./setup_scripts/test_spike.sh- Make sure that
TheHuzz/sim/spike/spike_trace.logfile is same asTheHuzz/docs/examples/riscv_testcase/spike_trace.log.
-
Deleting a benchmark:
- Rocket Core, CVA6, and BOOM are all installed together in the
TheHuzz/benchmarks/chipyard_v1_7_1directory and executables are copied toTheHuzz/sim/sim_chipyarddirectory.- Hence they cannot be individually deleted.
- Deleting
TheHuzz/benchmarks/chipyard_v1_7_1andTheHuzz/sim/sim_chipyardremoves Chipyard along with Rocket Core, CVA6, and BOOM processors.
- Rocket Core, CVA6, and BOOM are all installed together in the
cd $MY_THEHUZZ_DIRsource thehuzz_setup.shcd thehuzzpython3 fuzz.py -co <benchmark> -j <no threads> -mp <max testcases>- Ex:
python3 fuzz.py -co rc -j 10 -mp 30 - Use
python3 fuzz.py --help for details about more arguments - Important arguments:
python3 fuzz.py -co <benchmark> -id <run name> -mp <max testcases> -sj <simulation batch size> -j <num threads to use>
- Ex:
- Outputs:
- All the outputs are recorded in
TheHuzz/outputs/<clone no>_<core_name>_<run name>directory.TheHuzz/outputs/trash_<clone no>_<core_name>_<run name>stores all the unwanted files related to the run. They can be deleted. TheHuzz/outputs/<clone no>_<core_name>_<run name>directory:cov_log.jsonlfile logs the coverage increment of each testcase.fuzz_log.txtlogs the start and end times of mutation, feedback generation, and simulation engines. It also has the summary of results computed at the end of fuzzing.inputs_log.txtrecords the information about generation and mutation of testcases.merged_cov.jsonrecords the final coverage achieved by TheHuzz.all_progsdirectory stores all the testcase files generated and mutated by TheHuzz.sim_outdirectory stores all the hardware simulation trace files and coverage files.
- All the outputs are recorded in
- Bug detection:
- By default, TheHuzz only collects coverage. To enable bug detection also, use
-db 1as the argument.- Ex:
python3 fuzz.py -co rc -j 10 -mp 30 -db 1
- Ex:
- Note: Depending on the ISA of the core being fuzzed, the corresponding emulator, i.e., spike for RISC-V needs to be installed to enable bug detection.
- Instructions to install spike are included above.
- To run only the checking of traces of rtl and emulator on a already completed fuzzer run, set
-mp 0so that no new test cases are run, and-db 1so that bug comparison happens. When tyou are prompted to delete the existing files, pressnand enter.- Ex: If you previously ran fuzzer with the following command:
python3 fuzz.py -co rc -rm thehuzz -id mytest -j 10 -mp 30 -db 1, now to reun fuzzer but only do mismatch comparison of the traces, dopython3 fuzz.py -co rc -rm thehuzz -id mytest -j 10 -mp 0 -db 1. Then selectnand press enter when prompted about deleting existing files.
- Ex: If you previously ran fuzzer with the following command:
- By default, TheHuzz only collects coverage. To enable bug detection also, use
- Profiling a new benchmark:
- To run the profiler and get the optimizer solution for a benchmark, do the following:
- Create a conda environment (you can run the setup directly without conda environment, but we recommend using it because using the rest if environment will not be disturbed if conda env is used)
conda create -n py3_cplex python=3.6source activate py3_cplex
- Install the optimizer packages (run the following if you are in the conda environment, else, install it with python package manager)
conda install -c ibmdecisionoptimization docplex
- Add your IBM Cplex implementation to the python path if it is not already there
- For example:
export PYTHONPATH=$PYTHONPATH:/opt/coe/ibm/cplex_studio129/cplex/python/3.6/x86-64_linux
- For example:
cd $MY_THEHUZZ_DIRsource thehuzz_setup.shcd thehuzzpython3 do_profile.py -rm prof -co rc -j 10 -sfc 1- This will generate the optimizer solution file,
thehuzz/cplex_cov_solution.json. Theget_solfunction fromthehuzz/fuzz.pyparses this solution file to extract the optimal instruction mutation pairs.
- This will generate the optimizer solution file,
- Create a conda environment (you can run the setup directly without conda environment, but we recommend using it because using the rest if environment will not be disturbed if conda env is used)
- To run the profiler and get the optimizer solution for a benchmark, do the following:
- Custom seed inputs:
- TheHuzz does not need any seed inputs from the user as it generates its own seed inputs. But, TheHuzz does accept custom seed inputs placed in the
input_seedsdirectory. The files should be in the .hex format used by TheHuzz.
- TheHuzz does not need any seed inputs from the user as it generates its own seed inputs. But, TheHuzz does accept custom seed inputs placed in the
- Starting coverage data:
- By default, TheHuzz starts with zero coverage. To use a custom starting coverage data, use
-stc continueand-icf <json coverage dict file>to start TheHuzz with custom coverage. The json coveerage dict file should be in the same format as theoutputs/<outputs run dir>/merged_cov.jsonfile.
- By default, TheHuzz starts with zero coverage. To use a custom starting coverage data, use
- Running random regression:
- TheHuzz can be run in random regression mode where fuzzing components such as mutation and coverage feedback will be disabled. All the input testcases are randomly generated to verify the benchmarks and the coverage is reported.
- To run TheHuzz in random regression mode, add the argument
-rm randomto the command- Ex:
python3 fuzz.py -co rc -j 10 -mp 30 -rm random
- Ex:
The work presented in this repository is part of the CROSSCON project that received funding from the European Union’s Horizon Europe research and innovation programme under grant agreement No 101070537.
