emu_prof.c

Go to the documentation of this file.

 
#include "emu_prof.h"
 
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>
 
#include "emu_elf.h"
#include "emu_host_io_internal.h"

static const double s_nsec_per_sec = 1.0e9;

double board_now_s(void)
{
  struct timespec ts = {};
  (void)clock_gettime(CLOCK_MONOTONIC, &ts);
  return (double)ts.tv_sec + ((double)ts.tv_nsec / s_nsec_per_sec);
}
 
/* ===========================================================================
 * Firmware profiler (RA8_EMU_PROFILE). Two modes, bucketed by ELF FUNC symbol:
 *   =1     wall-time sample -- charge each chunk's wall time to its start PC.
 *          Cheap (no per-instruction cost); a flat % list of the dominant cost.
 *   =full  per-instruction -- a code hook tallies every instruction + call entry
 *          AND reconstructs the live call chain (see below), so the run end emits
 *          an Ozone-style breakdown: a boot timeline, an inclusive/self table,
 *          and a speedscope flamechart file. Accurate but ~10x slower; off by
 *          default. The run auto-stops once boot settles into the idle frame
 *          loop, so =full profiles boot work rather than the idle tail.
 * ===========================================================================
 */
enum : uint32_t {
  k_prof_max_syms = 8192U, 
  k_prof_top_n    = 40U,   
};
typedef struct {
  uint32_t lo;          
  uint32_t hi;          
  uint64_t name_offset; 
  double   secs;        
  uint64_t insns;       
  uint64_t calls;       
} prof_sym_t;
static prof_sym_t              s_prof[k_prof_max_syms];
static const emu_elf_source_t* s_prof_elf; 
static uint32_t                s_prof_n       = 0U;
static double                  s_prof_total_s = 0.0;
static uint64_t                s_prof_total_i = 0U;
static prof_mode_t             s_prof_mode    = k_prof_off;
 
/* ---------------------------------------------------------------------------
 * Ozone-style call-stack tracing (insn mode only). On top of the per-function
 * tally above, reconstruct the live call chain straight from the PC stream: a
 * fresh function entry that is not already on the chain is a call (push), and
 * re-entering a function already deeper on the chain is a return (pop down to
 * it). NASA Rule 1 bans recursion in this firmware, so a function appears at
 * most once on the chain and the "already on the chain" test is unambiguous.
 * The chain is sampled at a fixed instruction cadence into a bounded,
 * chronological store and written out as a speedscope "sampled" profile -- open
 * ra8_emulator_profile.speedscope.json at https://speedscope.app for the
 * time-ordered flamechart ("what ran when", the Ozone timeline) plus the
 * sandwich view (self vs total per function). WFI idle naturally weighs ~zero
 * because a halted core retires no instructions, so the picture is boot work,
 * not the idle frame loop. ===============================================
 */
enum : uint32_t {
  k_prof_max_depth   = 64U,    
  k_prof_max_samples = 16384U, 
  k_prof_samp_every  = 256U,   
};
static uint16_t s_pstk[k_prof_max_depth];                      
static uint32_t s_pstk_n = 0U;                                 
static uint16_t s_samp[k_prof_max_samples][k_prof_max_depth];  
static uint8_t  s_samp_d[k_prof_max_samples];                  
static uint32_t s_samp_w[k_prof_max_samples];                  
static uint32_t s_samp_n        = 0U;                          
static uint64_t s_samp_every    = (uint64_t)k_prof_samp_every; 
static uint64_t s_samp_acc      = 0U;                          
static uint32_t s_prof_stop_pc  = 0U;                          
static bool     s_prof_stop_hit = false;                       
static uint64_t s_incl[k_prof_max_syms];                       
static uint64_t s_self[k_prof_max_syms];                       

RA8_INTERNAL static int internal_prof_cmp(const void* a, const void* b)
{
  const uint32_t la = ((const prof_sym_t*)a)->lo;
  const uint32_t lb = ((const prof_sym_t*)b)->lo;
  if (la < lb) {
    return -1;
  }
  if (la > lb) {
    return 1;
  }
  return 0;
}

RA8_INTERNAL static bool internal_prof_symbol(const emu_elf_symbol_t* symbol, void* ctx)
{
  (void)ctx;
  if (((symbol->info & (uint8_t)k_elf_st_type_mask) != 2U) || (symbol->size == 0U) ||
      (symbol->name_offset == 0U)) {
    return true;
  }
  if (s_prof_n >= (uint32_t)k_prof_max_syms) {
    return false;
  }
  const uint32_t lo = symbol->value & ~1U;
  s_prof[s_prof_n] =
    (prof_sym_t){.lo = lo, .hi = lo + symbol->size, .name_offset = symbol->name_offset};
  s_prof_n++;
  return true;
}

void prof_load(const emu_elf_source_t* elf)
{
  const char* mode = getenv("RA8_EMU_PROFILE");
  if (mode == nullptr) {
    s_prof_mode = k_prof_off;
    return;
  }
  s_prof_mode =
    ((strcmp(mode, "full") == 0) || (strcmp(mode, "insn") == 0)) ? k_prof_insn : k_prof_wall;
  s_prof_n   = 0U;
  s_prof_elf = elf;
  (void)elf_foreach_symbol(elf, internal_prof_symbol, nullptr);
  qsort(s_prof, (size_t)s_prof_n, sizeof(s_prof[0]), internal_prof_cmp);
  (void)priv_emu_io_errf("  [profile] %s; %u FUNC symbols\n",
                         (s_prof_mode == k_prof_insn) ? "per-instruction (exact, slow)"
                                                      : "wall-time sample",
                         (unsigned)s_prof_n);
}

RA8_INTERNAL static uint32_t internal_prof_find(uint32_t pc)
{
  uint32_t lo = 0U;
  uint32_t hi = s_prof_n;
  while (lo < hi) {
    const uint32_t mid = lo + ((hi - lo) / 2U);
    if (s_prof[mid].lo <= pc) {
      lo = mid + 1U;
    } else {
      hi = mid;
    }
  }
  if (lo == 0U) {
    return s_prof_n;
  }
  const uint32_t idx = lo - 1U;
  return (pc < s_prof[idx].hi) ? idx : s_prof_n;
}

void prof_add(uint32_t pc, double dt)
{
  if (s_prof_mode != k_prof_wall) {
    return;
  }
  s_prof_total_s += dt;
  const uint32_t idx = internal_prof_find(pc);
  if (idx < s_prof_n) {
    s_prof[idx].secs += dt;
  }
}

RA8_INTERNAL static void internal_prof_decimate(void)
{
  uint32_t dst = 0U;
  for (uint32_t i = 0U; i < s_samp_n; i += 2U) {
    const uint32_t w2 = ((i + 1U) < s_samp_n) ? s_samp_w[i + 1U] : 0U;
    if (dst != i) {
      (void)memcpy(s_samp[dst], s_samp[i], (size_t)s_samp_d[i] * sizeof(uint16_t));
      s_samp_d[dst] = s_samp_d[i];
    }
    s_samp_w[dst] = s_samp_w[i] + w2; /* merged time keeps the total exact. */
    dst++;
  }
  s_samp_n = dst;
  s_samp_every *= 2U; /* coarser cadence keeps the next fill the same span. */
}

RA8_INTERNAL static void internal_prof_sample(uint32_t weight)
{
  if (s_samp_n >= (uint32_t)k_prof_max_samples) {
    internal_prof_decimate();
  }
  uint32_t d = s_pstk_n;
  if (d > (uint32_t)k_prof_max_depth) {
    d = (uint32_t)k_prof_max_depth;
  }
  for (uint32_t i = 0U; i < d; i++) {
    s_samp[s_samp_n][i] = s_pstk[i];
  }
  s_samp_d[s_samp_n] = (uint8_t)d;
  s_samp_w[s_samp_n] = weight;
  s_samp_n++;
}

