improved report configs explanations

e2e/configs-design/gcd/power-rtl-sky130.yml

@@ -5,21 +5,26 @@ vlsi.core.power_tool: "hammer.power.joules"
 power.inputs:
   level: "rtl"
   input_files: ["src/gcd.v"]
-  waveforms: ["build-sky130-cm/gcd/sim-rtl-rundir/output.fsdb"]
+  waveforms: [] #"build-sky130-cm/gcd/sim-rtl-rundir/output.fsdb"]
   report_configs:
     - waveform_path: "build-sky130-cm/gcd/sim-rtl-rundir/output.fsdb"
-      inst: gcd/GCDctrl0
-      levels: 2
-      toggle_signal: clk
+      inst: /gcd/GCDctrl0
+      toggle_signal: /gcd/clk
       num_toggles: 1
       report_name: inst-GCDctrl0
       output_formats:
       - all
     - waveform_path: "build-sky130-cm/gcd/sim-rtl-rundir/output.fsdb"
       module: gcd_control
-      levels: 2
-      toggle_signal: clk
+      toggle_signal: /gcd/clk
       num_toggles: 1
       report_name: module-gcd_control
       output_formats:
       - all
+    - waveform_path: "build-sky130-cm/gcd/sim-rtl-rundir/output.fsdb"
+      levels: 1
+      toggle_signal: /gcd/clk
+      num_toggles: 1
+      report_name: levels-1
+      output_formats:
+      - all

e2e/configs-design/pass/power-rtl-sky130.yml

@@ -13,4 +13,7 @@ power.inputs:
       toggle_signal: clock
       num_toggles: 1
       output_formats:
-      - all
+      - report
+      - activity
+      - ppa
+      - plot_profile

hammer/config/defaults.yml

@@ -844,28 +844,33 @@ power.inputs:
 
   report_configs: [] # Optional: Power report configs that are run in addition to the average power reports in power.inputs.waveforms
   # type: List[PowerReport]
-  # PowerReport struct members:
-  # waveform_path (str) - Path to the waveform for the report
-  # inst (str) - Optional. Hierarchical or leaf instance to report power for
-  # module (str) - Optional. The module to report power for (default here is the Chipyard top level). All instances of this module are used for the power report.
-  # levels (int) - Optional. The number of levels in the design hierachy to report
-  # start_time (TimeValue) - Optional. The start time of the power report in the waveform
-  # end_time (TimeValue) - Optional. The end time of the power report in the waveform
-  # interval_size (TimeValue) - Optional. Divide the stimulus into frames of this size
-  # toggle_signal (str) - Optional. Path to the signal to generate report windows based on toggles
-  # num_toggles (int) - Optional (must be specified if toggle_signal is specified). The number of toggles of the toggle_signal for each frame to report power
-  # frame_count (int) - Optional. The number of frames to report the power for. Default: 1
-  # report_name (str) - Optional. Name of the power report, but MUST NOT contain file extension.
-  #     If an absolute path is provided, this is used as the path (plus file extension).
-  #     If a relative path or just the filename is provided, output file will be saved to <power-rundir>/<output_format-type>/<report_name>.<ext>
+  ## PowerReport struct members:
+  #   waveform_path (str) - Path to the waveform for the report
+  #   start_time (TimeValue) - Optional. The start time of the power report in the waveform
+  #   end_time (TimeValue) - Optional. The end time of the power report in the waveform
+  ### Frame-based analysis: interval_size and toggle_signal+num_toggles are exclusive (interval_size takes precedence)
+  #   interval_size (TimeValue) - Optional. Divide the stimulus into frames of this size.
+  #   toggle_signal (str) - Optional. Path to the signal to generate report windows based on toggles
+  #   num_toggles (int) - Optional (must be specified if toggle_signal is specified). The number of toggles of the toggle_signal for each frame to report power
+  #   frame_count (int) - Optional. The number of frames to report the power for. Default: 1
+  #     Must be combined with interval_size or toggle_signal/num_toggles
+  ### Instance/Module Power Reporting: inst and module are exclusive (inst takes precedence)
+  #   inst (str) - Optional. Hierarchical or leaf instance to report power for. Takes precedence over module option.
+  #   module (str) - Optional. The module to report power for (default here is the Chipyard top level). All instances of this module are used for the power report.
+  #   levels (int) - Optional. The number of levels in the design hierachy to report. Default: unspecified (tool command default used)
+  #     If inst/module are specified, all children hierarchical instances upto the specified level are reported
+  ### Report Details:
+  #   report_name (str) - Optional. Name of the power report, but MUST NOT contain file extension.
+  #     If an absolute path is provided, this is used as the path
+  #     If a relative path or just the filename is provided, output file will be saved to <power-rundir>/reports/
   #     Default: waveform file name
