Performance budgets: telling work apart from waiting

Two budgets, in one panel and one DAP response: the CPU's cycles, and VERA's VRAM bandwidth. They answer the same question — "what is eating my frame?" — from the two ends that can independently run out, and the frames worth looking at are the ones where they disagree.

The cycle model comes first; VERA's bandwidth is below.

The problem

"How much of my frame am I using?" has no direct answer on a 6502, because the CPU never idles. At 8 MHz a VGA frame is exactly

cycles/frame = MHZ * 1e6 * (VGA_SCAN_WIDTH * SCAN_HEIGHT) / PIXEL_FREQ
             = 8e6 * (800 * 525) / 25e6
             = 134,400 cycles          (256 per scanline, over 525 lines)

and the machine burns every one of them whether your program is doing work or spinning on a vsync flag. Raw cycles-per-frame is therefore always 100% and says nothing at all.

The number you actually want is work versus waiting. Producing it means classifying cycles, and classification is a judgement call — so this document says exactly what judgement is made, and where it can be wrong.

The budget

targetFps asks how many vsyncs your frame work is allowed to span. The frame period is fixed by VERA and cannot be changed by wanting it to be, so asking for 30 fps does not make frames longer: it means the work may take two of them, and the budget becomes two frames' worth of cycles.

A target faster than the machine scans is a different question — "must this routine fit in half a frame?" — and gets a fractional budget instead. Between the two, a target within 5% of a whole number of vsyncs snaps onto it: "60" on a 59.52 Hz machine plainly means "every frame", not "0.8% faster than the hardware can scan", and reporting the latter would put every saturated program permanently over budget for no reason anyone would accept.

The budget always follows the machine's native clock, never timing_get_speed_khz(). The speed control exists so a routine can be watched at 25 kHz; a budget that shrank to match would report every frame as a catastrophic overrun for a machine that is running perfectly well.

How cycles are classified

Three layers, highest precedence first. Each exists because the one below it has a limit you can hit in practice.

1. Guest markers ($9FBC) — exact, opt-in

The program itself says where its frame work begins and ends. This is the only layer that involves no guessing at all, and the only one that can be right about code the other two cannot see.

Reading $9FBC returns a protocol version, so guest code can feature-detect.

Any marker write puts the module in marker mode, which suppresses the heuristic entirely: a program that says where its work is should not also be guessed at. Marker mode is cleared by a reset, so a program that used markers once does not lose automatic detection for the rest of the session.

A region id first seen here claims a zone slot named region <n>, so marker regions and address zones appear in one breakdown rather than two. A client can name a region before the guest first enters it — RRDC's POST /perf with {"name": "sound", "marker": 7} — so the breakdown reads in the program's own words.

A frame of the guest's own. The module's frame runs vsync to vsync; a game's frame starts wherever it waits for the vertical blank, so its work routinely runs across the module's boundary. A guest that frames its work with $F0 … $F1 keeps its open regions across that boundary — the phase running there keeps its cycles — until its own next $F0 or $F1. (Closing them at the boundary handed the rest of whichever phase was running to no zone at all: Metal Gear's "common" phase read 2.8 scanlines where the guest's own cycle counter said 4.3.)

Unbalanced writes are tolerated rather than rejected — leaving a region that is not open is ignored. A framed guest that forgets a leave mis-attributes the rest of one of its frames, up to its next $F0; a guest that never writes $F0 has a region still open at the frame boundary closed there. Either way it costs one frame, not every frame after it.

The cycles after $F1 are waiting — except an interrupt handler's, which are work in marker mode as in every other (see Interrupts).

2. Zones — exact, no guest changes

Address ranges named in the debugger or over DAP. Cycles executed inside a zone are attributed to it, giving the per-routine breakdown.

A zone flagged idle declares "cycles here are waiting, not work". That is the manual override for a wait loop the heuristic below cannot see.

Zones are looked up through a flat 64K table (PC -> zone), rebuilt only when the zone list changes, so attribution costs one array index per instruction rather than a scan of range checks. Later zones win where two overlap, which makes "draw a tighter zone inside a looser one" behave as expected.

3. Automatic detection — zero setup, heuristic

Two signals:

• WAI — unambiguous, and free to detect.
• A store-free tight loop. A loop is identified by the backward jump that closes it. Once the same backward jump has closed twice with no memory stores and a body spanning no more than 32 bytes, its cycles are credited as waiting.

