RootCanal Artifact

This folder contains the artifact submission for RootCanal at CHES 2022.

Organization

Each example folder has the following structure:
- rtl/ folder contains the hardware design files
- synth/ folder contains the post-synthesis gate-level netlist and the gate to RTL mapping files
- sim/ folder contains the software source code, assembly file, binary file, testbench, test vectors, and the log of the program counter for each pipeline stage
- power/ folder has the mean power trace for the experiment
- aca/ folder contains the output result of the non-specific ACA for the experiment
- nga/ folder contains the scripts and outputs of netlist graph analysis

Steps

Step 1: Finding Leaky Time-Gate Tuples

The first step of RootCanal, will find the leaky time-gate tuples. This step includes synthesizing the design to generate the gate-level netlist, running gate-level simulation on the design, and simulating power consumption traces. ACA (https://arxiv.org/abs/2204.11972) is then used to find the leaky time-gate tuples.
This step of RootCanal is not open source.

Steps 2, 3: Finding Leaky Units and Instructions

nga/nga.py finds the leaky units and instructions.

Prerequisites:
To run the RootCanal on your design, the following files are required:

• ACA results
  • For example, look at aca/combinedresults-sum.yaml
• PC log:
  • Log of PC for each pipeline stage. An example is given in sim/pc_log/ folder. The first column is time and second column PC value.
• Disassembly of the software program:
  • By running ./compile.sh <program> in sim/software/, sim/software/binaries/<program>.dump file is generated. This requires the 32bit RISC-V GCC to be installed. To install, follow the steps in https://github.com/riscv-collab/riscv-gnu-toolchain.
• gate-level netlist
  • For example, look at synth/skivav_sky130_50.v
• HDL track file (optional)
  • For example, look at synth/skivav_sky130_50.g (generated by Cadence Genus)

Setup:
To run NGA on your design, first the following scripts should be adjusted according to the design.
- nga/generate_graph.py: In the current form, this code can generate the graph from a gate-level netlist synthesized for SkyWater 130nm standard cell library and is used by nga/nga.py. Set the variable MAIN_MODULE to the name of the top-level module.

• nga/nga.py: set the following variables
  • ACA_RESULTS_FILE: set to the ACA output file
  • PC_LOG_DIR: set to the PC log file
  • ASSEMBLY_FILE: the disassmebly file of the software program
  • FREQ: frequency of gate-level simulation in Hz
  • PC_LOG_TIMESCALE: time unit for PC log file
  • TOPLEVEL: name of the top level module in the netlist
  • NAME: baseline of the output file names
  • NETLIST: set to the gate-level netlist
  • G_FILE: set to the HDL track file
  • MODULE_NAMES: list of all RTL module names
  • MODULE_NAME_PIPE_STAGE_DICT: dictionary showing the pipeline stage for each RTL file
  • WITHIN_PROCESSOR_CORE: list of the RTL files inside the processor core
  • REGISTER_FILE: name of the register file inside the gate-level netlist
  • EXTRA_PROCESSOR_MODULES: list of the mdoules out of the processor core
  • EXTRA_PROCESSOR_UNITS_DICT: dictionary showing the design block for each module out of the processor core

Run:
After setting the variables, on Ubuntu, run the following commands to install the required packages and run NGA:

sudo apt-get install python3 
pip3 install argparse networkx pyyaml tqdm 
python3 nga.py