Merge pull request #212 from eki-project/feature/instrumentation_avg

[Instrumentation] Measure avg. performance

Author: fpjentzsch

custom_hls/instrumentation.template.cpp

@@ -60,6 +60,7 @@
  constexpr unsigned  ILEN    = @ILEN@;    // Input words per IFM
  constexpr unsigned  OLEN    = @OLEN@;    // Output words per OFM
  constexpr unsigned  KO      = @KO@;      // Subwords within OFM transaction word
+ constexpr unsigned  AVG_N   = @AVG_N@;   // Max frames in averaging window
  using  TI = @TI@;  // IFM transaction word
  using  TO = @TO@;  // OFM transaction word
 
@@ -133,6 +134,7 @@
      unsigned  ILEN,
      unsigned  OLEN,
      unsigned  KO,
+     unsigned  AVG_N,
      typename  TI,
      typename  TO
  >
@@ -141,11 +143,14 @@
      hls::stream<TO> &finnox,
      ap_uint<32>  cfg,   	// [0] - 0:hold, 1:lfsr; [31:1] - minimum interval (cycles) between IFM starts
      ap_uint<32>  seed,  	// [31:16] - LFSR seed (only upper 16 bits used)
+     ap_uint<32>  avg_n, 	// [31:0] - averaging window size (1..AVG_N frames)
      ap_uint<32> &status,	// [0] - timestamp overflow; [1] - timestamp underflow
      ap_uint<32> &latency,
      ap_uint<32> &interval,
      ap_uint<32> &checksum,
-     ap_uint<32> &min_latency
+     ap_uint<32> &min_latency,
+     ap_uint<32> &avg_latency,
+     ap_uint<32> &avg_interval
  ) {
  #pragma HLS pipeline II=1 style=flp
 
@@ -219,6 +224,26 @@
  #pragma HLS reset variable=last_interval
  #pragma HLS reset variable=cur_min_latency
 
+     // Sliding-Window Averaging State
+     static ap_uint<clog2nz(AVG_N)>    avg_head = 0;  // write pointer in circular buffer
+     static ap_uint<clog2nz(AVG_N+1)>  avg_fill = 0;  // number of valid entries (0..AVG_N)
+     static clock_t  lat_buf[AVG_N];
+     static clock_t  int_buf[AVG_N];
+     static ap_uint<64>  lat_sum = 0;
+     static ap_uint<64>  int_sum = 0;
+     static clock_t  last_avg_latency  = 0;
+     static clock_t  last_avg_interval = 0;
+     static ap_uint<32>  prev_avg_n = 0;
+ #pragma HLS reset variable=avg_head
+ #pragma HLS reset variable=avg_fill
+ #pragma HLS reset variable=lat_buf off
+ #pragma HLS reset variable=int_buf off
+ #pragma HLS reset variable=lat_sum
+ #pragma HLS reset variable=int_sum
+ #pragma HLS reset variable=last_avg_latency
+ #pragma HLS reset variable=last_avg_interval
+ #pragma HLS reset variable=prev_avg_n
+
      static ap_uint<8>  pkts = 0;
  #pragma HLS reset variable=pkts
      static ap_uint< 2>  coeff[3];
@@ -264,6 +289,33 @@
                  last_interval = cnt_clk - ts1;	// completion - previous completion
                  cur_min_latency = std::min(cur_min_latency, last_latency);
                  ts1 = cnt_clk;	// mark completion ^
+
+                 // Sliding-window average update
+                 // TODO: II=1 but depth is ~70 cycles, can we optimize this?
+                 ap_uint<32>  win = (avg_n == 0 || avg_n > AVG_N) ? ap_uint<32>(AVG_N) : avg_n;
+                 if(prev_avg_n != win) {
+                     avg_head = 0;
+                     avg_fill = 0;
+                     lat_sum  = 0;
+                     int_sum  = 0;
+                     prev_avg_n = win;
+                 }
+                 clock_t  old_lat = lat_buf[avg_head];
+                 clock_t  old_int = int_buf[avg_head];
+                 lat_buf[avg_head] = last_latency;
+                 int_buf[avg_head] = last_interval;
+                 if(avg_fill < win) {
+                     lat_sum += last_latency;
+                     int_sum += last_interval;
+                     avg_fill++;
+                 } else {
+                     lat_sum = lat_sum + last_latency - old_lat;
+                     int_sum = int_sum + last_interval - old_int;
+                 }
+                 avg_head++;
+                 if(avg_head >= ap_uint<clog2nz(AVG_N)+1>(win))  avg_head = 0;
+                 last_avg_latency  = lat_sum / avg_fill;
+                 last_avg_interval = int_sum / avg_fill;
              }
              ocnt = 0;
 
@@ -279,7 +331,9 @@
      latency  = last_latency;
      interval = last_interval;
      checksum = last_checksum;
-     min_latency = cur_min_latency;
+     min_latency  = cur_min_latency;
+     avg_latency  = last_avg_latency;
+     avg_interval = last_avg_interval;
 
  } // instrument()
 
@@ -288,21 +342,27 @@
      hls::stream<TO> &finnox,
      ap_uint<32>  cfg,
      ap_uint<32>  seed,
+     ap_uint<32>  avg_n,
      ap_uint<32> &status,
      ap_uint<32> &latency,
      ap_uint<32> &interval,
      ap_uint<32> &checksum,
-     ap_uint<32> &min_latency
+     ap_uint<32> &min_latency,
+     ap_uint<32> &avg_latency,
+     ap_uint<32> &avg_interval
  ) {
  #pragma HLS interface axis port=finnix
  #pragma HLS interface axis port=finnox
  #pragma HLS interface s_axilite bundle=ctrl port=cfg
  #pragma HLS interface s_axilite bundle=ctrl port=seed
+ #pragma HLS interface s_axilite bundle=ctrl port=avg_n
  #pragma HLS interface s_axilite bundle=ctrl port=status
  #pragma HLS interface s_axilite bundle=ctrl port=latency
  #pragma HLS interface s_axilite bundle=ctrl port=interval
  #pragma HLS interface s_axilite bundle=ctrl port=checksum
  #pragma HLS interface s_axilite bundle=ctrl port=min_latency
+ #pragma HLS interface s_axilite bundle=ctrl port=avg_latency
+ #pragma HLS interface s_axilite bundle=ctrl port=avg_interval
  #pragma HLS interface ap_ctrl_none port=return
 
  #pragma HLS dataflow disable_start_propagation
@@ -315,7 +375,7 @@
      move(finnox, finnox0);
 
      // Main
-     instrument<PENDING, ILEN, OLEN, KO>(finnix0, finnox0, cfg, seed, status, latency, interval, checksum, min_latency);
+     instrument<PENDING, ILEN, OLEN, KO, AVG_N>(finnix0, finnox0, cfg, seed, avg_n, status, latency, interval, checksum, min_latency, avg_latency, avg_interval);
 
      // FIFO -> AXI-Stream
      move(finnix0, finnix);

src/finn/builder/build_dataflow_config.py

@@ -538,6 +538,10 @@ def _fix_path(p: Path | None) -> Path | None:
     #: If enable_instrumentation is True, one can disable the DMA with this flag
     instrumentation_no_dma: Optional[bool] = False
 
+    #: (Only relevant if enable_instrumentation is True) Size of the averaging window
+    #: (number of frames) used by the instrumentation wrapper for throughput measurement.
+    instrumentation_avg_n: int = 64
+
     #: Whether pdb postmortem debugging will be launched when the build fails.
     enable_build_pdb_debug: bool = False
 

src/finn/builder/build_dataflow_steps.py

@@ -1515,6 +1515,7 @@ def step_synthesize_bitfile(model: ModelWrapper, cfg: DataflowBuildConfig):
                     cfg.enable_hw_debug,
                     cfg.enable_instrumentation,
                     cfg.instrumentation_no_dma,
+                    cfg.instrumentation_avg_n,
                     cfg.live_fifo_sizing,
                     partition_model_dir=partition_model_dir,
                 )

src/finn/templates/python_driver/driver.py

@@ -601,7 +601,7 @@ def reset_accelerator(self):
             offset=self.ip_dict["axi_gpio_0"]["registers"]["GPIO_DATA"]["address_offset"], value=0
         )
 
