# 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](#veras-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.

| Target | Budget period | Budget at 8 MHz |

| --- | --- | --- |

| 60 fps | 1 vsync | 134,400 cycles |

| 30 fps | 2 vsyncs | 268,800 cycles |

| 20 fps | 3 vsyncs | 403,200 cycles |

| 120 fps | 1 vsync | ~66,600 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.

| Write | Meaning |

| --- | --- |

| `$01`–`$3F` | enter region *n* (nests) |

| `$80 \| n` | leave region *n* |

| `$00` | leave the innermost region |

| `$F0` | frame work begins |

| `$F1` | frame work ends — the rest of the frame is waiting |

| `$FE` | reset all statistics |

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:

```asm

    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.

| Fact | Source |

| --- | --- |

| A scanline is 800 clocks (640 + 16 + 96 + 48), 525 lines a frame | `video_vga.v:27-37` |

| VRAM is 32 bits wide, so **an access is four bytes** | `main_ram.v:7-10` |

| An access costs **two clocks**: strobe, then ack | `layer_renderer.v:250-271` |

| One bus, **fixed priority: CPU > layer 0 > layer 1 > sprites** | `vram_if.v:142-157`, wired at `top.v:680-713` |

| A tile map word holds **two** 16-bit entries, so a map fetch every two tiles | `layer_renderer.v:113`, `:305` |

| The layer renderer always fills **640 pixels**, then stops | `layer_renderer.v:488` |

### 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

| Tile mode | 8px tiles | 16px tiles |

| --- | --- | --- |

| 1 bpp | 120 | 60 |

| 2 bpp | 120 | 60 |

| 4 bpp | 120 | 100 |

| 8 bpp | 200 | 180 |

| Bitmap mode | 1 bpp | 2 bpp | 4 bpp | 8 bpp |

| --- | --- | --- | --- | --- |

| Fetches | 20 | 40 | 80 | 160 |

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

| File | Role |

| --- | --- |

| `src/perf_budget.{c,h}` | All the cycle accounting. Reaches for no emulator state — everything arrives as a function argument — so it is unit-tested with no CPU, no memory, no video and no SDL. |

| `src/vera_bandwidth.{c,h}` | The VRAM bus model, dependency-free for the same reason. |

| `src/main.c` | Per-instruction and frame-boundary hooks. |

| `src/memory.c` | The store signal the spin detector needs, and the `$9FBC` register. |

| `src/video.c` | Per-scanline layer modes, data-port traffic, and the VERA frame boundary. |

| `src/debug_ui/panels/perf_panel.cpp` | The Performance panel, CPU and bandwidth in one place. |

| `src/perf_json.{c,h}` | The measurements as JSON, one builder each for the two remote surfaces below. |

| `src/debug_server.c` | `x16/perfStats`, `x16/perfConfig`, and the `x16/perfBudgetOverrun` event. |

| `src/control_backend.c` | The RRDC control port's `GET`/`POST /perf` (contract 0.6), beside its memory, stepping and input. |

| `tests/test_perf_budget.c` | The classification and statistics, driven directly. |

| `tests/test_vera_bandwidth.c` | The fetch model, checked against the RTL's decode tables. |

| `testbench/test_dap.py` | Both DAP surfaces against a real running machine. |