perf: add reusable perf_counters.h instrumentation system

JoeMatt · claude · JoeMatt · commit 28b56ce7441c · 2026-05-01T23:12:07.000-04:00
Generalizes the ad-hoc BLITTER_PROFILE pattern into a reusable,
zero-overhead-when-off counter system any subsystem can use.

* src/core/perf_counters.{h,c} - PERF_COUNTER / PERF_INC / PERF_ADD
  macros backed by a constructor-registered linked list.  When
  BENCH_PROFILE is undefined every macro expands to (0) so there is
  no runtime, code-size, or symbol cost in shipped builds.

* src/tom/blitter.c - migrate the existing BLITTER_PROFILE counters
  in BlitterMidsummer2 onto the new system.  Counters are embedded in
  existing initializers via the comma operator so the file stays
  C89-clean (no statements before declarations).

* Makefile - `make BENCH_PROFILE=1` defines the macro globally.
  `make benchmark BENCH_PROFILE=1` re-invokes with TEST_EXPORTS=1 so
  test_benchmark can dlsym `perf_counters_dump` and print all
  registered counters next to the FPS report.

* test/tools/test_benchmark.c - dlsym the optional dump symbol; if
  present (BENCH_PROFILE build), call it before the BENCHMARK RESULTS
  block.  No effect on default builds.

* exports-test.list / link-test.T - add perf_counters_{dump,reset,
  register} so harnesses can reach them under TEST_EXPORTS=1.

* scripts/profile-mac.sh - one-line wrapper around `xctrace record`.
  Defaults to Time Profiler; --template "CPU Counters" for PMU
  events on Apple Silicon.  Builds the core + harness, runs the
  benchmark under instrumentation, writes a .trace bundle, and can
  auto-open it with --open.

* docs/profiling.md - new sections covering BENCH_PROFILE counters
  (when to use vs sampling profilers) and the profile-mac.sh wrapper.

Validated end-to-end with `make benchmark BENCH_PROFILE=1
BENCH_BLITTER=accurate`: counters populate
(blitter_inner=283994 over 120 frames of yarc), and default builds
remain unchanged.

Co-Authored-By: Claude Opus 4.7 &lt;noreply@anthropic.com&gt;
diff --git a/Makefile b/Makefile
@@ -53,6 +53,13 @@ ifeq ($(DEBUG),1)
    CFLAGS += -DBUILD_TIMESTAMP="\"debug $(shell date -u +%Y-%m-%dT%H:%M:%SZ)\""
 endif
 
+# Opt-in instrumentation counters (src/core/perf_counters.h).
+# `make BENCH_PROFILE=1` defines the macro so PERF_COUNTER/PERF_INC
+# emit real code; otherwise every counter macro is a no-op.
+ifeq ($(BENCH_PROFILE),1)
+   CFLAGS += -DBENCH_PROFILE
+endif
+
 # Symbol export gating.
 #
 #   GNU ld (Linux, Windows MSYS2, ARM, ...) honours --version-script:
@@ -869,12 +876,19 @@ BENCH_ROM     ?= test/roms/yarc.j64
 BENCH_FRAMES  ?= 600
 BENCH_WARMUP  ?= 60
 BENCH_BLITTER ?= fast
-benchmark: $(TARGET)
-	@# Build the harness inline so this works whether or not TEST_EXPORTS=1
-	@# was used for $(TARGET); the harness only uses retro_* exports.
-	@# -ldl is Linux-specific; macOS/BSD provide dl* in libSystem/libc
-	@# (and Apple's clang silently accepts -ldl as a no-op, but other
-	@# linkers may not).
+# BENCH_PROFILE=1 enables src/core/perf_counters.h instrumentation and
+# wide-export ABI so test_benchmark can dlsym `perf_counters_dump`.
+ifeq ($(BENCH_PROFILE),1)
+BENCH_TEST_EXPORTS := TEST_EXPORTS=1
+else
+BENCH_TEST_EXPORTS :=
+endif
+benchmark:
+	@# Re-invoke make so BENCH_PROFILE / TEST_EXPORTS take effect on the .so/.dylib.
+	$(MAKE) $(BENCH_TEST_EXPORTS) BENCH_PROFILE=$(BENCH_PROFILE) -j$(shell getconf _NPROCESSORS_ONLN 2>/dev/null || echo 4)
+	@# Build the harness inline; it dlopens the core, so it only needs the retro_* ABI
+	@# (plus the optional perf_counters_dump symbol when BENCH_PROFILE=1).
+	@# -ldl is Linux-specific; macOS/BSD provide dl* in libSystem/libc.
 	$(CC) -O2 -Wall -std=c99 $(INCFLAGS) \
 		-o test/tools/test_benchmark test/tools/test_benchmark.c \
 		$(if $(filter Linux,$(shell uname -s)),-ldl)
