Contract 0.6: performance metrics (GET/POST /perf) and /status.capabilities (#6) proposal #7 landed andymccall wants perf-6 into main · 1 change · opened 25 days ago

Closes issue #6.

Contract 0.6: performance metrics. It's additive: older clients and servers are unaffected.

• GET /perf[?windows=][&zones=][&frames=][&since=]: how much of each frame the program uses, in guest CPU cycles.
  • budget, the frame and its budget;
  • current, the last completed frame: total, work, idle, IRQ and main cycles, instructions, host µs and utilisation;
  • windows, with min/mean/p50/p95/p99/max and overruns;
  • zones, address ranges or regions the guest marks, each with its own windows;
  • frames, raw records: the last n, or every frame since one, so a polling harness misses none;
  • platform, for the rest.
• POST /perf: a JSON settings body: enabled, targetFps, idleMode, historyFrames, reset, and zones (an address range, or {name, marker} naming a guest marker region). A bad body is a 400.
• /status.capabilities: the endpoint groups a server serves, whatever level it reaches, so a client can ask for perf (or pointer) directly. contract stays cumulative.
• Core: get_perf and set_perf callbacks return allocated JSON the core frees, so the core stays platform-neutral. They're marshalled to the emulator thread like /mem. A NULL callback gives a 501 and lowers the level.
• Also: a client (perf, perf_config, capabilities), five conformance tests gated on 0.6, a CHANGELOG entry, and the README and SPEC. The SPEC's X16 appendix documents the $9FBC markers and the X16 platform section (VERA bus per scanline, sprite render time).

Tested: the whole conformance suite, 27 of 27, against the first 0.6 backend, the enhanced X16 emulator (enhanced-x16-emulator issue #1), launched with RRDC_EMU_CMD. The core builds clean with -Wall -Wextra.

Used by: Metal Gear's harness reads /perf to profile the game by phase (metalgear #261).