RA8_INTERNAL static void internal_prof_stack_update(uint32_t f)
{
  if (f >= s_prof_n) {
    return; /* unknown region -- keep the current leaf (it gets the self time). */
  }
  if ((s_pstk_n > 0U) && (s_pstk[s_pstk_n - 1U] == (uint16_t)f)) {
    return; /* still in the same function -- no call/return transition. */
  }
  for (uint32_t i = s_pstk_n; i > 0U; i--) {
    if (s_pstk[i - 1U] == (uint16_t)f) {
      s_pstk_n = i; /* returned to a frame already on the chain -- unwind to it. */
      return;
    }
  }
  if (s_pstk_n < (uint32_t)k_prof_max_depth) {
    s_pstk[s_pstk_n] = (uint16_t)f; /* a fresh call -- push it. */
    s_pstk_n++;
  }
}

RA8_INTERNAL static void
internal_prof_insn_hook(uc_engine* uc, uint64_t address, uint32_t size, void* user)
{
  (void)size;
  (void)user;
  s_prof_total_i++;
  const uint32_t idx = internal_prof_find((uint32_t)address);
  if (idx < s_prof_n) {
    s_prof[idx].insns++;
    if ((uint32_t)address == s_prof[idx].lo) {
      s_prof[idx].calls++; /* PC at the entry point -> a fresh call (approx). */
    }
  }
  internal_prof_stack_update(idx);
  s_samp_acc++;
  if (s_samp_acc >= s_samp_every) {
    internal_prof_sample((uint32_t)s_samp_acc);
    s_samp_acc = 0U;
  }
  if ((s_prof_stop_pc != 0U) && ((uint32_t)address == s_prof_stop_pc)) {
    s_prof_stop_hit = true; /* RA8_EMU_STOP_PC reached -- end the run cleanly. */
    (void)uc_emu_stop(uc);
  }
}

RA8_INTERNAL static bool internal_prof_io_ok(emu_io_result_t result)
{
  return result.status == k_emu_io_ok;
}

typedef struct {
  int  fd;         
  char escape;     
  bool error_sink; 
  bool ok;         
} prof_name_sink_t;

RA8_INTERNAL static bool internal_prof_name_chunk(const char* bytes, size_t length, void* opaque)
{
  prof_name_sink_t* const sink = (prof_name_sink_t*)opaque;
  if ((sink->escape == '\0') && sink->error_sink) {
    sink->ok = internal_prof_io_ok(priv_emu_io_err_bytes(bytes, length));
    return sink->ok;
  }
  for (size_t index = 0U; (index < length) && sink->ok; index++) {
    if ((sink->escape != '\0') && (bytes[index] == sink->escape || bytes[index] == '\\')) {
      sink->ok = internal_prof_io_ok(priv_emu_io_file_char(sink->fd, '\\'));
    }
    if (sink->ok) {
      sink->ok = internal_prof_io_ok(priv_emu_io_file_char(sink->fd, bytes[index]));
    }
  }
  return sink->ok;
}

RA8_INTERNAL static bool internal_prof_name(uint32_t symbol, int fd, char escape, bool error_sink)
{
  if ((symbol >= s_prof_n) || (s_prof_elf == nullptr)) {
    return false;
  }
  prof_name_sink_t sink = {.fd = fd, .escape = escape, .error_sink = error_sink, .ok = true};
  return elf_string_foreach(s_prof_elf,
                            s_prof[symbol].name_offset,
                            internal_prof_name_chunk,
                            &sink) &&
         sink.ok;
}

RA8_INTERNAL static bool internal_prof_json_frames(int fd)
{
  bool ok = true;
  for (uint32_t i = 0U; i < s_prof_n; i++) {
    ok = internal_prof_io_ok(
           priv_emu_io_file_text(fd, (i == 0U) ? "{\"name\":\"" : ",{\"name\":\"")) &&
         ok;
    ok = internal_prof_name(i, fd, '"', false) && ok;
    ok = internal_prof_io_ok(priv_emu_io_file_text(fd, "\"}")) && ok;
  }
  return ok;
}