-  # output_formats (List[str]) - Optional. Report types to generate. Default: ["report"]
-  #   Valid options are:
-  #     "report" - average power report (*.rpt), default
-  #     "plot_profile" - power profile over time, requires frame-based analysis (*.png, *.png.data)
-  #     "write_profile" - profiles all power types on all categories for all the sub-hierarchies for a given design instance (*.fsdb)
-  #     "profile" - run plot_profile + dump_profile
-  #     "all" - generate all of the above report formats
+  #   output_formats (List[str]) - Optional. Report types to generate. Default: ["report"]
+  #     Valid options are:
+  #       "report" - average power report (*.rpt), default
+  #       "plot_profile" - power profile over time, requires frame-based analysis (*.png, *.png.data)
+  #       "write_profile" - profiles all power types on all categories for all the sub-hierarchies for a given design instance (*.fsdb)
+  #       "profile" - run plot_profile + dump_profile
+  #       "all" - generate all of the above report formats
 
   # examples:
   #   report_configs: [{waveform_path: "/path/to/fsdb", module: "chiptop", levels:3, start_time: "0ns", end_time: "1ns", toggle_signal:"/ChipTop/clock", num_toggles:1, frame_count:1000, report_name: "my_fsdb_report"}]

hammer/power/joules/__init__.py

@@ -291,12 +291,16 @@ def report_power(self) -> bool:
 
             stim_alias, new_stim = self.get_alias_name(read_stim_cmd)
 
-            if new_stim:
-                block_append(f"{read_stim_cmd} -alias {stim_alias} -append")
-                # block_append(f"write_sdb -out {alias}.sdb") # NOTE: subsequent read_sdb command errors when reading this file back in, so don't cache for now
-                # TODO: avg mode saves time, run this based on output_formats mode?
-                # block_append(f"compute_power -mode average -stim {stim_alias} -append")
-                block_append(f"compute_power -mode time_based -stim {stim_alias} -append")
+            # if new_stim:
+            # NOTE: only reading new stimuli with -append mode breaks frame-based power analysis 
+            #   with error message: "Invalid frame name /stim#2/frame#3. No stimulus read. Using vectorless power computation"
+            #   Interestingly, this does not happen when starting from a database checkpoint (i.e. after read_db pre_report_power)
+            #   For now, re-run read_stimulus for each power report config, even if it's an identical stimulus
+            block_append(f"{read_stim_cmd} -alias {stim_alias}")
+            # block_append(f"write_sdb -out {alias}.sdb") # NOTE: subsequent read_sdb command errors when reading this file back in, so don't cache for now
+            # TODO: avg mode saves time, run this based on output_formats mode?
+            # block_append(f"compute_power -mode average -stim {stim_alias} -append")
+            block_append(f"compute_power -mode time_based -stim {stim_alias} -append")
 
             # remove only file extension (last .*) in filename
             waveform_name = '.'.join(os.path.basename(report.waveform_path).split('.')[0:-1])
@@ -320,20 +324,14 @@ def report_power(self) -> bool:
             # use set intersection to determine whether two lists have at least one element in common
             if {'report','all'} & output_formats:
                 # -frames $frames explodes the runtime & doesn't seem to change result
-                # NOTE: module_str causes it to error
-                if not report.levels: levels_str = "-levels all"
-                self.block_append(f"report_power -stims {stim_alias} {inst_str} {module_str} {m_levels_str} -unit mW -out {report_path}.power.rpt")
+                self.block_append(f"report_power -stims {stim_alias} {inst_str} {module_str} {levels_str} -unit mW -out {report_path}.power.rpt")
                 self.block_append(f"report_power -stims {stim_alias} -by_hierarchy {levels_str} -unit mW -out {report_path}.hier.power.rpt")
             if {'activity','all'} & output_formats:
-                if not report.levels: levels_str = "-levels 0"
-                self.block_append(f"report_activity -stims {stim_alias} {inst_str} {module_str} {m_levels_str} -out {report_path}.activity.rpt")
+                self.block_append(f"report_activity -stims {stim_alias} {inst_str} {module_str} {levels_str} -out {report_path}.activity.rpt")
                 self.block_append(f"report_activity -stims {stim_alias} -by_hierarchy {levels_str} -out {report_path}.hier.activity.rpt")
             if {'ppa','all'} & output_formats:
                 root_str = inst_str.replace('-inst','-root')
-                # TODO: this command causes internal error (but not when just running report_power step) 
-                # self.append(f"report_ppa {root_str} {module_str} -out {report_path}.ppa.rpt")
-            # TODO: any frame-based analysis gives this error message: "Invalid frame name /stim#2/frame#3. No stimulus read. Using vectorless power computation"
-            #   however, this does not happen when just running report_power step, similar to the report_ppa issue
+                self.block_append(f"report_ppa {root_str} {module_str} -out {report_path}.ppa.rpt")
             if {'plot_profile','profile','all'} & output_formats:
                 if not frame_based_analysis:
                     self.logger.error("Must specify either interval_size or toggle_signal+num_toggles in power.inputs.report_configs to generate plot_profile report (frame-based analysis).")
@@ -344,7 +342,7 @@ def report_power(self) -> bool:
                 if not frame_based_analysis:
                     self.logger.error("Must specify either interval_size or toggle_signal+num_toggles in power.inputs.report_configs to generate write_profile report (frame-based analysis).")
                     return False
-                block_append(f"write_power_profile -stims {stim_alias} -root [get_insts -rtl_type hier] {levels_str} -unit mW -format fsdb -out {report_path}.profile")
+                block_append(f"write_power_profile -stims {stim_alias} -root [get_insts -rtl_type hier] {levels_str} -unit mW -format fsdb -out {report_path}.profile.fsdb")
 
         saifs = self.get_setting("power.inputs.saifs")
         for saif in saifs: