added sgemm_tcu roofline perf plotting

Author: NikhilRout

AGENTS.md

@@ -61,7 +61,7 @@ Wait until build completes before running anything else in parallel terminals.
     CONFIGS="-DEXT_TCU_ENABLE" ./ci/blackbox.sh --driver=simx --app=sgemm_tcu --threads=8
     ```
 
-- `make tests` and `make -C tests/regression` build test binaries using their default macros. If you intend to run a test with non-default `NUM_THREADS`, data types, or feature flags, rebuild that specific test explicitly before invoking it.
+- `make tests` and `make -C tests/regression` build test binaries using their default macros. If you intend to run a test with non-default thread count, data types, or feature flags use `CONFIGS` + `blackbox.sh`
 
 ## Testing & Debugging
 
@@ -94,12 +94,18 @@ make -C tests/regression/<test-name>
 ./ci/blackbox.sh --driver=rtlsim --app=<test-name> --debug=1 --log=run.log
 ```
 
-When using non-default compile-time macros, split the flow into an explicit rebuild step and a run step:
+When using non-default compile-time macros, pass them directly via `CONFIGS` on the same command:
 
 ```bash
-make -C tests/regression/<test-name> clean
-CONFIGS="-DNUM_THREADS=8 -DITYPE=fp16 -DOTYPE=fp32 -DEXT_TCU_ENABLE" make -C tests/regression/<test-name>
-CONFIGS="-DEXT_TCU_ENABLE" ./ci/blackbox.sh --driver=simx --app=<test-name> --threads=8 --args="..."
+CONFIGS="-DNUM_THREADS=8 -DITYPE=fp16 -DOTYPE=fp32 -DEXT_TCU_ENABLE" \
+./ci/blackbox.sh --driver=simx --app=<test-name> --threads=8 --args="..."
+```
+
+### Roofline Perf Plot
+
+Example to run sgemm_tcu test with perf collection and generate roofline plot (Peak vs Actual FLOPS, Compute vs Memory BW)
+```bash
+/usr/bin/python3 ../perf/roofline.py --app=sgemm_tcu --driver=simx --cores=1 --warps=4 --threads=8 --issue-width=2 --n=32 --perf=1 --by-cycle --output=sgemm_tcu_roofline.png
 ```
 
 For multi-suite coverage, `ci/regression.sh` is the canonical source of tested configurations. Use it to discover supported parameter combinations before inventing ad hoc ones.
@@ -133,8 +139,8 @@ For parameters not exposed as explicit flags, use `CONFIGS` with `-D...` overrid
 
 Example: To enable TCU, select FEDP backend, and set I/O data types:
 ```bash
-make -C tests/regression/sgemm_tcu clean && CONFIGS="-DNUM_THREADS=4 -DITYPE=bf16 -DOTYPE=fp32" make -C tests/regression/sgemm_tcu
-CONFIGS="-DNUM_THREADS=4 -DEXT_TCU_ENABLE -DTCU_TYPE_TFR" ./ci/blackbox.sh --driver=rtlsim --app=sgemm_tcu
+CONFIGS="-DNUM_THREADS=4 -DEXT_TCU_ENABLE -DTCU_TYPE_TFR -DITYPE=bf16 -DOTYPE=fp32" \
+./ci/blackbox.sh --driver=rtlsim --app=sgemm_tcu --threads=4
 ```
 
 ### Editing default config files

docs/install_vortex.md

@@ -9,6 +9,12 @@
    sudo apt-get install build-essential cmake ccache zlib1g-dev libtinfo-dev libncurses-dev uuid-dev libboost-serialization-dev libpng-dev libhwloc-dev
    ```
 
+   (Optional) for roofline/perf plotting:
+
+   ```
+   sudo apt-get install python3-numpy python3-matplotlib
+   ```
+
 2. Download the Vortex codebase:
 
    ```
@@ -42,6 +48,12 @@ Note: depending on the system, some of the toolchain may need to be recompiled f
    sudo yum install libpng-devel boost boost-devel boost-serialization libuuid-devel opencl-headers hwloc hwloc-devel gmp-devel compat-hwloc1
    ```
 
+   (Optional) for roofline/perf plotting:
+
+   ```
+   sudo yum install python3-numpy python3-matplotlib
+   ```
+
 2. Upgrade GCC to 11:
 
    ```

perf/roofline.py

@@ -13,16 +13,16 @@
 # limitations under the License.
 #
 # Vortex SGEMM Roofline Plotter
-# Runs the regression/sgemmx kernel via ci/blackbox.sh and plots the roofline.
+# Runs a SGEMM-style regression kernel via ci/blackbox.sh and plots roofline metrics.
 #
 # Usage (from build dir):
-#   python3 tests/regression/sgemmx/roofline.py [--driver=rtlsim] [--cores=1]
+#   python3 perf/roofline.py [--app=sgemmx] [--driver=rtlsim] [--cores=1]
 #           [--warps=4] [--threads=4] [--n=128]
 #           [--freq=<auto>] [--bw=51.2] [--perf=1]
 #           [--output=roofline.png]
 #
 # Usage (from source tree, targeting a specific build dir):
-#   python3 tests/regression/sgemmx/roofline.py --build-dir=build_test32 ...
+#   python3 perf/roofline.py --build-dir=build_test32 ...
 
 import argparse
 import os
@@ -64,6 +64,9 @@ def parse_args():
     p.add_argument("--driver",    default="rtlsim",
                    choices=["rtlsim", "simx", "opae", "xrt"],
                    help="Vortex driver")
+    p.add_argument("--app",       default="sgemmx",
+                   choices=["sgemmx", "sgemm_tcu"],
+                   help="Regression app to run")
     p.add_argument("--cores",     type=int, default=1,
                    help="Number of cores (NUM_CORES)")
     p.add_argument("--warps",     type=int, default=4,
@@ -74,6 +77,10 @@ def parse_args():
                    help="Issue width (ISSUE_WIDTH)")
     p.add_argument("--n",         type=int, default=32,
                    help="Square matrix dimension N (SGEMM computes N×N × N×N)")