RA8_INTERNAL static bool internal_prof_json_samples(int fd)
{
  bool ok = true;
  for (uint32_t i = 0U; i < s_samp_n; i++) {
    ok = internal_prof_io_ok(priv_emu_io_file_char(fd, (i == 0U) ? '[' : ',')) && ok;
    if (i != 0U) {
      ok = internal_prof_io_ok(priv_emu_io_file_char(fd, '[')) && ok;
    }
    for (uint8_t j = 0U; j < s_samp_d[i]; j++) {
      ok = internal_prof_io_ok(
             priv_emu_io_filef(fd, (j == 0U) ? "%u" : ",%u", (unsigned)s_samp[i][j])) &&
           ok;
    }
    ok = internal_prof_io_ok(priv_emu_io_file_char(fd, ']')) && ok;
  }
  return ok;
}

RA8_INTERNAL static bool internal_prof_json_weights(int fd)
{
  bool ok = true;
  for (uint32_t i = 0U; i < s_samp_n; i++) {
    ok =
      internal_prof_io_ok(priv_emu_io_filef(fd, (i == 0U) ? "%u" : ",%u", (unsigned)s_samp_w[i])) &&
      ok;
  }
  return ok;
}

RA8_INTERNAL static bool internal_prof_js_frames(int fd)
{
  bool ok = true;
  for (uint32_t i = 0U; i < s_prof_n; i++) {
    ok = internal_prof_io_ok(priv_emu_io_file_text(fd, (i == 0U) ? "'" : ",'")) && ok;
    ok = internal_prof_name(i, fd, '\'', false) && ok;
    ok = internal_prof_io_ok(priv_emu_io_file_char(fd, '\'')) && ok;
  }
  return ok;
}

RA8_INTERNAL static void internal_prof_write_speedscope(const char* path)
{
  if ((s_samp_n == 0U) || (s_prof_n == 0U)) {
    return;
  }
  emu_io_txn_t txn = {.fd = -1};
  if (priv_emu_io_txn_begin(path, &txn).status != k_emu_io_ok) {
    return;
  }
  uint64_t total = 0U;
  for (uint32_t i = 0U; i < s_samp_n; i++) {
    total += s_samp_w[i];
  }
  bool ok = internal_prof_io_ok(
    priv_emu_io_file_text(txn.fd,
                          "{\"$schema\":\"https://www.speedscope.app/file-format-schema.json\",\n"
                          " \"name\":\"ra8_emulator boot\",\"activeProfileIndex\":0,\n"
                          " \"shared\":{\"frames\":["));
  ok = internal_prof_json_frames(txn.fd) && ok;
  ok = internal_prof_io_ok(priv_emu_io_filef(
         txn.fd,
         "]},\n"
         " \"profiles\":[{\"type\":\"sampled\",\"name\":\"boot\",\"unit\":\"none\",\n"
         "  \"startValue\":0,\"endValue\":%llu,\n"
         "  \"samples\":[",
         (unsigned long long)total)) &&
       ok;
  ok = internal_prof_json_samples(txn.fd) && ok;
  ok = internal_prof_io_ok(priv_emu_io_file_text(txn.fd, "],\n  \"weights\":[")) && ok;
  ok = internal_prof_json_weights(txn.fd) && ok;
  ok = internal_prof_io_ok(priv_emu_io_file_text(txn.fd, "]}]}\n")) && ok;
  if (!ok || (priv_emu_io_txn_commit(&txn).status != k_emu_io_ok)) {
    priv_emu_io_txn_abort(&txn);
  }
}
 
/* Self-contained flamechart viewer markup. The page embeds the profile arrays
 * (written just before this) and renders a time-ordered flame chart on a canvas
 * -- the Ozone timeline, but as a local file that opens in any browser with no
 * upload and no external site. Single-quoted HTML/JS strings keep the C literal
 * free of escapes; pure 7-bit ASCII. */
