QFlex’s source code is available on our GitHub repositoryWe encourage QFlex users to subscribe to our GitHub repository and use GitHub issues to request enhancements or bug fixes, or ask questions.

Example: Running Matrix Multiplication with QFlex – Emulation


Downloading QFlex and setting up the environment

  • Clone the main QFlex repository along with all the submodules in the $qflex directory. 
$ git clone https://github.com/parsa-epfl/qflex --recurse-submodules
  • Go to qemu directory, use the build_qemu.sh script to install dependencies and build QEMU with the -emulation option (README).
    • Install dependencies using build_qemu.sh -install.
    • Build QEMU for emulation using build_qemu.sh -emulation.
  • Go to images directory, checkout the matmul branch and setup the image (README).   
  • Go to scripts/captain directory ($captain), and setup the config parameters (README).
    • Install dependencies specified in requirements.txt using pip install --user -r requirements.txt.
    • Use your setup specific ABSOLUTE paths in config/system.ini and config/instance.ini.
    • Use qemu_core_count=1 and  memory_size=4096.
    • Use ramp_c1 as the  starting_snapshot parameter in config/instance.ini to use the base Ubuntu image.
    • Use telnet localhost 5551 in another terminal to interact with the base Ubuntu image.
    • Use matmul as the  starting_snapshot parameter in config/instance.ini to run Matrix Multiplication checkpoint.
  • Run the captain script to start the emulation.
    • Create a $qflex/run directory to contain all the files produced during the run and cd $qflex/run.
    • Run captain using $captain/captain $captain/config/system.ini

Example: Running Matrix Multiplication with QFlex – Trace (KeenKraken)


Downloading QFlex and setting up the environment

  • Clone the QFlex repository as above.
  • Go to qemu directory, install required dependencies and build QEMU with the -trace option (README).
    • Build QEMU for trace using build_qemu.sh -trace.
  • Go to flexus directory, install required dependencies and build the KeenKraken simulator (README).
    • Build KeenKraken using cmake -DSIMULATOR=KeenKraken . && make -j.
  • Go to images directory, checkout the matmul branch and setup the image (README).
  • Go to scripts/captain directory ($captain), and setup the config parameters (README).
    • Use simulation_type=trace along with the correct flexus_path and  flexus_trace_path.
    • Use icount=on in config/system.ini.
    • Provide the correct user_postload path. An example file is given at config/user_postload.
  • Run the captain script to start simulation.
    • Create a $qflex/run directory to contain all the files produced during the run and cd $qflex/run.
    • Create an output directory (e.g. qflex/run/output) to store the logs from the simulation.
    • Use echo 1 > $qflex/run/preload_system_width to provide the system width to KeenKraken. (1 is the number of cores in matmul).
    • Run captain using $captain/captain $captain/config/system.ini -o $qflex/run/output.
  • After the simulation, a stats_db.out.gz file is created in the $qflex/run directory with all the statistics of the simulated run.
    • The stat-manager tool should already be compiled along with flexus.
    • Check the statistics by running $qflex/flexus/stat-manager/stat-manager print all.

Example: Running Matrix Multiplication with QFlex – Timing (KnottyKraken) 


Downloading QFlex and setting up the environment 

  • Clone the QFlex repository as above.
  • Go to qemu directory, install required dependencies and build QEMU with the -timing option (README).
    • Build QEMU for timing using build_qemu.sh -timing.
  • Go to flexus directory, install required dependencies and build the KnottyKraken simulator (README).
    • Build KnottyKraken using cmake -DSIMULATOR=KnottyKraken . && make -j.
  • Go to images directory, checkout the matmul branch and setup the image (README).
  • Go to scripts/captain directory ($captain), and setup the config parameters (README).
    • Use simulation_type=timing along with the correct flexus_path and  flexus_timing_path.
    • Use icount=on in config/system.ini.
    • Provide the correct user_postload path. An example file is given at config/user_postload.
    • Update the paths in config/user_postload corresponding to “To be updated” according to your setup.
  • Run the captain script to start simulation.
    • Create a $qflex/run directory to contain all the files produced during the run and cd $qflex/run.
    • Create an output directory (e.g. $qflex/run/output) to store the logs from the simulation.
    • Use echo 1 > $qflex/run/preload_system_width to provide the system width to KnottyKraken. (1 is the number of cores in matmul).
    • Run captain using $captain/captain $captain/config/system.ini -o $qflex/run/output.
  • After the simulation, a stats_db.out.gz file is created in the qflex/run directory with all the statistics of the simulated run.
    • The stat-manager tool should already be compiled along with flexus.
    • Check the statistics by running $qflex/flexus/stat-manager/stat-manager print all.

Example: Running Matrix Multiplication with QFlex KnockoutKraken


KnockoutKraken brings FPGA-accelerated simulation to the QFlex family. We are working towards simulating instrumented code on instrumented hardware at 100 MIPS/core! 

KnockoutKraken is composed of three main components: a modified version of QEMU, an instrumented ARM softcore (ARMFlex), and a driver that handles the communication between QEMU and ARMFlex. The vast majority of developers will work on QEMU and/or ARMFlex. QEMU is written in C and can be developed on most Linux machines. ARMFlex is written in Chisel, and while basic testing can be done in most Linux machines, fully simulating and synthesizing the softcore requires an extensive toolchain.

  • Clone the QFlex repository with the knockoutkraken branch along with all the submodules
$ git clone https://github.com/parsa-epfl/qflex --recurse-submodules -b knockoutkraken
  • Go to the qemu directory and build QEMU with support for FPGA acceleration (README).
  • Go to the image directory and run unpack.sh to unpack the image. You can use your newly built QEMU to try it out (README).
  • Go to the knockoutkraken directory and start simulating the FPGA soft core right away with sbt. Afterwards, you can synthesize and run your image on an Amazon AWS F1 node. (README).