Contract 0.6: performance metrics (GET/POST /perf) and /status capabilities issue #6 open andymccall opened this 25 days ago · 0 comments

Ask: a contract level for performance metrics, so a harness can measure how much of each frame a program uses, in the same way it already reads memory and steps frames.

Today nothing in the contract reports CPU time. Metal Gear on the X16 had to put its own scanline probes in the game, at a cost in MAIN memory and with torn reads. Meanwhile the enhanced X16 emulator already computes all of it, but exposes it only over DAP (x16/perfStats, x16/perfConfig):

• a CPU cycle budget per frame (total, work, IRQ, idle);
• statistics windows;
• zones, including regions the guest marks;
• VERA bus bandwidth.

Proposed 0.6.0 (additive):

• GET /perf[?windows=][&zones=][&frames=][&since=] returns JSON:
  • budget, current (the last completed frame), windows[] (min, mean, p50, p95, p99, max and overruns), zones[] and frames[] (raw per-frame records), all platform-neutral, in guest CPU cycles;
  • platform, for the rest (the X16's VERA bandwidth and sprite render time).
• POST /perf takes a JSON body of settings: enabled, target FPS, idle mode, history, zones (address ranges, or names for guest marker regions) and reset.
• /status gains capabilities, a list of the endpoint groups the backend serves, so a client can check for perf without relying on the cumulative ladder.
• Backend callbacks get_perf and set_perf return allocated JSON, so the core stays platform-neutral.
• Conformance tests are gated on 0.6.