+    p.add_argument("--m",         type=int, default=None,
+                   help="M dimension for non-square SGEMM (default: use --n)")
+    p.add_argument("--k",         type=int, default=None,
+                   help="K dimension for non-square SGEMM (default: use --n)")
     p.add_argument("--freq",      type=float, default=0,
                    help="Pipeline clock frequency in MHz "
                         "(0 = per-cycle mode, implies --by-cycle; "
@@ -129,15 +136,28 @@ def find_blackbox(args):
     return bb, bdir
 
 
-def run_sgemmx_capture(args):
-    """Run sgemmx via blackbox.sh and return captured stdout+stderr."""
+def _matrix_dims(args):
+    m_dim = args.m if args.m is not None else args.n
+    n_dim = args.n
+    k_dim = args.k if args.k is not None else args.n
+    return m_dim, n_dim, k_dim
+
+
+def run_app_capture(args):
+    """Run the selected app via blackbox.sh and return captured stdout+stderr."""
     blackbox, cwd = find_blackbox(args)
 
+    m_dim, n_dim, k_dim = _matrix_dims(args)
+    if args.app == "sgemm_tcu":
+        app_args = f"-m{m_dim} -n{n_dim} -k{k_dim}"
+    else:
+        app_args = f"-n{n_dim}"
+
     cmd = [
         blackbox,
         f"--driver={args.driver}",
-        "--app=sgemmx",
-        f"--args=-n{args.n}",
+        f"--app={args.app}",
+        f"--args={app_args}",
     ]
     if args.perf:
         cmd.append(f"--perf={args.perf}")
@@ -155,6 +175,8 @@ def run_sgemmx_capture(args):
         configs.append(f"-DPLATFORM_MEMORY_NUM_BANKS={args.mem_banks}")
     if args.mem_data_size is not None:
         configs.append(f"-DPLATFORM_MEMORY_DATA_SIZE={args.mem_data_size}")
+    if args.app == "sgemm_tcu":
+        configs.append("-DEXT_TCU_ENABLE")
 
     env = os.environ.copy()
     existing = env.get("CONFIGS", "")
@@ -248,7 +270,7 @@ def parse_perf(output):
 # ────────────────────────────────────────────────────────────────────────────
 
 def compute_metrics(args, perf):
-    n        = args.n
+    m_dim, n_dim, k_dim = _matrix_dims(args)
     freq_hz  = args.freq * 1e6                          # MHz → Hz
     num_hw_threads    = args.cores * args.warps * args.threads
     # Compute throughput threads: one warp issues per cycle per core, executing
@@ -257,14 +279,14 @@ def compute_metrics(args, perf):
     num_compute_threads = args.cores * args.threads
 
     # --- Workload FLOPs ---
-    # SGEMM: C = A × B  → 2·N³ FLOPs (N³ muls + N³ adds, or N³ FMAs)
-    flops = 2.0 * n ** 3
+    # SGEMM: C[M×N] = A[M×K] × B[K×N] → 2·M·N·K FLOPs
+    flops = 2.0 * m_dim * n_dim * k_dim
 
     # --- Arithmetic intensity ---
     # Ideal (Roofline "capacity" model): one-pass, perfect reuse
-    #   load A (N² f32) + load B (N² f32) + store C (N² f32)
-    bytes_ideal = 3 * n * n * 4                         # bytes, float32
-    ai_ideal    = flops / bytes_ideal                   # FLOP/byte  (= N/6)
+    #   load A (M·K f32) + load B (K·N f32) + store C (M·N f32)
+    bytes_ideal = (m_dim * k_dim + k_dim * n_dim + m_dim * n_dim) * 4
+    ai_ideal    = flops / bytes_ideal
 
     # Actual (from profiler cache-line accounting), if available
     if perf.get("actual_bytes") is not None:
@@ -443,9 +465,9 @@ def plot_roofline(args, perf, m, outfile):
     ax.set_xlabel("Arithmetic Intensity  (FLOP / byte)", fontsize=12)
     ax.set_ylabel(y_label, fontsize=12)
     ax.set_title(
-        f"Vortex SGEMM Roofline — "
+        f"Vortex SGEMM Roofline — {args.app} — "
         f"{args.cores}C / {args.warps}W / {args.threads}T, "
-        f"N={args.n}, {args.driver}, {domain_tag}",
+        f"M={_matrix_dims(args)[0]}, N={_matrix_dims(args)[1]}, K={_matrix_dims(args)[2]}, {args.driver}, {domain_tag}",
         fontsize=12, fontweight="bold",
     )
     ax.legend(fontsize=9, loc="upper left")
@@ -513,12 +535,14 @@ def _annotate(ax, ai, gfl, color, label):
 # ────────────────────────────────────────────────────────────────────────────
 
 def print_metrics(args, perf, m):
+    m_dim, n_dim, k_dim = _matrix_dims(args)
     sep = "═" * 56
     print(f"\n{sep}")
     print("  Vortex SGEMM Roofline Metrics")
     print(sep)
+    print(f"  App             : {args.app}")
     print(f"  Config          : {args.cores}C / {args.warps}W / {args.threads}T")
-    print(f"  Matrix size     : {args.n} × {args.n}")
+    print(f"  Matrix size     : M={m_dim}, N={n_dim}, K={k_dim}")
     print(f"  Driver          : {args.driver}")
     if args.by_cycle:
         print(f"  Domain          : per-cycle")
@@ -577,7 +601,7 @@ def main():
         freq = read_platform_clock(bdir)
         args.freq = float(freq) if freq else 1.0
 
-    output = run_sgemmx_capture(args)
+    output = run_app_capture(args)
     perf   = parse_perf(output)
 
     print(f"\nParsed ({perf['cores_seen']} core(s)): "