RTLFuzzLab is designed to allow for easy experimentation with Coverage Directed Mutational Fuzz Testing on RTL designs.

For details about RTLFuzzLab, please see our abstract released in WOSET 2021.

Abstract

Fajardo, Brandon and Laeufer, Kevin and Bachrach, Jonathan and Sen, Koushik. RTLFuzzLab: Building A Modular Open-Source Hardware Fuzzing Framework. In Workshop on Open-Source EDA Technology (WOSET), 2021.

BibTeX citation:

@inproceedings{fajardo2021rtlfuzzlab,
  title={{RTLFuzzLab: Building A Modular Open-Source Hardware Fuzzing Framework}},
  author={Fajardo, Brandon and Laeufer, Kevin and Bachrach, Jonathan and Sen, Koushik},
  booktitle={Workshop on Open-Source EDA Technology (WOSET)},
  year={2021}
}

The following dependencies are required to run this software:

• make
• gcc
• g++
• java
• sbt
• verilator
• matplotlib
• scipy

git clone https://github.com/ekiwi/AFL AFL_rtl_fuzz_lab
cd AFL_rtl_fuzz_lab
make

This AFL fork is functionally identical to upstream AFL. Our version produces some additional meta-data that is used to produce better plots.

git clone https://github.com/ekiwi/rtl-fuzz-lab

./setup.sh

This will create two fifos (a2j and j2a), a seeds directory, and compile the proxy to interface with AFL.

Script takes in two sets of arguments, separated by '---'.

1. First set is arguments to the Python script, fuzz.py.

Execute "fuzz.py -h ---" for argument options to the Python script

Existing seeds for --seed argument are available in: rtl-fuzz-lab/src/fuzzing/template_seeds/binary

2. Second set is arguments passed to the Scala script, AFLDriver. The following are options to pass in:

--FIRRTL <path>: FIRRTL design which is to be fuzzed. Existing designs under: test/resources/fuzzing

--Harness <rfuzz/tlul>: Handles converting input bytes to hardware inputs. Current options: rfuzz, tlul (bus-centric)

--Directed: Flag for ignoring coverage in bus-monitors

--VCD: Flag for generating a VCD (value change dump)

--Feedback <number>: Maximum number of times a coverage point can trigger per input

--MuxToggleCoverage <boolean>: Options: false (Mux Toggle Coverage), true (Full Mux Toggle Coverage)

Example:

python3 fuzz.py --time 3 --folder ./example --iterations 1 --afl-path ~/AFL_rtl_fuzz_lab --seed TLI2C_longSeed.hwf --- --FIRRTL test/resources/fuzzing/TLI2C.fir --Harness tlul --Directed --MuxToggleCoverage false --Feedback 255

Script takes in set of arguments equivalent to second set of arguments to fuzz.py described above.

In addition, script takes in --Folder argument to specify location of folder to analyze.

Example:

python3 coverageAnalysis.py --FIRRTL test/resources/fuzzing/TLI2C.fir --Harness tlul --Directed --MuxToggleCoverage false --Feedback 255 --Folder example/0.out

Takes in arguments: do_average PATH [PATH ...]

See plotCoverage.py -h for argument options

Outputs png of generated plot as rtl-fuzz-lab/coveragePlot.png

Example:

python3 plotCoverage.py true example

Integrating AFL with our Scala based fuzz bench would not have been possible without the awesome AFL proxy infrastructure from the JQF project.

This code is open-source under a BSD license. See the LICENSE file for more information.