-    def start_accelerator(self, throttle_interval=0):
+    def start_accelerator(self, throttle_interval=0, avg_window_size=64):
         """
         Start the accelerator. Input is throttled to the specified interval (in cycles)
         by pausing after each FM transmission. A throttle_interval of 0 means no throttling.
@@ -610,6 +610,10 @@ def start_accelerator(self, throttle_interval=0):
         lfsr_seed = (self.seed << 16) & 0xFFFF0000  # upper 16 bits
         self.instrumentation_write("seed", lfsr_seed)
 
+        # Set average measurement window size (in frames),
+        # maximum is configured in build config, default value = 64
+        self.instrumentation_write("avg_n", avg_window_size)
+
         # Start operation
         self.instrumentation_write("cfg", (throttle_interval << 1) | 1)  # bit 0 = start
 
@@ -624,6 +628,8 @@ def observe_instrumentation(self, debug_print=True):
         min_latency = self.instrumentation_read("min_latency")
         latency = self.instrumentation_read("latency")
         interval = self.instrumentation_read("interval")
+        avg_latency = self.instrumentation_read("avg_latency")
+        avg_interval = self.instrumentation_read("avg_interval")
 
         frame = (chksum_reg >> 24) & 0x000000FF
         checksum = chksum_reg & 0x00FFFFFF
@@ -643,9 +649,21 @@ def observe_instrumentation(self, debug_print=True):
             print("Min Latency (cycles): %d" % min_latency)
             print("Latency (cycles): %d" % latency)
             print("Interval (cycles): %d" % interval)
+            print("Average Latency (cycles): %d" % avg_latency)
+            print("Average Interval (cycles): %d" % avg_interval)
             print("----------------------------")
 
-        return (overflow_err, underflow_err, frame, checksum, min_latency, latency, interval)
+        return (
+            overflow_err,
+            underflow_err,
+            frame,
+            checksum,
+            min_latency,
+            latency,
+            interval,
+            avg_latency,
+            avg_interval,
+        )
 
     def experiment_instrumentation(self, *args, **kwargs):
         """Run instrumentation experiment and save report."""
@@ -668,6 +686,8 @@ def experiment_instrumentation(self, *args, **kwargs):
             min_latency,
             latency,
             interval,
+            avg_latency,
+            avg_interval,
         ) = self.observe_instrumentation()
 
         # write report to file
@@ -677,12 +697,20 @@ def experiment_instrumentation(self, *args, **kwargs):
             "min_latency_cycles": min_latency,
             "latency_cycles": latency,
             "interval_cycles": interval,
+            "avg_latency_cycles": avg_latency,
+            "avg_interval_cycles": avg_interval,
             "frequency_mhz": round(self.fclk_mhz_actual),
             "min_latency_ms": round(min_latency * (1 / (self.fclk_mhz_actual * 1e6)) * 1e3, 6),
             "latency_ms": round(latency * (1 / (self.fclk_mhz_actual * 1e6)) * 1e3, 6),
+            "avg_latency_ms": round(avg_latency * (1 / (self.fclk_mhz_actual * 1e6)) * 1e3, 6),
             "throughput_fps": (
                 round(1 / (interval * (1 / (self.fclk_mhz_actual * 1e6)))) if interval != 0 else 0
             ),
+            "avg_throughput_fps": (
+                round(1 / (avg_interval * (1 / (self.fclk_mhz_actual * 1e6))))
+                if avg_interval != 0
+                else 0
+            ),
             "min_pipeline_depth": round(min_latency / interval, 2) if interval != 0 else 0,
             "pipeline_depth": round(latency / interval, 2) if interval != 0 else 0,
         }

src/finn/transformation/fpgadataflow/instrumentation.py

@@ -43,12 +43,14 @@ def __init__(
         self,
         fpga_part,
         clk_period_ns,
+        avg_n=64,
         format="ip",  # "ip" for Vivado (Zynq) or "xo" for Vitis (Alveo/Versal)
     ):
         """Initialize instrumentation IP generation with FPGA part and clock settings."""
         super().__init__()
         self.fpga_part = fpga_part
         self.clk_period_ns = clk_period_ns
+        self.avg_n = avg_n
         self.format = format
 
     def apply(self, model):
@@ -86,6 +88,7 @@ def apply(self, model):
         ) as f:
             instrwrp_cpp = f.read()
         instrwrp_cpp = instrwrp_cpp.replace("@PENDING@", str(pending))
+        instrwrp_cpp = instrwrp_cpp.replace("@AVG_N@", str(self.avg_n))
         instrwrp_cpp = instrwrp_cpp.replace("@ILEN@", str(ilen))
         instrwrp_cpp = instrwrp_cpp.replace("@OLEN@", str(olen))
         instrwrp_cpp = instrwrp_cpp.replace("@TI@", str(ti))

src/finn/transformation/fpgadataflow/make_zynq_proj.py

@@ -625,6 +625,7 @@ def __init__(
         enable_debug=False,
         enable_instrumentation=False,
         instrumentation_no_dma=False,
+        instrumentation_avg_n=64,
         live_fifo_sizing=False,
         partition_model_dir=None,
     ):
@@ -637,6 +638,7 @@ def __init__(
         self.enable_debug = enable_debug
         self.enable_instrumentation = enable_instrumentation
         self.instrumentation_no_dma = instrumentation_no_dma
+        self.instrumentation_avg_n = instrumentation_avg_n
         self.live_fifo_sizing = live_fifo_sizing
         self.partition_model_dir = partition_model_dir
 
@@ -652,14 +654,18 @@ def apply(self, model):
         if self.enable_instrumentation:
             if self.instrumentation_no_dma is True or self.live_fifo_sizing is True:
                 prep_transforms = [
-                    GenerateInstrumentationIP(self.fpga_part, self.period_ns),
+                    GenerateInstrumentationIP(
+                        self.fpga_part, self.period_ns, self.instrumentation_avg_n
+                    ),
                     Floorplan(),
                     CreateDataflowPartition(partition_model_dir=self.partition_model_dir),
                 ]
             else:
                 # DMA & Instrumentation Wrapper Case
                 prep_transforms = [
-                    GenerateInstrumentationIP(self.fpga_part, self.period_ns),
+                    GenerateInstrumentationIP(
+                        self.fpga_part, self.period_ns, self.instrumentation_avg_n
+                    ),
                     InsertIODMA(self.axi_port_width),
                     InsertDWC(),
                     SpecializeLayers(self.fpga_part),