That catches the two idioms which dominate X16 code:

    lda $9F27       ; poll VERA's ISR for the vsync bit
    and #1
    beq -

    lda vsync_flag  ; poll a flag an IRQ handler sets
    beq -

Why the backward jump, and not PC drift

An earlier version anchored on the PC drifting outside a window. That meant whatever address the walk happened to start at became the anchor — so a compact routine whose whole body fits inside the window was treated as one enormous "loop" that stores, and the tight, store-free poll nested inside it was never seen at all. Anchoring on the branch target instead means each loop is recognised as itself, however tightly the code around it is packed. Pinned by a test.

What automatic detection cannot see

A wait loop that stores, or that calls a subroutine, reads as work. jsr GETIN / cmp #0 / beq - is the common example. "Performs no stores" is the only cheap signal that separates a spin from a computation, and a loop that writes memory has done something.

This is not a bug to be fixed by a cleverer heuristic — it is precisely why layers 1 and 2 exist. Mark such a range as an idle zone, or bracket the real work with markers, and it is counted correctly.

The detector also re-anchors whenever an interrupt is taken, so a wait loop interrupted by its own vsync handler loses up to two passes before it is confirmed again. Two passes of a four-instruction loop is on the order of twenty cycles against a budget of 134,400, so no state is carried to avoid it.

Interrupts

Cycles taken with an interrupt handler open are attributed to irq and are never idle. The split between handler and main-line work usually answers "what is eating my frame?" on its own, and needs no configuration: cpu_irq_depth() already tracks it.

Overruns, and why a saturated program is not automatically one

A frame boundary is detected after the instruction that crossed it, so a frame's accounted cycles can overshoot the nominal period by up to one instruction. Without a tolerance, a program that simply uses the whole machine reads as "over budget by 3 cycles" on the frames where the boundary happens to land late — measurement granularity reported as a defect. The overrun test therefore allows one maximum-length instruction (8 cycles) per frame in the period.

Note that with a whole-frame budget, work can never exceed the cycles that actually elapsed, so utilisation approaches but does not meaningfully pass 100%. Sub-frame budgets (a target faster than the machine scans) are where an overrun figure carries real information: there, work genuinely can exceed what you allowed it.

Cost

Off: one load and one predictable branch per instruction, from an inline guard. Nothing is allocated until profiling is switched on.

On: an add, one array index for the zone lookup, and a handful of branches — the same order as the code_map_record_current() call the debugger already makes on every instruction. The history ring is 3,600 frames (sixty seconds at 60 Hz) at about 56 bytes each.

Percentiles are computed on demand by copying the window and sorting it, so a window nobody asks for costs nothing.

Profiling runs while any owner wants it — the ImGui panel or a DAP client — mirroring the ownership rule the core already applies to breakpoints. Closing the panel does not strand a client with a dead feed, and a client disconnecting does not switch off a panel somebody is reading. The bandwidth accounting below follows the same switch and the same ownership rule, so "profile this machine" is one decision rather than two.

The panel ships open, so -imgui profiles from boot. That is deliberate: a window that starts empty and fills over the next minute cannot answer anything about the frame that made you open it, and the per-instruction cost is in the same class as what the debugger already spends on the code map. A run with no panel and no client still costs only the guard.

The bandwidth side costs a few arithmetic ops per scanline rather than per instruction — 480 lines against 134,400 cycles — and its buffers are two fixed 6 KB arrays, so there is nothing to allocate and nothing that can fail to.

VERA's bandwidth

Everything above accounts for CPU cycles. VERA has its own budget, and a program can have cycles to spare and still tear, drop sprites or run out of room to push pixels — so src/vera_bandwidth.c measures the VRAM bus alongside.

What the bus is

Quoted from the RTL, which for an FPGA is not a description of the hardware but is the hardware. Pinned to X16Community/vera-module tag v47.0.2, the same commit tests/fetch_vera_rtl.py fetches, so every line below can be checked.

Why the headline is a scanline

VERA's peak is 25 MHz × 4 bytes = 100 MB/s, and a real program uses perhaps a fifth of it. "Percent of total bandwidth" would therefore sit near 20% forever and say nothing — the same trap as raw cycles-per-frame always being 100%.

The 800 clocks of one scanline is the window that genuinely runs out, and at full load it exactly does:

