QFlex’s source code is available on our GitHub repository. We 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.