static const char s_k_prof_html_head[] =
  "<!doctype html><html><head><meta charset='utf-8'><title>ra8_emulator profile</title>\n"
  "<style>\n"
  "body{margin:0;font:12px Menlo,monospace;background:#1e1e1e;color:#ddd}\n"
  "#bar{padding:7px 10px;background:#2a2a2a;border-bottom:1px solid #444}\n"
  "#bar b{color:#fff}#bar button,#bar input{font:11px monospace;margin-left:10px;"
  "background:#3a3a3a;color:#ddd;border:1px solid #555;padding:2px 6px}\n"
  "#tip{position:fixed;pointer-events:none;background:#000;color:#fff;padding:5px 7px;"
  "border:1px solid #888;display:none;white-space:nowrap;z-index:9;font:11px monospace}\n"
  "canvas{display:block;cursor:crosshair}\n"
  "</style></head><body>\n"
  "<div id='bar'><b id='title'></b><span id='info'></span>"
  "<button onclick='resetView()'>Reset zoom</button>"
  "search:<input id='q' size='18' oninput='onSearch()'></div>\n"
  "<canvas id='fc'></canvas><div id='tip'></div>\n<script>\n";
 
static const char s_k_prof_html_js[] =
  "var cv=document.getElementById('fc'),ctx=cv.getContext('2d'),tip=document.getElementById('tip');\n"
  "document.getElementById('title').textContent=TITLE;\n"
  "var ROW=18,total=0,i;for(i=0;i<WEIGHTS.length;i++)total+=WEIGHTS[i];\n"
  "var maxd=0;for(i=0;i<SAMPLES.length;i++)if(SAMPLES[i].length>maxd)maxd=SAMPLES[i].length;\n"
  "var rects=[],incl={},self={};\n"
  "for(var d=0;d<maxd;d++){var cum=0,rs=0,rf=-1,op=false;\n"
  " for(i=0;i<SAMPLES.length;i++){var ff=d<SAMPLES[i].length?SAMPLES[i][d]:-1;\n"
  "  if(!(op&&ff===rf)){if(op&&rf>=0)rects.push({d:d,a:rs,b:cum,f:rf});rs=cum;rf=ff;op=true;}\n"
  "  cum+=WEIGHTS[i];}\n"
  " if(op&&rf>=0)rects.push({d:d,a:rs,b:cum,f:rf});}\n"
  "for(i=0;i<SAMPLES.length;i++){var s=SAMPLES[i],w=WEIGHTS[i];\n"
  " for(var j=0;j<s.length;j++)incl[s[j]]=(incl[s[j]]||0)+w;\n"
  " if(s.length)self[s[s.length-1]]=(self[s[s.length-1]]||0)+w;}\n"
  "var vx0=0,vx1=total,q='';\n"
  "function col(fi){var n=FRAMES[fi],h=0,k;for(k=0;k<n.length;k++)h=(h*31+n.charCodeAt(k))&0xffffff;\n"
  " var lit=(q&&n.toLowerCase().indexOf(q)>=0);return 'hsl('+(h%359)+','+(lit?'90%':'48%')+','+(lit?'62%':'44%')+')';}\n"
  "function resize(){cv.width=window.innerWidth;cv.height=Math.max(maxd*ROW+4,160);draw();}\n"
  "function draw(){ctx.clearRect(0,0,cv.width,cv.height);var span=vx1-vx0;if(span<=0)return;\n"
  " ctx.font='11px monospace';ctx.textBaseline='middle';\n"
  " for(var r=0;r<rects.length;r++){var R=rects[r];if(R.b<=vx0||R.a>=vx1)continue;\n"
  "  var p0=(R.a-vx0)/span*cv.width,p1=(R.b-vx0)/span*cv.width,w=p1-p0;if(w<0.4)continue;\n"
  "  var y=R.d*ROW;ctx.fillStyle=col(R.f);ctx.fillRect(p0,y,Math.max(w-0.6,0.5),ROW-1);\n"
  "  if(w>34){ctx.fillStyle='#111';ctx.fillText(FRAMES[R.f],p0+3,y+ROW/2,w-6);}}}\n"
  "function pick(mx,my){var d=Math.floor(my/ROW),span=vx1-vx0,wx=vx0+mx/cv.width*span,r;\n"
  " for(r=0;r<rects.length;r++){var R=rects[r];if(R.d===d&&wx>=R.a&&wx<R.b)return R;}return null;}\n"
  "cv.onmousemove=function(e){var R=pick(e.offsetX,e.offsetY);if(!R){tip.style.display='none';return;}\n"
  " var n=FRAMES[R.f],to=incl[R.f]||0,se=self[R.f]||0;\n"
  " tip.innerHTML=n+'<br>this block: '+((R.b-R.a)/total*100).toFixed(2)+'% ('+(R.b-R.a)+' insns)'+\n"
  "  '<br>total '+(to/total*100).toFixed(2)+'%  self '+(se/total*100).toFixed(2)+'%';\n"
  " tip.style.display='block';tip.style.left=(e.clientX+14)+'priv_px';tip.style.top=(e.clientY+14)+'priv_px';};\n"
  "cv.onmouseleave=function(){tip.style.display='none';};\n"
  "cv.onclick=function(e){var R=pick(e.offsetX,e.offsetY);if(R){vx0=R.a;vx1=R.b;draw();}};\n"
  "function resetView(){vx0=0;vx1=total;draw();}\n"
  "function onSearch(){q=document.getElementById('q').value.toLowerCase();draw();}\n"
  "document.getElementById('info').textContent=' | '+SAMPLES.length+' samples, '+total+\n"
  "  ' insns  (hover for self/total, click a block to zoom, Reset to zoom out)';\n"
  "window.onresize=resize;resize();\n";