layer 0, 8bpp bitmap    160 fetches x 2 = 320 clocks
layer 1, 8bpp bitmap    160 fetches x 2 = 320 clocks
sprites, 4bpp, full line                = 160 clocks
                                          ----
                                           800   = one scanline

So the panel reports peak, p95 and mean clocks per scanline, and names the line the peak fell on.

Fetches per scanline

Two things in that table surprise people:

• A 320-wide bitmap costs the same as a 640-wide one. layer_renderer has no scale input at all; DC_HSCALE is applied by the composer when it reads the line buffer. The renderer just fills to 640 pixels and runs off the end of its own line. Halving the width buys VRAM, not bandwidth.
• Scrolling is not free. The renderer starts at 0 - subtile_hscroll (layer_renderer.v:499-501), so a layer scrolled off a tile boundary draws one tile more than the screen needs — three extra fetches at 8 bpp.

The data port, and VERA FX

$9F23/$9F24 is the one piece of VERA bandwidth a program controls directly, so it is reported on its own: bytes read, bytes written, and what reached VRAM. An 8 MHz CPU can issue roughly 64 accesses a scanline — a 4-cycle sta is 12.5 VERA clocks — which is about 33 KB a frame and a ceiling no program can pass.

FX is where those two numbers come apart. A cache write is one store that moves four bytes, and an affine read costs a second fetch to translate the map. The panel reports the ratio, because "bytes into VRAM per byte the CPU pushed" is the whole reason to use FX.

The debugger's own reads and writes are never charged. writeMemory with a vram: reference reaches VRAM through video_space_write(), around the port entirely; a write to the CPU address $9F23 raises video_set_debug_write() so the accounting declines it; and the read path is already guarded by debugOn. If opening a memory view moved the number, the number would be worthless.

Where the model is wrong

Stated plainly, because a bandwidth figure nobody can calibrate is worse than none.

• Fetches are modelled from the layer registers, not observed. The emulator's renderer is a pixel loop — 640 columns reading a byte at a time, re-reading the same byte in 320-wide modes — and never fetches 32 bits at once the way the hardware does. Counting those calls would measure the emulator's inner loop rather than VERA's bus. The cost is that a bug in the emulator's renderer will not show up here.
• Clocks are a lower bound; accesses are exact. Two clocks per access is the uncontended cost. Under contention a lower-priority client holds its strobe and waits, burning more. Trust the access counts; read the clock totals as "at least this bad".
• The scroll tile is an assumption. Which tile is "every other" for the map fetch depends on the scrolled tile counter's parity, so the count can be one out at the margin.
• A line is fetched during the line before it. The layer line buffer is double-buffered (top.v active_line_buf_r, composer.v). Fetches are reported against the line they paint, which is where a developer looks.
• FX is covered where the emulator implements it — the four-byte cache write and the affine prefetch — not as a whole model of addr_data.v.

Sprites, and the contention this makes visible

Sprite render time is modelled separately and reported in the VERA panel's Multiplex → Render time view. The Bandwidth section links to it rather than drawing it twice.

The two now meet at a real number — but only after a conversion, because they are measured in different clocks.

SPRITE_TRACE_LINE_BUDGET (798) is wall clock: render_time_r increments every clock (sprite_renderer.v:43-56), including the STATE_RENDER clocks when the renderer is painting and holding no strobe at all. Everything in the Bandwidth section is bus occupancy. A sprite spends 2 clocks fetching a word and then 8 rendering it at 4 bpp, so its render time runs about five times its bus time — and a full 4 bpp sprite line is roughly 158 bus clocks, nowhere near 798.

Subtracting one from the other therefore overstates sprite pressure fivefold and warns about lines that comfortably fit, which is worse than not reporting it at all. vera_bandwidth_sprite_bus_clocks() does the conversion, and the per-line tooltip shows both figures with their units named. Every clock in the x16/perfStats bandwidth object is bus occupancy, and it says so in a clockUnits field so a client cannot make the same mistake more quietly.

Sprites are also last on the bus. What layers and the CPU leave is what they get, so the tooltip shows the headroom after both and says when a line's sprite fetches exceed it. That is the known gap made expressible: the sprite model charges STATE_WAIT_FETCH one clock where the bus takes two, so on a line the layers have filled it flatters itself. Making the sprite model itself contention-aware would mean simulating the arbiter cycle by cycle, and is not done.

Where this is implemented