Skip to content

ics-jku/spinalfuzz

Repository files navigation

About SpinalFuzz

This repository branched from SpinalHDL Repository. Some changes are made in core and sim to add fuzzing to the workflow. Testcases were reduced to SpinalFuzz relevant Benchmarks. SpinalFuzz is only available on Linux systems and require bash to work.

Publication

The initial paper on SpinalFuzz was presented at ETS'22 and can be downloaded here: https://www.ics.jku.at/files/2022ETS_SpinalFuzz.pdf and can be cited as follows:

@inproceedings{RG:2022,
  author =        {Katharina Ruep and Daniel Gro{\ss}e},
  booktitle =     {European Test Symposium},
  pages =         {1--4},
  title =         {{SpinalFuzz}: Coverage-Guided Fuzzing for {SpinalHDL} Designs},
  year =          {2022},
}

Getting Started

To run SpinalFuzz the following is required:

  1. clone this repository

    git clone [email protected]:ics-jku/spinalfuzz.git
  2. get SpinalHDL requirements A detailed description can be found https://spinalhdl.github.io/SpinalDoc-RTD/master/SpinalHDL/Getting%20Started/getting_started.html#requirements-things-to-download-to-get-started .

  3. get Verilator

    sudo apt-get install git make autoconf g++ flex bison  # First time prerequisites
    git clone http://git.veripool.org/git/verilator   # Only first time
    unset VERILATOR_ROOT  # For bash
    cd verilator
    git pull        # Make sure we're up-to-date
    git checkout v4.217
    autoconf        # Create ./configure script
    ./configure
    make -j$(nproc)
    sudo make install
    echo "DONE"

    For more versions and information about Verilator, see https://www.veripool.org/verilator/ and github https://github.com/verilator/verilator .

  4. get AFLplusplus

    sudo apt-get update
    sudo apt-get install -y build-essential python3-dev automake cmake git flex bison libglib2.0-dev libpixman-1-dev python3-setuptools cargo libgtk-3-dev
    sudo apt-get install -y lld-12 llvm-12 llvm-12-dev clang-12
    sudo apt-get install -y gcc-$(gcc --version|head -n1|sed 's/\..*//'|sed 's/.* //')-plugin-dev libstdc++-$(gcc --version|head -n1|sed 's/\..*//'|sed 's/.* //')-dev
    sudo apt-get install -y ninja-build # for QEMU mode
    git clone https://github.com/AFLplusplus/AFLplusplus
    cd AFLplusplus
    make source-only
    sudo make install

    For more versions and information about AFL++, see https://aflplus.plus/ and github https://github.com/AFLplusplus/AFLplusplus .

How to use

  1. start SBT
    sbt
    
  2. enter tester
    project tester
  3. show all possible Testcases/Main Classes [optional]
    show discoveredMainClasses
  4. start with benchmark settings
    runMain mylib.<setting>
    <setting> is composed of:
    • <benchmark>Fuzz: Fuzz run
    • <benchmark>Sim: Random simulation run
    • <benchmark>Verilog: Verilog code generation only

Benchmarks

  • GCD
  • CNN-Buffer (CnnBuffer in SpinalHDL)
  • Alu
  • I2cSlave
  • Apb3Timer
  • SpiXdrMaster
  • Apb3SpiSlave
  • UartCtrl
  • Apb3UartCtrl
  • BmbI2cCtrl

The files of code are placed in spinalfuzz/tester/src/main/scala/spinal/tester/mylib and are named <benchmark>Test.scala. For some benchmarks additional files with name <benchmark>.scala are needed too, especially when the benchmarks are not part of the SpinalHDL library.

About SpinalHDL Links

SpinalHDL License

The SpinalHDL core is using the LGPL3 license while SpinalHDL lib is using the MIT license. That's for the formalities. But there are some practical statements implied by those licenses:

Your freedoms are:

  • You can use SpinalHDL core and lib in your closed/commercial projects.
  • The generated RTL is yours (.vhd/.v files)
  • Your hardware description is yours (.scala files)

Your obligations (and my wish) are:

  • If you modify the SpinalHDL core (the compiler itself), please, share your improvements.

Also, SpinalHDL is provided "as is", without warranty of any kind.