// Checks for guest performance budget accounting (src/perf_budget.c).

//

// The module's whole job is to decide which cycles were WORK and which were

// WAITING, so most of what is worth testing is the classification: that a spin

// loop is recognised, that something which merely looks like one is not, and

// that the three layers override each other in the documented order. The

// statistics on top of that are ordinary arithmetic, but they are the numbers a

// developer would act on, so the percentile and overrun maths is pinned too.

//

// perf_budget.c reaches for no emulator state, so this drives it directly: no

// CPU, no memory, no video, no SDL.

#include "perf_budget.h"

#include "support/harness.h"

#include <stdio.h>

#include <string.h>

// The machine this file assumes throughout: 8 MHz, VGA. Stated once here so a

// change of default in the module cannot quietly rewrite what the checks mean.

#define KHZ              8000

#define CYCLES_PER_FRAME 134400

#define SCANLINES        525

static void

configure(void)

{

	perf_budget_zone_clear();

	perf_budget_set_enabled(false);

	perf_budget_set_capacity(PERF_DEFAULT_CAPACITY);

	perf_budget_configure(KHZ, CYCLES_PER_FRAME, SCANLINES);

	perf_budget_set_target_fps(60.0f);

	perf_budget_set_idle_mode(PERF_IDLE_AUTO);

	perf_budget_set_enabled(true);

	perf_budget_reset();

}

// Run `count` instructions of straight-line work, each costing `clocks`.

static void

run_work(uint32_t clocks, int count)

{

	for (int i = 0; i < count; i++)

		perf_budget_step(clocks, (uint16_t)(0x2000 + i * 3), 0, false, 0);

}

// Run `passes` iterations of a three-instruction loop at `base` that stores

// nothing -- the shape of `lda $9F27 / and #1 / beq -`.

static void

run_spin(uint16_t base, int passes)

{

	for (int p = 0; p < passes; p++) {

		perf_budget_step(4, base, 0, false, 0);

		perf_budget_step(2, (uint16_t)(base + 3), 0, false, 0);

		perf_budget_step(3, (uint16_t)(base + 5), 0, false, 0);

	}

}

int

main(void)