diff --git a/Makefile.common b/Makefile.common
@@ -33,6 +33,7 @@ SOURCES_C :=  \
 	$(CORE_DIR)/src/cd/cdrom.c \
 	$(CORE_DIR)/src/core/cheat.c \
 	$(CORE_DIR)/src/core/crc32.c \
+	$(CORE_DIR)/src/core/perf_counters.c \
 	$(CORE_DIR)/src/core/event.c \
 	$(CORE_DIR)/src/jerry/eeprom.c \
 	$(CORE_DIR)/src/core/filedb.c \
diff --git a/docs/profiling.md b/docs/profiling.md
@@ -23,11 +23,21 @@ Reports `Frames/sec`, `Time/frame`, total wall time.  Boots the core via `dlopen
 
 **Instruments (Time Profiler)** is the easiest way to get a flame graph on macOS.
 
+The wrapper at `scripts/profile-mac.sh` builds the core, runs the benchmark
+under `xctrace`, and writes a `.trace` bundle you can open in Instruments:
+
+```bash
+scripts/profile-mac.sh                                    # default: Time Profiler, accurate blitter
+scripts/profile-mac.sh --template "CPU Counters"          # PMU: cycles, instructions, branch misses
+scripts/profile-mac.sh --rom test/roms/yarc.j64 --open    # auto-open the trace
+```
+
+Manual invocation if you'd rather attach to a running process:
+
 ```bash
 make benchmark BENCH_FRAMES=6000 BENCH_WARMUP=120 &
 BENCH_PID=$!
 
-# Sample for 30 seconds, output to .trace bundle
 xcrun xctrace record --template "Time Profiler" --attach $BENCH_PID --output bench.trace --time-limit 30s
 open bench.trace
 ```
@@ -41,6 +51,57 @@ sample $BENCH_PID 5 -file /tmp/sample.txt
 # 5-second sample.  Read /tmp/sample.txt for collapsed call stacks.
 ```
 
