Added documentation for running McPAT

README.md

@@ -30,6 +30,7 @@
       <ul>
         <li><a href="#launching-experiments">Launching Experiments</a></li>
         <li><a href="#rolling-up-statistics">Rolling up Statistics</a></li>
+        <li><a href="#running-mcpat">Running McPAT</a></li>
       </ul>
     </li>
     <li><a href="#brief-code-walkthrough">Brief Code Walkthrough</a></li>
@@ -172,6 +173,44 @@ Our experimental workflow consists of two stages: (1) launching experiments, and
 
 4. Export the `rollup.csv` file in your favorite data processor (Python Pandas, Excel, Numbers, etc.) to gain insights.
 
+### Running McPAT
+McPAT requires an XML file that contains all the necessary statistics (e.g., #L1D hits, #L2C hits, etc.) to compute the runtime dynamic power consumption of the processor. We have already provided a [template XML file](https://github.com/CMU-SAFARI/Hermes/blob/main/mcpat/hermes_glc_template.xml) that models our GLC core configuration. Note that this file is only a template file, meaning we only use a placeholder name for key statistics (e.g., [total cycles](https://github.com/CMU-SAFARI/Hermes/blob/main/mcpat/hermes_glc_template.xml#L33)). 
+
+To generate power consumption stats using McPAT, we need to follow three key steps: (1) replace appropriate statistics from the `.out` file generated by simulator in the template XML file, (2) run McPAT on the generated XML file, and (3) rollup statistics from McPAT output. To automate this process, we have provided some scripts. Please use the following instructions to run them.
+
+1. Checkout McPAT in `mcpat/` directory and compile.
+
+    ```bash
+    cd $HERMES_HOME/mcpat
+    git clone https://github.com/HewlettPackard/mcpat
+    cd mcpat/
+    git checkout v1.3.0
+    make
+    ```
+2. Now create the jobfile to run the McPAT experiments
+
+    ```bash
+    cd $HERMES/experiments
+    perl $HERMES_HOME/scripts/create_mcpat_jobfile.pl --exe $HERMES_HOME/scripts/run_mcpat.pl --tlist MICRO22_AE.tlist --exp MICRO22_AE.exp --xmltemplate $HERMES_HOME/mcpat/hermes_glc_template.xml --mcpatexe $HERMES_HOME/mcpat/mcpat/mcpat --statsdir $HERMES_HOME/experiments/outputs/ --outdir $HERMES_HOME/experiments/outputs/ --local 1 > mcpat_jobfile.sh
+    ```
+    This will essentially create a set of jobs, where each job runs the script `run_mcpat.pl` on a `.out` file generated by the simulator. The script `run_mcpat.pl` does three things: (1) creates a new XML file by by replacing all placeholder stats in the template XML by real all stats from the `.out` file, (2) saves this new XML file in `outdir`, and (3) runs McPAT executable on the generated XML file.
+
+3. Launch the jobs
+
+    ```bash
+      cd $HERMES_HOME/experiments/outputs/
+      source ../mcpat_jobfile.sh
+      ```
+
+4. Once the runs are complete, you can rollup necessary statistics from the McPAT output files using the following script
+
+    ```bash
+    cd $HERMES_HOME/experiments/outputs/
+    perl ../../scripts/rollup_mcpat.pl --tlist ../MICRO22_AE.tlist --exp ../MICRO22_AE.exp > rollup_mcpat.csv
+    ```
+
+    Be careful: the `rollup_mcpat.pl` script is very hardcoded, meaning, it extracts specific stats (e.g., power consumption by dcache) from the McPAT generated output files by grepping and relying on line numbers of the grepped output. This is not the best way to write code. So, if you want to make this code more flexible, please open a pull request and I will be very happy to merge your contribution.
+
 ## Brief Code Walkthrough
 > Hermes was code-named DDRP (Direct DRAM Prefetch) during development. So any mention of DDRP anywhere in the code inadvertently means Hermes.
 

scripts/create_mcpat_jobfile.pl

@@ -28,24 +28,38 @@
 	   'exclude=s' => \$exclude_list,
 	   'include=s' => \$include_list,
 	   'extra=s' => \$extra,
-) or die "Usage: $0 --exe <executable> --exp <exp file> --tlist <trace list>\n";
+	   'xmltemplate=s' => \$xml_template,
+	   'mcpatexe=s' => \$mcpat_exe,
+	   'statsdir=s' => \$stats_dir,
+	   'outdir=s' => \$out_dir
+) or die "Usage: $0 --exe <executable> 
+			--exp <exp file> 
+			--tlist <trace list> 
+			--xmltemplate <XML template file> 
+			--mcpatexe <McPAT exe path> 
+			--statsdir <dir where the .out files are from the simulator> 
+			--outdir <dir where McPAT outputs will be saved>\n";
 
 die "\$HERMES_HOME env variable is not defined.\nHave you sourced setvars.sh?\n" unless defined $ENV{'HERMES_HOME'};
 
 die "Supply exe\n" unless defined $exe;
 die "Supply tlist\n" unless defined $tlist_file;
 die "Supply exp\n" unless defined $exp_file;
+die "Supply xmltemplate\n" unless defined $xml_template;
+die "Supply mcpatexe\n" unless defined $mcpat_exe;
+die "Supply statsdir\n" unless defined $stats_dir;
+die "Supply outdir\n" unless defined $out_dir;
 
 my $exclude_nodes_list = "";
 $exclude_nodes_list = "kratos[$exclude_list]" if defined $exclude_list;
 my $include_nodes_list = "";
 $include_nodes_list = "kratos[$include_list]" if defined $include_list;
 
-$stats_dir = getcwd;
-$out_dir = $stats_dir;
+# $stats_dir = getcwd;
+# $out_dir = $stats_dir;
 
-my $xml_template = "$HERMES_HOME/mcpat/hermes_glc_template.xml";
-my $mcpat_exe = "${HERMES_HOME}/mcpat/mcpat";
+# my $xml_template = "$HERMES_HOME/mcpat/hermes_glc_template.xml";
+# my $mcpat_exe = "${HERMES_HOME}/mcpat/mcpat";
 
 my @trace_info = Trace::parse($tlist_file);
 my @exp_info = Exp::parse($exp_file);