{

	// ── Derived machine figures ─────────────────────────────────────────────

	{

		configure();

		check_eq(perf_budget_cycles_per_frame(), CYCLES_PER_FRAME,

		         "a VGA frame at 8 MHz is 134,400 cycles");

		check_eq(perf_budget_cycles_per_scanline(), 256,

		         "which is 256 cycles per scanline over 525 lines");

		check_eq(perf_budget_budget_cycles(), CYCLES_PER_FRAME,

		         "and at 60 fps the budget is one frame's worth");

		check_eq((uint32_t)perf_budget_frames_per_budget(), 1,

		         "spanning a single vsync");

		const float hz = perf_budget_vsync_hz();

		check(hz > 59.0f && hz < 60.5f, "vsync is derived at ~59.5 Hz");

	}

	// ── A lower target fps buys more frames, not longer ones ────────────────

	{

		configure();

		perf_budget_set_target_fps(30.0f);

		check_eq((uint32_t)perf_budget_frames_per_budget(), 2,

		         "30 fps lets the work span two vsyncs");

		check_eq(perf_budget_budget_cycles(), CYCLES_PER_FRAME * 2,

		         "so the budget is two frames' cycles");

		perf_budget_set_target_fps(20.0f);

		check_eq((uint32_t)perf_budget_frames_per_budget(), 3, "20 fps spans three");

		perf_budget_set_target_fps(60.0f);

		check_eq((uint32_t)perf_budget_frames_per_budget(), 1, "and 60 fps is back to one");

	}

	// ── Nothing is idle until something says so ─────────────────────────────

	{

		configure();

		run_work(4, 100);

		perf_budget_frame_end(0);

		perf_frame_t f;

		check(perf_budget_last_frame(&f), "a completed frame is retained");

		check_eq(f.total, 400, "every cycle stepped is counted");

		check_eq(f.idle, 0, "straight-line code is never idle");

		check_eq(perf_frame_work(&f), 400, "so all of it is work");

		check_eq(f.instructions, 100, "and the instructions are counted");

	}

	// ── WAI is idle, unambiguously ──────────────────────────────────────────

	{

		configure();

		run_work(4, 10);                             //  40 work

		for (int i = 0; i < 10; i++)                 // 100 idle

			perf_budget_step(10, 0x3000, 0, true, 0);

		perf_budget_frame_end(0);

		perf_frame_t f;

		perf_budget_last_frame(&f);

		check_eq(f.idle, 100, "WAI cycles are idle");

		check_eq(perf_frame_work(&f), 40, "and the rest is work");

	}

	// ── A store-free tight loop is recognised as waiting ────────────────────

	{

		configure();

		run_work(4, 10); // 40 work

		run_spin(0x4000, 20);

		perf_budget_frame_end(0);

		perf_frame_t f;

		perf_budget_last_frame(&f);

		// Each pass is 9 cycles. The detector re-anchors on the loop head and

		// only credits confirmed passes, so a couple go to work; the point is

		// that the great majority is recognised.

		check(f.idle >= 9 * 16, "a store-free spin loop is mostly idle");

		check(perf_frame_work(&f) < 40 + 9 * 4,

		      "and only the run-up is charged as work");

	}

	// ── A loop that stores is computing, not waiting ────────────────────────

	{

		configure();

		for (int p = 0; p < 20; p++) {

			perf_budget_step(4, 0x4000, 0, false, 0);

			perf_budget_step(2, 0x4003, 0, false, 0);

			perf_budget_note_store(); // the difference from the case above

			perf_budget_step(3, 0x4005, 0, false, 0);

		}

		perf_budget_frame_end(0);

		perf_frame_t f;

		perf_budget_last_frame(&f);

		check_eq(f.idle, 0, "a loop with a side effect is never idle");

		check_eq(perf_frame_work(&f), 9 * 20, "all of it counts as work");

	}

	// ── A loop wider than the span is not a spin ────────────────────────────

	{

		configure();

		for (int p = 0; p < 20; p++) {

			perf_budget_step(4, 0x5000, 0, false, 0);

			perf_budget_step(2, 0x5000 + PERF_SPIN_SPAN + 8, 0, false, 0);

		}

		perf_budget_frame_end(0);

		perf_frame_t f;

		perf_budget_last_frame(&f);

		check_eq(f.idle, 0, "a loop spanning more than PERF_SPIN_SPAN is not a spin");

	}

	// ── Interrupt cycles are counted, and are never idle ────────────────────

	{

		configure();

		run_spin(0x4000, 20);

		for (int i = 0; i < 10; i++)

			perf_budget_step(5, (uint16_t)(0x9000 + i * 2), 0, false, 1);

		perf_budget_frame_end(0);

		perf_frame_t f;

		perf_budget_last_frame(&f);

		check_eq(f.irq, 50, "cycles at interrupt depth are attributed to the handler");

		check(f.idle > 0, "the spin before it is still recognised");

		check(f.idle <= f.total - 50, "but the handler's cycles are not idle");

	}

	// ── An idle zone overrides the heuristic ────────────────────────────────

	{

		configure();

		const int z = perf_budget_zone_add("wait", 0x6000, 0x6100, -1, true);

		check(z >= 0, "an idle zone can be defined");

		// A loop that stores, which the heuristic would call work.

		for (int p = 0; p < 10; p++) {

			perf_budget_step(4, 0x6000, 0, false, 0);

			perf_budget_note_store();

			perf_budget_step(3, 0x6002, 0, false, 0);

		}

		perf_budget_frame_end(0);

		perf_frame_t f;

		perf_budget_last_frame(&f);

		check_eq(f.idle, 70, "an idle zone declares its cycles waiting regardless");

		check_eq(perf_frame_work(&f), 0, "leaving no work at all");

	}

	// ── Zones attribute cycles, and respect their bank ──────────────────────

	{

		configure();

		const int z0 = perf_budget_zone_add("sprites", 0x2000, 0x2100, -1, false);

		const int z1 = perf_budget_zone_add("banked", 0xA000, 0xA100, 3, false);

		check(z0 == 0 && z1 == 1, "zones take the first free slots");

		run_work(4, 4);                                    // $2000,$2003,$2006,$2009

		perf_budget_step(7, 0xA000, 3, false, 0);          // matching bank

		perf_budget_step(9, 0xA000, 5, false, 0);          // wrong bank

		perf_budget_frame_end(0);

		perf_frame_t f;

		perf_budget_last_frame(&f);

		check_eq(f.zone[0], 16, "a zone collects the cycles inside it");

		check_eq(f.zone[1], 7, "a banked zone collects only its own bank");

		check_eq(f.total, 32, "while the frame total counts everything");

	}

	// ── Removing a zone stops attribution ───────────────────────────────────

	{

		configure();

		perf_budget_zone_add("gone", 0x2000, 0x2100, -1, false);

		check(perf_budget_zone_remove(0), "a zone can be removed");

		check(!perf_budget_zone_get(0, NULL), "and is then unknown");

		run_work(4, 4);

		perf_budget_frame_end(0);

		perf_frame_t f;

		perf_budget_last_frame(&f);

		check_eq(f.zone[0], 0, "cycles are no longer attributed to it");

	}

	// ── Markers: the guest says where its work is ───────────────────────────

	{

		configure();

		check_eq(perf_budget_marker_read(), PERF_MARKER_PROTOCOL,

		         "the marker register reads back a protocol version");

		perf_budget_marker_write(0xF0); // work begins

		run_work(4, 10);                // 40 work

		perf_budget_marker_write(0xF1); // work ends

		run_work(4, 10);                // 40 idle -- and it stores, and it is

		perf_budget_note_store();       // straight-line, so only the marker

		run_work(4, 10);                // could possibly call this waiting

		perf_budget_frame_end(0);

		perf_frame_t f;

		perf_budget_last_frame(&f);

		check_eq(perf_frame_work(&f), 40, "only the marked span is work");

		check_eq(f.idle, 80, "everything after the end marker is idle");

	}

	// ── Marker regions claim zone slots, and nest ───────────────────────────

	{

		configure();

		perf_budget_marker_write(0xF0);

		perf_budget_marker_write(0x01); // enter region 1

		run_work(4, 5);                 // 20 -> region 1

		perf_budget_marker_write(0x02); // enter region 2, nested

		run_work(4, 5);                 // 20 -> region 2 (innermost wins)

		perf_budget_marker_write(0x82); // leave region 2

		run_work(4, 5);                 // 20 -> region 1 again

		perf_budget_marker_write(0x81); // leave region 1

		run_work(4, 5);                 // 20 -> unattributed

		perf_budget_frame_end(0);

		perf_frame_t f;

		perf_budget_last_frame(&f);

		check_eq(f.zone[0], 40, "an outer region collects its own cycles");

		check_eq(f.zone[1], 20, "the innermost open region wins while nested");

		perf_zone_t z;

		check(perf_budget_zone_get(0, &z), "a marker region claims a zone slot");

		check(z.is_marker && z.marker_id == 1, "tagged with the region it stands for");

		check(strcmp(z.name, "region 1") == 0, "and named after it");

	}

	// ── A framed guest's work may run across the emulator's frame boundary ──

	{

		// A game's frame starts where it waits for the vertical blank, which

		// is not where this module's frame ends. Its phases run straight

		// across the boundary, and the one running there keeps its cycles.

		configure();

		perf_budget_marker_write(0xF0);

		perf_budget_marker_write(0x01); // phase 1

		run_work(4, 10);

		perf_budget_marker_write(0x00);

		perf_budget_marker_write(0x02); // phase 2, running at the boundary

		run_work(4, 10);

		perf_budget_frame_end(0);

		run_work(4, 10);                // phase 2, after it

		perf_budget_marker_write(0x00);

		perf_budget_marker_write(0xF1);

		run_work(4, 10);                // the wait

		perf_budget_frame_end(0);

		perf_frame_t f;

		perf_budget_frame_at(1, &f);

		check_eq(f.zone[0], 40, "phase 1 before the boundary");

		check_eq(f.zone[1], 40, "phase 2's cycles before the boundary");

		perf_budget_last_frame(&f);

		check_eq(f.zone[1], 40, "and phase 2's after it, carried across");

		check_eq(f.idle, 40, "the wait after $F1 idle");

	}

	// ── An interrupt during the wait is work ────────────────────────────────

	{

		// After $F1 the guest is waiting; the IRQ handler that runs in that

		// wait is not, and main (work less irq) must not come out short of it.

		configure();

		perf_budget_marker_write(0xF0);

		run_work(4, 10);

		perf_budget_marker_write(0xF1);

		for (int i = 0; i < 10; i++) perf_budget_step(4, 0x2000, 0, false, 0); // waiting

		for (int i = 0; i < 5; i++)  perf_budget_step(6, 0xE000, 0, false, 1); // the IRQ

		perf_budget_frame_end(0);

		perf_frame_t f;

		perf_budget_last_frame(&f);

		check_eq(f.irq, 30, "the handler's cycles are IRQ");

		check_eq(f.idle, 40, "only the waiting is idle");

		check_eq(perf_frame_work(&f), 70, "the handler counted as work");

	}

	// ── A marker region can be named before the guest enters it ─────────────

	{

		configure();

		const int zi = perf_budget_zone_add_marker("sound", 7);

		check(zi >= 0, "a named marker region claims a zone slot");

		perf_zone_t z;

		check(perf_budget_zone_get(zi, &z) && z.is_marker && z.marker_id == 7 &&

		      !strcmp(z.name, "sound"), "under its name, standing for region 7");

		perf_budget_marker_write(0xF0);

		perf_budget_marker_write(0x07);

		run_work(4, 5);

		perf_budget_marker_write(0xF1);

		perf_budget_frame_end(0);

		perf_frame_t f;

		perf_budget_last_frame(&f);

		check_eq(f.zone[zi], 20, "and the guest's region 7 lands in it");

		check(perf_budget_zone_add_marker("x", 0) < 0 && perf_budget_zone_add_marker("x", 0x40) < 0,

		      "ids outside $01-$3F are refused");

	}

	// ── Unbalanced markers cost one frame, not every frame ──────────────────

	{

		// A guest that does not frame its work ($F0 ... $F1): the boundary is

		// the only thing that can close a region it forgot to leave.

		configure();

		perf_budget_marker_write(0x05); // entered and never left

		run_work(4, 10);

		perf_budget_frame_end(0);

		run_work(4, 10); // the next frame must not still be inside region 5

		perf_budget_frame_end(0);

		perf_frame_t f;

		perf_budget_last_frame(&f);

		check_eq(f.zone[0], 0, "a region left open is closed by the frame boundary");

		// A guest that does frame its work closes it itself, at its next $F0:

		// the missing leave costs one of ITS frames.

		configure();

		perf_budget_marker_write(0xF0);

		perf_budget_marker_write(0x05); // entered and never left

		run_work(4, 10);

		perf_budget_frame_end(0);

		perf_budget_marker_write(0xF0); // the guest's next frame

		run_work(4, 10);

		perf_budget_frame_end(0);

		perf_budget_last_frame(&f);

		check_eq(f.zone[0], 0, "a framed guest's open region ends at its next $F0");

		// Leaving a region that was never entered is ignored rather than

		// corrupting the stack.

		perf_budget_marker_write(0x93);

		run_work(4, 5);

		perf_budget_frame_end(0);

		perf_budget_last_frame(&f);

		check_eq(f.total, 20, "an unmatched leave is ignored");

	}

	// ── Marker mode does not outlive a reset ────────────────────────────────

	{

		// Marker mode suppresses the heuristic. If a reset did not clear it, a

		// program that wrote one marker would disable automatic detection for

		// the rest of the session, with no way back.

		configure();

		perf_budget_marker_write(0xF0);

		run_work(4, 5);

		perf_budget_frame_end(0);

		perf_budget_reset();

		run_spin(0x4000, 20);

		perf_budget_frame_end(0);

		perf_frame_t f;

		perf_budget_last_frame(&f);

		check(f.idle > 0, "a reset gives automatic detection back after markers");

		// And a guest still driving markers re-asserts the mode immediately.

		perf_budget_reset();

		perf_budget_marker_write(0xF1); // work has ended: all of this is idle

		run_work(4, 10);

		perf_budget_frame_end(0);

		perf_budget_last_frame(&f);

		check_eq(f.idle, 40, "while the next marker write takes control again");

	}

	// ── Idle modes ──────────────────────────────────────────────────────────

	{

		configure();

		perf_budget_set_idle_mode(PERF_IDLE_NONE);

		run_spin(0x4000, 20);

		for (int i = 0; i < 5; i++)

			perf_budget_step(10, 0x3000, 0, true, 0);

		perf_budget_frame_end(0);

		perf_frame_t f;

		perf_budget_last_frame(&f);

		check_eq(f.idle, 0, "PERF_IDLE_NONE classifies nothing as waiting");

		configure();

		perf_budget_set_idle_mode(PERF_IDLE_MARKERS);

		run_spin(0x4000, 20);

		perf_budget_frame_end(0);

		perf_budget_last_frame(&f);

		check_eq(f.idle, 0, "PERF_IDLE_MARKERS ignores the spin heuristic");

	}

	// ── Overruns, against the budget ────────────────────────────────────────

	{

		configure();

		// Three frames under budget, two over.

		const uint32_t under = CYCLES_PER_FRAME / 2;

		const uint32_t over  = CYCLES_PER_FRAME + 1000;

		const uint32_t counts[5] = {under, over, under, over, under};

		for (int i = 0; i < 5; i++) {

			perf_budget_step(counts[i], (uint16_t)(0x2000 + i), 0, false, 0);

			perf_budget_frame_end(1000);

		}

		perf_window_t w;

		check(perf_budget_window(0.0f, &w), "the whole ring is a valid window");

		check_eq((uint32_t)w.frames, 5, "holding every frame recorded");

		check_eq((uint32_t)w.overruns, 2, "two of which exceeded the budget");

		check_eq(w.worst_overrun, 1000, "by 1000 cycles at worst");

		check_eq(w.work.max, over, "the worst frame is the maximum");

		check_eq(w.work.min, under, "and the best the minimum");

		check(w.max_utilization > 100.0f, "so peak utilisation is over budget");

		check(w.mean_utilization < 100.0f, "while the mean is under it");

	}

	// ── The overrun drain, which the DAP event rides on ─────────────────────

	{

		configure();

		perf_overrun_report_t r;

		check(!perf_budget_drain_overruns(&r), "a clean run reports nothing");

		perf_budget_step(CYCLES_PER_FRAME + 500, 0x2000, 0, false, 0);

		perf_budget_frame_end(0);

		perf_budget_step(CYCLES_PER_FRAME + 2500, 0x2000, 0, false, 0);

		perf_budget_frame_end(0);

		check(perf_budget_drain_overruns(&r), "overruns are reported once seen");