RA8_INTERNAL static void internal_prof_write_html(const char* path, uint64_t total)
{
  if ((s_samp_n == 0U) || (s_prof_n == 0U)) {
    return;
  }
  emu_io_txn_t txn = {.fd = -1};
  if (priv_emu_io_txn_begin(path, &txn).status != k_emu_io_ok) {
    return;
  }
  bool ok = internal_prof_io_ok(priv_emu_io_file_text(txn.fd, s_k_prof_html_head));
  ok      = internal_prof_io_ok(priv_emu_io_file_text(txn.fd, "var FRAMES=[")) && ok;
  ok      = internal_prof_js_frames(txn.fd) && ok;
  ok      = internal_prof_io_ok(priv_emu_io_file_text(txn.fd, "];\n")) && ok;
  /* SAMPLES / WEIGHTS are plain integer arrays, so the JSON the speedscope
   * writer emits is already valid JavaScript -- the same two helpers serve. */
  ok = internal_prof_io_ok(priv_emu_io_file_text(txn.fd, "var SAMPLES=[")) && ok;
  ok = internal_prof_json_samples(txn.fd) && ok;
  ok = internal_prof_io_ok(priv_emu_io_file_text(txn.fd, "];\nvar WEIGHTS=[")) && ok;
  ok = internal_prof_json_weights(txn.fd) && ok;
  ok = internal_prof_io_ok(
         priv_emu_io_filef(txn.fd,
                           "];\nvar TITLE='ra8_emulator flamechart -- %llu insns, %u samples';\n",
                           (unsigned long long)total,
                           (unsigned)s_samp_n)) &&
       ok;
  ok = internal_prof_io_ok(priv_emu_io_file_text(txn.fd, s_k_prof_html_js)) && ok;
  ok = internal_prof_io_ok(priv_emu_io_file_text(txn.fd, "</script></body></html>\n")) && ok;
  if (!ok || (priv_emu_io_txn_commit(&txn).status != k_emu_io_ok)) {
    priv_emu_io_txn_abort(&txn);
  }
}

static const double s_percent_scale = 100.0;

typedef enum : uint32_t {
  k_no_fn        = 0xFFFFFFFFU, 
  k_phase_depth  = 2U,          
  k_phase_lines  = 24U,         
  k_phase_pct_x1 = 100U,        
} prof_phase_t;