+## Bespoke counters — `BENCH_PROFILE=1`
+
+Sampling profilers tell you *where* time goes; counters tell you *how often*
+something happens.  When you want exact iteration counts (e.g., "did my
+fast-path actually skip the inner loop?"), use the `perf_counters` system in
+`src/core/perf_counters.h`.
+
+```bash
+make benchmark BENCH_PROFILE=1 BENCH_BLITTER=accurate BENCH_FRAMES=300
+# ...
+# [perf] counter dump:
+# [perf]   blitter_phrase_writes                    3034993
+# [perf]   blitter_phrase_reads                     931821
+# [perf]   blitter_inner_io                         3966814
+# [perf]   blitter_inner                            4131151
+# [perf]   blitter_outer                            337722
+# [perf]   blitter_calls                            131628
+```
+
+The macros are zero-overhead when `BENCH_PROFILE` is undefined (default
+build) — every `PERF_INC` becomes `((void)0)`, every `PERF_COUNTER`
+becomes a typedef.  Use them freely in hot paths to instrument
+hypotheses.
+
+Adding a counter:
+
+```c
+#include "perf_counters.h"
+
+PERF_COUNTER(my_event);             /* file scope */
+
+void hot(void) {
+    PERF_INC(my_event);             /* in-loop */
+    PERF_ADD(my_event, n);          /* batch */
+}
+```
+
+The harness (`test/tools/test_benchmark.c`) calls
+`perf_counters_dump(stderr)` at exit; counter values appear right
+before the `BENCHMARK RESULTS` block.
+
+When to reach for this vs. Time Profiler:
+
+| Question | Tool |
+|---|---|
+| "Where are we spending cycles?" | `xctrace` Time Profiler |
+| "How many times does the inner loop run per frame?" | `BENCH_PROFILE=1` |
+| "What fraction of inner iterations are no-ops?" | `BENCH_PROFILE=1` |
+| "Are we hitting L1 / branch-mispredicting?" | `xctrace` CPU Counters |
+| "Did this optimization change behavior, not just timing?" | `BENCH_PROFILE=1` (deltas in counts) |
+
 ## Linux — `perf` + flamegraph
 
 ```bash
diff --git a/exports-test.list b/exports-test.list
@@ -33,3 +33,6 @@ _sclk
 _smode
 _lowerField
 _vjs
+_perf_counters_dump
+_perf_counters_reset
+_perf_counters_register
diff --git a/link-test.T b/link-test.T
@@ -36,5 +36,8 @@
       smode;
       lowerField;
       vjs;
+      perf_counters_dump;
+      perf_counters_reset;
+      perf_counters_register;
    local: *;
 };
diff --git a/scripts/profile-mac.sh b/scripts/profile-mac.sh
@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+#
+# profile-mac.sh -- Run test_benchmark under Xcode Instruments on Apple Silicon
+# (or any Mac with Xcode CLT).
+#
+# Usage:
+#   scripts/profile-mac.sh [--template NAME] [--frames N] [--warmup N]
+#                          [--blitter fast|accurate] [--rom PATH] [--open]
+#
+# Defaults:
+#   template = "Time Profiler"
+#   frames   = 600  warmup = 60  blitter = accurate
+#   rom      = test/roms/yarc.j64
+#   --open   = open the .trace bundle in Instruments when finished
+#
+# Common templates:
+#   "Time Profiler"   -- where time is being spent (call tree / flame)
+#   "CPU Counters"    -- Apple Silicon PMU (cycles, instr, branches, misses)
+#   "System Trace"    -- syscalls, scheduler, VM events
+#
+set -euo pipefail
+
+TEMPLATE="Time Profiler"
+FRAMES=600
+WARMUP=60
+BLITTER=accurate
+ROM="test/roms/yarc.j64"
+OPEN_TRACE=0
+
+while [ $# -gt 0 ]; do
+   case "$1" in
+      --template) TEMPLATE="$2"; shift 2 ;;
+      --frames)   FRAMES="$2"; shift 2 ;;
+      --warmup)   WARMUP="$2"; shift 2 ;;
+      --blitter)  BLITTER="$2"; shift 2 ;;
+      --rom)      ROM="$2"; shift 2 ;;
+      --open)     OPEN_TRACE=1; shift ;;
+      -h|--help)
+         sed -n '2,20p' "$0"
+         exit 0 ;;
+      *)
+         echo "Unknown arg: $1" >&2
+         exit 2 ;;
+   esac
+done
+
+if ! command -v xctrace >/dev/null 2>&1; then
+   echo "xctrace not found. Install Xcode Command Line Tools: xcode-select --install" >&2
+   exit 1
+fi
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT"
+
+mkdir -p build
+TRACE="build/profile-$(date +%Y%m%d-%H%M%S).trace"
+
+# Make sure the core + harness are built (no BENCH_PROFILE; profiling
+# instrumentation skews sampling results).
+make -j"$(getconf _NPROCESSORS_ONLN 2>/dev/null || echo 4)" >/dev/null
+cc -O2 -Wall -std=c99 -I. -I./libretro-common/include \
+   -o test/tools/test_benchmark test/tools/test_benchmark.c
+
+CORE="./virtualjaguar_libretro.dylib"
+HARNESS="./test/tools/test_benchmark"
+
+echo ">>> xctrace template:   $TEMPLATE"
+echo ">>> trace output:       $TRACE"
+echo ">>> rom / blitter:      $ROM / $BLITTER"
+echo ">>> frames (+warmup):   $FRAMES (+$WARMUP)"
+
+xctrace record \
+   --template "$TEMPLATE" \
+   --output "$TRACE" \
+   --launch -- "$HARNESS" "$CORE" "$ROM" "$FRAMES" \
+                          --warmup "$WARMUP" --blitter "$BLITTER"
+
+echo ">>> trace written to $TRACE"
+if [ "$OPEN_TRACE" = "1" ]; then
+   open "$TRACE"
+fi
diff --git a/src/core/perf_counters.c b/src/core/perf_counters.c
@@ -0,0 +1,41 @@
+/*
+ * perf_counters.c - registry + dump for opt-in instrumentation counters.
+ * Only compiled into the program when BENCH_PROFILE is defined; the header
+ * provides no-op stubs otherwise.
+ */
+#include "perf_counters.h"
+
+#ifdef BENCH_PROFILE
+
+static perf_counter_entry_t *perf_head = (perf_counter_entry_t *)0;
+
+void perf_counters_register(perf_counter_entry_t *entry)
+{
+   if (!entry || entry->next)
+      return; /* already linked */
+   entry->next = perf_head;
+   perf_head = entry;
+}
+
+void perf_counters_reset(void)
+{
+   perf_counter_entry_t *e;
+   for (e = perf_head; e; e = e->next)
+      *e->value = 0;
+}
+
+void perf_counters_dump(FILE *out)
+{
+   perf_counter_entry_t *e;
+   if (!out)
+      out = stderr;
+   if (!perf_head) {
+      fprintf(out, "[perf] no counters registered\n");
+      return;
+   }
+   fprintf(out, "[perf] counter dump:\n");
+   for (e = perf_head; e; e = e->next)
+      fprintf(out, "[perf]   %-40s %llu\n", e->name, *e->value);
+}
+
+#endif /* BENCH_PROFILE */
diff --git a/src/core/perf_counters.h b/src/core/perf_counters.h
@@ -0,0 +1,85 @@
+/*
+ * perf_counters.h - lightweight, opt-in instrumentation counters.
+ *
+ * Define BENCH_PROFILE at compile time to enable. Otherwise every macro
+ * expands to (void)0 and there is no runtime, code-size, or symbol cost.
+ *
+ * Usage:
+ *
+ *   #include "perf_counters.h"
+ *
+ *   PERF_COUNTER(blitter_inner);
+ *   PERF_COUNTER(blitter_phrase_reads);
+ *
+ *   void hot(void) {
+ *       PERF_INC(blitter_inner);
+ *       PERF_ADD(blitter_phrase_reads, 2);
+ *   }
+ *
+ *   // Somewhere at shutdown (e.g., test harness atexit):
+ *   perf_counters_dump(stderr);
+ *
+ * Counters self-register via constructor functions, so PERF_COUNTER must
+ * appear at file scope. Only one definition per name across the program.
+ *
+ * C89-clean. No designated initializers, no mid-block declarations.
+ */
+#ifndef VJ_PERF_COUNTERS_H
+#define VJ_PERF_COUNTERS_H
+
+#include <stdio.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifdef BENCH_PROFILE
+
+typedef struct perf_counter_entry
+{
+   const char *name;
+   unsigned long long *value;
+   struct perf_counter_entry *next;
+} perf_counter_entry_t;
+
+void perf_counters_register(perf_counter_entry_t *entry);
+void perf_counters_dump(FILE *out);
+void perf_counters_reset(void);
+
+#define PERF_COUNTER(name) \
+   static unsigned long long perf_##name = 0; \
+   static perf_counter_entry_t perf_entry_##name = \
+      { #name, &perf_##name, (perf_counter_entry_t *)0 }; \
+   __attribute__((constructor)) \
+   static void perf_register_##name(void) { \
+      perf_counters_register(&perf_entry_##name); \
+   } \
+   typedef int perf_##name##_decl_semicolon_eater
+
+/* PERF_INC / PERF_ADD are expressions of integer type (not statements),
+ * so they can be embedded in declaration initializers via the comma
+ * operator without violating C89's no-decl-after-statement rule:
+ *   uint32_t cmd = (PERF_INC(my_event), real_value());
+ */
+#define PERF_INC(name)    (++perf_##name)
+#define PERF_ADD(name, n) (perf_##name += (unsigned long long)(n))
+
+#else /* !BENCH_PROFILE */
+
+#define PERF_COUNTER(name) typedef int perf_##name##_unused
+/* No-op forms remain expressions of integer type (not void) so callers
+ * can use them inside comma operators without code changes. */
+#define PERF_INC(name)        (0)
+#define PERF_ADD(name, n)     ((void)(n), 0)
+
+/* Stubs so callers don't need their own #ifdef around dump/reset. */
+static __inline void perf_counters_dump(FILE *out)  { (void)out; }
+static __inline void perf_counters_reset(void)      { }
+
+#endif /* BENCH_PROFILE */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* VJ_PERF_COUNTERS_H */
diff --git a/src/tom/blitter.c b/src/tom/blitter.c
diff --git a/test/tools/test_benchmark.c b/test/tools/test_benchmark.c
