Sampling profiler — kit prof (planned work)

Forward-looking design for kit prof, a host-native statistical CPU profiler. It reuses the interactive JIT debugger's host signal infrastructure (../DBG.md, DEBUG.md): SIGPROF fires on the debugger's worker thread, the handler walks the frame-pointer chain into a pre-allocated ring buffer and returns without parking — the one property that keeps sampling cheap and guest timing undisturbed — and PCs are symbolicated after the guest exits.

Nothing exists yet: no prof subcommand in driver/main.c, no src/dbg/prof.c, no on_sample field on KitDbgSignalOps. This document is the worklist for building it.

Scope — this is the sampling profiler, deliberately on the host-native substrate. It is one of two complementary profilers, and it is not being rebased onto the emulator. This one measures real wall/CPU time by statistically sampling natively-run kit code; the deterministic instruction-counting profiler (callgrind-style — exact, reproducible, any guest arch) lives on the emulator substrate (INSTRUMENT.md §9, §12.1). The two share a back-end (symbolication + folded / flat output), not a collector. See INSTRUMENT.md §9 for the perf-vs-callgrind split and the one-core-two-collectors factoring.

1. Public API (include/kit.h)

• Add on_sample(void* session, void* ucontext) to KitDbgSignalOps (NULL = ignore SIGPROF); it receives the raw ucontext_t*, not a marshalled frame, because it extracts only PC and FP on the hot path.
• Declare KitProfBuf (fixed-capacity sample ring: pcs[PROF_MAX_DEPTH] per sample, count/cap/dropped) and KitProfWriter (post-run symbolication callback vtable), plus kit_dbg_session_prof_attach(session, buf) (before session_call) and kit_dbg_session_prof_collect(session, buf, writer).

2. Library (src/dbg/prof.c, freestanding C11)

• dbg_fp_walk(ucontext, sample): frame-pointer walk via dbg_os->guarded_copy for every dereference; terminate on NULL / misaligned / non-advancing FP or PROF_MAX_DEPTH. The three frame layouts are identical ([FP] = saved FP, [FP+8] = saved LR/return addr); FP is x29 / rbp / s0(x8). WHY: no DWARF or symbol lookup on the signal path — raw PCs only.
• on_sample body: capacity check, walk, append or bump dropped (non-atomic; the single worker makes that safe). prof_attach / prof_collect bodies; prof_collect symbolicates each PC via kit_jit_addr_to_sym + kit_dwarf_addr_to_line, dispatching to the writer (may allocate freely).

3. Host adapter (driver/env/posix_dbg.c and windows.c)

• Add SIGPROF to the POSIX handler's signal set with an early-return path: if (signo == SIGPROF && on_sample) { on_sample(...); return; } — no park/unpark. SIGPROF joins the blocked cohort so it does not recurse. Timer arming (setitimer(ITIMER_PROF)) and thread targeting stay driver-side and do not belong behind KitDbgOs.
• Decide the Windows sampling mechanism (no SIGPROF): a periodic SuspendThread + GetThreadContext sampler thread is the natural analog of the VEH interrupt path. WHY: the SIGPROF design has no direct Windows equivalent, so this is a genuine open design question, not a port.

4. Driver (driver/cmd/prof.c)

Wired into the multi-call dispatch in driver/main.c:

• Flags --rate (default 1ms), --depth (64), --cap (1M), --output (prof.folded), --no-folded, --no-flat. Input handling mirrors kit run, with -g forced on so symbolication always has DWARF.
• Arm the timer before session_call, disarm after, then prof_collect. Emit folded stacks (sorted + RLE for flamegraph.pl) plus a flat self%/cumul% report to stdout and a dropped-sample warning.

5. Tests

• test/smoke/prof_hello: assert prof.folded is non-empty and main appears.
• test/dbg/fp_walk_*: canned frame chains per arch, assert the PC sequence and termination.
• test/dbg/prof_buf_overflow: fill to capacity, assert dropped increments and count caps.

6. Follow-ons (deferred)

• Per-thread timers via timer_create(CLOCK_THREAD_CPUTIME_ID) + SIGEV_THREAD_ID for multi-thread guests. This depends on widening KitDbgOs for multi-threaded guests (DEBUG.md §7).
• An ITIMER_REAL wall-clock mode for I/O-bound programs.
• Allocation profiling via a conditional breakpoint on the allocator.
• SpeedScope / pprof output.