RA8_INTERNAL static uint64_t internal_prof_accumulate_incl_self(void)
{
  /* Inclusive (anywhere on the chain) + self (leaf) weights, from the samples.
   * No recursion (NASA Rule 1) -> each function appears at most once per sample,
   * so a straight per-frame add needs no dedup. */
  uint64_t total = 0U;
  for (uint32_t i = 0U; i < s_prof_n; i++) {
    s_incl[i] = 0U;
    s_self[i] = 0U;
  }
  for (uint32_t i = 0U; i < s_samp_n; i++) {
    const uint32_t w = s_samp_w[i];
    const uint8_t  d = s_samp_d[i];
    total += w;
    for (uint8_t j = 0U; j < d; j++) {
      s_incl[s_samp[i][j]] += w;
    }
    if (d > 0U) {
      s_self[s_samp[i][d - 1U]] += w;
    }
  }
  return total;
}

RA8_INTERNAL static void
internal_prof_print_phase(uint32_t segfn, uint64_t cum, uint64_t segw, uint64_t total)
{
  (void)priv_emu_io_errf("    %5.1f%%  +%4.1f%%  ",
                         s_percent_scale * (double)cum / (double)total,
                         s_percent_scale * (double)segw / (double)total);
  if (segfn < s_prof_n) {
    (void)internal_prof_name(segfn, -1, '\0', true);
  } else {
    (void)priv_emu_io_err_text("?");
  }
  (void)priv_emu_io_err_text("\n");
}

RA8_INTERNAL static void internal_prof_print_boot_timeline(uint64_t total)
{
  /* Phase timeline: collapse each sample's chain to a fixed shallow depth (the
   * major subsystem under main) and print each contiguous run as a boot phase,
   * so the terminal shows "what ran when" even without opening speedscope. */
  (void)priv_emu_io_errf("  [profile] boot timeline (phase = call depth %u; start%% .. width%%):\n",
                         (unsigned)k_phase_depth);
  uint64_t cum   = 0U;
  uint64_t segw  = 0U;
  uint32_t segfn = (uint32_t)k_no_fn;
  uint32_t lines = 0U;
  for (uint32_t i = 0U; i <= s_samp_n; i++) {
    uint32_t fn = (uint32_t)k_no_fn;
    if (i < s_samp_n) {
      const uint8_t d = s_samp_d[i];
      if (d > 0U) {
        const uint8_t pd = ((uint32_t)(d - 1U) < (uint32_t)k_phase_depth) ? (uint8_t)(d - 1U)
                                                                          : (uint8_t)k_phase_depth;
        fn               = s_samp[i][pd];
      }
    }
    if ((i == s_samp_n) || (fn != segfn)) {
      const bool show = (segfn != (uint32_t)k_no_fn) &&
                        (((uint32_t)k_phase_pct_x1 * segw) >= total) &&
                        (lines < (uint32_t)k_phase_lines);
      if (show) {
        internal_prof_print_phase(segfn, cum, segw, total);
        lines++;
      }
      cum += segw;
      segw  = 0U;
      segfn = fn;
    }
    if (i < s_samp_n) {
      segw += s_samp_w[i];
    }
  }
}

RA8_INTERNAL static void
internal_prof_print_incl_self_table(const char* html, const char* out, uint64_t total)
{
  /* Inclusive/self table -- the "why is it slow" view (sorted by inclusive). */
  (void)priv_emu_io_errf("  [profile] flamechart GUI -> %s  (interactive: hover/zoom/search)\n"
                         "  [profile] %u samples over %llu insns  (also %s for speedscope.app)\n"
                         "       self%%    total%%  function\n",
                         html,
                         (unsigned)s_samp_n,
                         (unsigned long long)total,
                         out);
  for (uint32_t k = 0U; k < (uint32_t)k_prof_top_n; k++) {
    uint32_t best  = s_prof_n;
    uint64_t bestv = 0U;
    for (uint32_t i = 0U; i < s_prof_n; i++) {
      if (s_incl[i] > bestv) {
        bestv = s_incl[i];
        best  = i;
      }
    }
    if ((best == s_prof_n) || (bestv == 0U)) {
      break;
    }
    (void)priv_emu_io_errf("    %8.2f%%  %7.2f%%  ",
                           s_percent_scale * (double)s_self[best] / (double)total,
                           s_percent_scale * (double)s_incl[best] / (double)total);
    (void)internal_prof_name(best, -1, '\0', true);
    (void)priv_emu_io_err_text("\n");
    s_incl[best] = 0U; /* consume so the next pick is the runner-up. */
  }
}

RA8_INTERNAL static void internal_prof_report_flamechart(void)
{
  const char* out = getenv("RA8_EMU_PROFILE_OUT");
  if ((out == nullptr) || (out[0] == '\0')) {
    out = "ra8_emulator_profile.speedscope.json";
  }
  const char* html = getenv("RA8_EMU_PROFILE_HTML");
  if ((html == nullptr) || (html[0] == '\0')) {
    html = "ra8_emulator_profile.html";
  }
  internal_prof_write_speedscope(out);
 
  const uint64_t total = internal_prof_accumulate_incl_self();
  if (total == 0U) {
    return;
  }
  internal_prof_write_html(html, total); /* self-contained local GUI flamechart. */
  internal_prof_print_boot_timeline(total);
  internal_prof_print_incl_self_table(html, out, total);
}

void prof_report(void)
{
  const bool   insn = (s_prof_mode == k_prof_insn);
  const double tot  = insn ? (double)s_prof_total_i : s_prof_total_s;
  if ((s_prof_mode == k_prof_off) || (tot <= 0.0)) {
    return;
  }
  if (insn) {
    (void)priv_emu_io_errf("  [profile] %llu instructions; hottest (by instruction count):\n"
                           "     %%insn       instructions       calls  function\n",
                           (unsigned long long)s_prof_total_i);
  } else {
    (void)priv_emu_io_errf("  [profile] %.2fs wall sampled; hottest (by wall time):\n", tot);
  }
  for (uint32_t k = 0U; k < (uint32_t)k_prof_top_n; k++) {
    uint32_t best  = s_prof_n;
    double   bestv = 0.0;
    for (uint32_t i = 0U; i < s_prof_n; i++) {
      const double v = insn ? (double)s_prof[i].insns : s_prof[i].secs;
      if (v > bestv) {
        bestv = v;
        best  = i;
      }
    }
    if ((best == s_prof_n) || (bestv <= 0.0)) {
      break;
    }
    if (insn) {
      (void)priv_emu_io_errf("    %6.2f%%  %15llu  %10llu  ",
                             s_percent_scale * bestv / tot,
                             (unsigned long long)s_prof[best].insns,
                             (unsigned long long)s_prof[best].calls);
      (void)internal_prof_name(best, -1, '\0', true);
      (void)priv_emu_io_err_text("\n");
      s_prof[best].insns = 0U;
    } else {
      (void)priv_emu_io_errf("    %6.2f%%  %8.2fs  ", s_percent_scale * bestv / tot, bestv);
      (void)internal_prof_name(best, -1, '\0', true);
      (void)priv_emu_io_err_text("\n");
      s_prof[best].secs = 0.0;
    }
  }
  if (insn && (s_samp_n > 0U)) {
    internal_prof_report_flamechart(); /* speedscope export + inclusive/self + timeline. */
  }
}

void emu_prof_install(uc_engine* uc)
{
  if (s_prof_mode == k_prof_insn) {
    static uc_hook s_h_prof;
    (void)uc_hook_add(uc, &s_h_prof, UC_HOOK_CODE, (void*)internal_prof_insn_hook, nullptr, 1, 0);
  }
}

prof_mode_t emu_prof_mode(void)
{
  return s_prof_mode;
}

uint64_t emu_prof_total_insns(void)
{
  return s_prof_total_i;
}

void emu_prof_set_stop_pc(uint32_t pc)
{
  s_prof_stop_pc = pc;
}

bool emu_prof_stop_hit(void)
{
  return s_prof_stop_hit;
}