// *******************************************************************************************

// *******************************************************************************************

//

//		File:		debugger.c

//		Date:		5th September 2019

//		Purpose:	Debugger code

//		Author:		Paul Robson ([email protected])

//

// *******************************************************************************************

// *******************************************************************************************

#include <stdlib.h>

#include <stdio.h>

#include <string.h>

#include <inttypes.h>

#include <stdbool.h>

#include <SDL.h>

#include "glue.h"

#include "timing.h"

#include "disasm.h"

#include "memory.h"

#include "video.h"

#include "cpu/fake6502.h"

#include "debugger.h"

#include "debug_server.h"

#include "dbg_info.h"

#include "rendertext.h"

static void DEBUGHandleKeyEvent(SDL_Keycode key,int isShift);

static void DEBUGNumber(int x,int y,int n,int w, SDL_Color colour);

static void DEBUGNumberDec(int x, int y, int n, int w, SDL_Color colour);

static void DEBUGAddress(int x, int y, int x16Bank, int addr, uint8_t bank, SDL_Color colour);

static void DEBUGVAddress(int x, int y, int addr, SDL_Color colour);

static void DEBUGRenderData(int y,uint32_t data);

static int DEBUGRenderZeroPageRegisters(int y);

static void DEBUGRenderVERAState(int y);

static int DEBUGRenderRegisters(void);

static void DEBUGRenderVRAM(int y, int data);

static void DEBUGRenderCode(int lines,int initialPC);

static void DEBUGRenderStack(int bytesCount);

static void DEBUGRenderCmdLine(int x, int width, int height);

static bool DEBUGEditCmdLine(SDL_Keycode key);

static void DEBUGBuildCmdLine(char *text);

static void DEBUGExecCmd();

// *******************************************************************************************

//

//		This is the minimum-interference flag. It's designed so that when

//		its non-zero DEBUGRenderDisplay() is called.

//

//			if (showDebugOnRender != 0) {

//				DEBUGRenderDisplay(SCREEN_WIDTH,SCREEN_HEIGHT,renderer);

//				SDL_RenderPresent(renderer);

//				return true;

//			}

//

//		before the SDL_RenderPresent call in video_update() in video.c

//

//		This controls what is happening. It is at the top of the main loop in main.c

//

//			if (isDebuggerEnabled != 0) {

//				int dbgCmd = DEBUGGetCurrentStatus();

//				if (dbgCmd > 0) continue;

//				if (dbgCmd < 0) break;

//			}

//

//		Both video.c and main.c require debugger.h to be included.

//

//		isDebuggerEnabled should be a flag set as a command line switch - without it

//		it will run unchanged. It should not be necessary to test the render code

//		because showDebugOnRender is statically initialised to zero and will only

//		change if DEBUGGetCurrentStatus() is called.

//

// *******************************************************************************************

//

//				0-9A-F sets the program address, with shift sets the data address.

//

#define DBGKEY_HOME     SDLK_F1                         // F1 is "Goto PC"

#define DBGKEY_RESET    SDLK_F2                         // F2 resets the 6502

#define DBGKEY_RUN      SDLK_F5                         // F5 is run.

#define DBGKEY_SETBRK   SDLK_F9                         // F9 sets breakpoint

#define DBGKEY_STEP     SDLK_F11                        // F11 is step into.

#define DBGKEY_STEPOVER SDLK_F10                        // F10 is step over.

#define DBGKEY_BANK_NEXT	SDLK_KP_PLUS

#define DBGKEY_BANK_PREV	SDLK_KP_MINUS

#define DBGSCANKEY_BRK  SDL_SCANCODE_F12                // F12 is break into running code.

#define DBGSCANKEY_SHOW SDL_SCANCODE_TAB                // Show screen key.

                                                        // *** MUST BE SCAN CODES ***

#define DBGMAX_ZERO_PAGE_REGISTERS 16

#define DDUMP_RAM	0

#define DDUMP_VERA	1

enum DBG_CMD { CMD_DUMP_MEM='m', CMD_DUMP_VERA='v', CMD_DISASM='d', CMD_SET_BANK='b', CMD_SET_REGISTER='r', CMD_FILL_MEMORY='f' };

// RGB colours

const SDL_Color col_bkgnd= {0, 0, 0, 255};

const SDL_Color col_label= {0, 255, 0, 255};

const SDL_Color col_data= {0, 255, 255, 255};

const SDL_Color col_highlight= {255, 255, 0, 255};

const SDL_Color col_cmdLine= {255, 255, 255, 255};

const SDL_Color col_directpage= {192, 224, 255, 255};

const SDL_Color col_vram_tilemap = {0, 255, 255, 255};

const SDL_Color col_vram_tiledata = {0, 255, 0, 255};

const SDL_Color col_vram_special  = {255, 92, 92, 255};

const SDL_Color col_vram_other  = {128, 128, 128, 255};

int showDebugOnRender = 0;                            // Used to trigger rendering in video.c

int showFullDisplay = 0;                              // If non-zero show the whole thing.

int currentPC = -1;                                   // Current disassembly PC value (16-bit).

uint8_t currentPCBank = 0;                            // Current disassembly PC bank (like regs.k) value.

int currentData = 0;                                  // Current data display address (RAM or VRAM).

int currentPCX16Bank = -1;                            // Current disassembly X16 RAM/ROM bank, -1 unless $A000-$FFFF, .K = 0

int currentX16Bank = -1;                              // Current data display (memory dump) X16 RAM/ROM bank

int currentMode = DMODE_RUN;                          // Start running.

uint32_t debugCPUClocks = 0;

// Stepping by source line. Defined with the rest of the source-step machinery

// further down; declared here because DEBUGGetCurrentStatus(), which retires

// each instruction step, has to ask whether one is still in progress.

static bool srcStepActive;

static bool DEBUGSourceStepContinue(void);

int dumpmode          = DDUMP_RAM;

// Where we resumed from, so the breakpoint we are parked on does not fire again

// the instant we continue. Cleared once the CPU has actually moved on.

//

// Pressing F5 never needed this: the key is read inside DEBUGGetCurrentStatus,

// after the breakpoint test, so by the next call the CPU has already stepped

// off the address. Anything driving execution from outside -- which is the

// point of the execution-control functions -- changes the mode between calls

// instead, and would otherwise re-trigger the same breakpoint forever without

// ever advancing.

//

// The clock is part of the test, not just the address: `JMP *` at a breakpoint

// never changes the PC, and an address-only guard would then suppress that

// breakpoint permanently. Conversely the clock alone is not enough, in two

// ways: handle_ieee_intercept() can skip an iteration without executing

// anything, and -- the sharp one -- step6502() ticks the clock and returns

// immediately while the CPU is parked in WAI. A breakpoint on the instruction

// after a WAI, which is the idiomatic frame-sync placement, would otherwise

// clear the guard every poll and buy one emulated cycle per resume.

static int      resumeSkipPC    = -1;

static uint8_t  resumeSkipBank  = 0;

static uint32_t resumeSkipClock = 0;

// A watchpoint fired mid-instruction and the reported location still has to be

// taken, once the instruction that did the write has finished. See

// DEBUGBreakOnWatchpoint().

static bool watchpointStopPending = false;

static void DEBUGClearStepBreakPoint(void);

static void DEBUGArmResumeSkip(void) {

	resumeSkipPC    = regs.pc;

	resumeSkipBank  = regs.k;

	resumeSkipClock = clockticks6502;

}

struct breakpoint stepBreakPoint = { -1, 0, -1, 0, true };     // Single step break.

// Who asked for the pending step-over/step-out.

//

// The step target deliberately lives outside the shared breakpoint table, so it

// needs its own record of who wanted it -- and that record belongs next to the

// state it describes, rather than in a flag kept by whichever front end happened

// to start the step. DEBUG_OWNER_COUNT means nothing is pending.

static debug_owner_t stepOwner = DEBUG_OWNER_COUNT;

// Interrupt following. followInterrupts makes a step that is interrupted stop

// at the handler instead of running through it; breakOnInterrupt stops on every

// interrupt entry, even while free-running. Both default off so normal stepping

// behaves exactly as before.

static bool followInterrupts = false;

static bool breakOnInterrupt = false;

void DEBUGSetFollowInterrupts(bool on) { followInterrupts = on; }

bool DEBUGGetFollowInterrupts(void)    { return followInterrupts; }

void DEBUGSetBreakOnInterrupt(bool on) { breakOnInterrupt = on; }

bool DEBUGGetBreakOnInterrupt(void)    { return breakOnInterrupt; }

// Why execution last stopped. A UI needs this to tell a step apart from an

// arrival somewhere new: after a step the view should stay put, while a

// breakpoint or a pause has to re-centre or the highlight lands off-screen.

// Recorded here rather than in a debug client so it is correct whether or not

// one is attached. Only ever set to a string literal, so there is nothing to

// free and no buffer to overrun.

static const char *lastStopReason = "";

void

DEBUGSetStopReason(const char *reason)

{

	lastStopReason = reason ? reason : "";

}

// Record the reason AND tell a DAP client execution stopped.

//

// Split from the plain setter deliberately. Some sites run on every poll while

// already halted -- the F12 key test reads the physical key state, so it fires

// ~60-100 times a second while the key is held -- and others set a default that

// a more specific caller then overrides. Those must only store. Announcing is

// edge-triggered: exactly once per RUN->STOP transition, at the site that knows

// it is a transition. Folding the notify into the setter turned per-poll string

// assignments into per-poll socket writes.

//

// Compiles to a bare store in a build without the DAP server.

void

DEBUGAnnounceStop(const char *reason)

{

	DEBUGSetStopReason(reason);

	debug_server_notify_stopped(lastStopReason);

}

const char *

DEBUGGetStopReason(void)

{

	return lastStopReason;

}

char cmdLine[64]= "";                                 // command line buffer

int currentPosInLine= 0;                              // cursor position in the buffer (NOT USED _YET_)

int currentLineLen= 0;                                // command line buffer length

int    oldRegisters[DBGMAX_ZERO_PAGE_REGISTERS];      // Old ZP Register values, for change detection

char * oldRegChange[DBGMAX_ZERO_PAGE_REGISTERS];      // Change notification flags for output

int    oldRegisterTicks = 0;                          // Last PC when change notification was run

//

//		This flag controls

//

SDL_Renderer *dbgRenderer;                            // Renderer passed in.

// Unbanked, the RAM window, or the ROM window. A bank number selected for one

// of these means nothing in the others.

static int bank_window_of(int addr) {

	if (addr < 0xA000)

		return 0;

	return addr < 0xC000 ? 1 : 2;

}

// Which RAM/ROM window the PC is in, or -1 where a bank means nothing there.

// Delegates to debug_core so the rule that *produces* a selector is the same one

// the matcher applies. The copy that used to live here required the program bank

// to be zero unconditionally, which disagrees on gen1 with -c816: read6502

// forces the bank to zero there, so the window registers do apply.

static inline int getCurrentBank(int pc, uint8_t bank) {

	return debug_current_x16_bank(pc, bank);

}

// *******************************************************************************************

//

//      	This determines if we have hit a breakpoint, both in pc and bank

//

// *******************************************************************************************

static inline bool hitBreakpoint(int pc, uint8_t bank, struct breakpoint bp) {

	// Uses the same bank rule as every other matcher, so this field cannot mean

	// "any bank" in one place and "not banked" in another.

	return pc == bp.pc && bank == bp.bank

	       && debug_bank_selector_matches(bp.x16Bank, pc, bank);

}

// *******************************************************************************************

//

//			This is used to determine who is in control. If it returns zero then

//			everything runs normally till the next call.

//			If it returns +ve, then it will update the video, and loop round.

//			If it returns -ve, then exit.

//

// *******************************************************************************************

int  DEBUGGetCurrentStatus(void) {

	SDL_Event event;

	if (currentPC < 0) currentPC = regs.pc;                                      // Initialise current PC displayed.

	// Interrupt following. cpu_irq_take_entered_flag() is true exactly once per

	// interrupt entry, and at this point the PC is already the handler's first

	// instruction. "Break on interrupt" stops whenever one is taken; "follow

	// interrupts" only stops if we were stepping, so that an interrupt landing

	// in the middle of a step-over/step-out becomes visible instead of being

	// silently run through.

	//

	// The flag is consumed unconditionally -- reading it is what clears it -- so

	// that a stale entry cannot fire a stop later, after the feature is enabled.

	{

		const bool entered = cpu_irq_take_entered_flag();

		const bool wasStepping = (currentMode == DMODE_STEP) || (stepBreakPoint.pc >= 0);

		if (entered && (breakOnInterrupt

		                || (followInterrupts && wasStepping && currentMode != DMODE_STOP))) {

			currentPC = regs.pc;

			currentPCBank = regs.k;

			currentPCX16Bank = getCurrentBank(regs.pc, regs.k);

			currentMode = DMODE_STOP;

			stepBreakPoint.pc = -1;                             // the pending step target is now unreachable

			stepBreakPoint.bank = 0;

			stepBreakPoint.x16Bank = -1;

			srcStepActive = false;   // and any step-by-line it was driving

			DEBUGAnnounceStop("interrupt");

		}

	}

	// A watchpoint stopped us from inside a store. The instruction that did the

	// write has now finished, so this is the first point at which regs.pc says

	// where the CPU actually ended up.

	if (watchpointStopPending) {

		watchpointStopPending = false;

		currentPC = regs.pc;

		currentPCBank = regs.k;

		currentPCX16Bank = getCurrentBank(regs.pc, regs.k);

		// Reported here rather than from the store itself: only now does

		// regs.pc name the instruction after the write.

		DEBUGAnnounceStop("data breakpoint");

	}

	if (currentMode == DMODE_STEP) {                                // Single step before

		if (currentPC != regs.pc || currentPCBank != regs.k || currentPCX16Bank != getCurrentBank(regs.pc, regs.k)) { // Ensure that the PC moved

			currentPC = regs.pc;                                    // Update current PC

			currentPCBank = regs.k;

			currentPCX16Bank = getCurrentBank(regs.pc, regs.k);     // Update the bank if we are in upper memory.

			// A step by source line is this step repeated until the line

			// changes, so while it has not, arm the next one instead of

			// stopping. Announcing here and resuming would report a stop per

			// instruction to a DAP client for a step the user asked once for.

			if (!DEBUGSourceStepContinue()) {

				currentMode = DMODE_STOP;                               // So now stop, as we've done it.

				// A single step retires here without ever arming a step target, so

				// there is none to retract: the owner of a pending step is derived

				// from whether one is armed at all.

				DEBUGAnnounceStop("step");

			}

		}

	}

	// debug_bp_on_arrival() also counts the hit and spends the ignore budget,

	// so the DMODE_STOP guard is load-bearing rather than an optimisation: while

	// halted this function is polled continuously with the PC parked on the

	// breakpoint, and counting each poll would burn through an ignore count

	// while the machine is standing still.

	//

	// The resume guard covers the other half of the same problem: having just

	// been told to continue from a breakpoint, the PC is still sitting on it,

	// and testing it again would stop instantly and never make progress.

	// Cycles only count as progress when the CPU is actually running them: in

	// WAI it is parked, ticking the clock without retiring anything.

	const bool cpuAdvanced = (clockticks6502 != resumeSkipClock) && !waiting;

	if (resumeSkipPC >= 0

	    && (regs.pc != resumeSkipPC || regs.k != resumeSkipBank || cpuAdvanced)) {

		resumeSkipPC = -1;                                      // the CPU moved on; guard done

	}

	const bool stopped     = (currentMode == DMODE_STOP);

	const bool justResumed = (resumeSkipPC >= 0);

	// Parked in WAI counts as standing still here too. The CPU stops on the

	// instruction AFTER the WAI -- the opcode fetch has already advanced the PC

	// -- and then ticks the clock without retiring anything, so this poll runs

	// once per emulated cycle with the PC unchanged. Testing arrival there

	// stops before the awaited interrupt has happened, and because the test is

	// not a query -- it counts the hit and spends the ignore budget -- an

	// "ignore 60" meant as sixty frames is exhausted in sixty cycles, still

	// inside the first wait.

	//

	// Both ways out stay correct: a masked interrupt clears `waiting` without

	// vectoring, so the next poll sees the PC still on the breakpoint and stops

	// there; a vectored one arrives after the handler returns.

	if (!stopped && !justResumed && !waiting) {

		// Order matters: debug_bp_on_arrival() counts the hit and spends the

		// ignore budget, so it has to be reached exactly as often as before.

		const bool viaUser = debug_bp_on_arrival(regs.pc, regs.k);

		const bool viaStep = !viaUser && hitBreakpoint(regs.pc, regs.k, stepBreakPoint);

		if (viaUser || viaStep) {                               // Hit a breakpoint.

			currentPC = regs.pc;                                    // Update current PC

			currentPCBank = regs.k;

			currentPCX16Bank = getCurrentBank(regs.pc, regs.k);     // Update the bank if we are in upper memory.

			DEBUGClearStepBreakPoint();                             // and the step target is retired

			// A step-over that a source step is driving lands here every time

			// it runs over a call. Keep going while the line has not changed;

			// a breakpoint the user set always wins and ends the source step.

			bool keepStepping = false;

			if (viaUser)

				srcStepActive = false;

			else

				keepStepping = DEBUGSourceStepContinue();

			if (!keepStepping) {

				currentMode = DMODE_STOP;                           // So now stop, as we've done it.

				// A step-over or step-out finishing is a completed step, not a

				// breakpoint nobody set. Both the graphical debugger and a DAP

				// client key off this: a step leaves the view where it is, an

				// arrival re-centres it.

				DEBUGAnnounceStop(viaStep ? "step" : "breakpoint");

			}

		}

	}

	if (SDL_GetKeyboardState(NULL)[DBGSCANKEY_BRK]) {            // Stop on break pressed.

		const bool wasRunning = (currentMode != DMODE_STOP);

		currentMode = DMODE_STOP;

		srcStepActive = false;                                   // the user has taken over

		DEBUGSetStopReason("user");                              // store only: this test is level-triggered

		currentPC = regs.pc;                                     // Set the PC to what it is.

		currentPCBank = regs.k;

		currentPCX16Bank = getCurrentBank(regs.pc, regs.k);      // Update the bank if we are in upper memory.

		if (wasRunning) {                                        // Tell a DAP client too; see DEBUGBreakToDebugger().

			DEBUGAnnounceStop("pause");

		}

	}

	// Repair the bank when it is unset: currentPC moves independently of

	// regs.pc via the navigation keys, so it can land in a banked window while

	// currentPCX16Bank still says "none". Uses the shared rule rather than a

	// local copy of it, which is what let this one keep the old requirement

	// that the program bank be zero.

	if (currentPCX16Bank < 0) {

		currentPCX16Bank = debug_current_x16_bank(currentPC, currentPCBank);

	}

	// Who owns the UI while the machine is not running. With -imgui and no

	// text debugger the graphical one does: it pumps events, repaints, and

	// decides when to resume. Gated on the window having actually been created

	// -- if it failed to open there is no control bar to resume from, and

	// swallowing the loop here would park the machine unrecoverably.

	//

	// Tested on debug_window_enabled, not debugger_enabled: -debugport turns

	// debugger_enabled on by itself to get the breakpoint machinery, so keying

	// on it handed -imgui -debugport to the text debugger -- drawing its

	// overlay over a session that never asked for one, and swallowing the

	// emulator window's keys. debug_window_enabled means -debug/-bp/-wp, which

	// is the question being asked. (-imgui -bp still goes to the text pump, as

	// before: -bp does ask for it.)

	const bool imguiOwnsUI = (!debug_window_enabled && video_debug_ui_available());

	// A DAP client can drive the run state while we are halted, so give it a

	// turn before any front end blocks: continue/step arriving over the socket

	// has to be able to get us moving again, whichever UI is up.

	if (currentMode != DMODE_RUN) {

		debug_server_poll();

		if (currentMode == DMODE_RUN || currentMode == DMODE_STEP) {

			return 0;                                                   // Mode changed remotely — execute.

		}

	}

	// DMODE_STOP only, not "not RUN". DMODE_STEP means one instruction has been

	// asked for and must be executed now: routing it through the pump costs it

	// the pump's 16ms sleep, and a step stays in DMODE_STEP until the PC

	// actually moves. Over a WAI the PC does not move for the whole wait, so

	// stepping one instruction would run at ~60 emulated cycles a second and

	// take tens of minutes. The classic path below has the same shape: it only

	// sleeps once currentMode == DMODE_STOP.

	if (currentMode == DMODE_STOP && imguiOwnsUI) {

		showDebugOnRender = 0;                                  // no SDL overlay in this mode

		return video_debug_ui_pump_paused();

	}

	// The classic text debugger's event pump. Skipped entirely when the ImGui

	// window owns the UI: it drains the whole SDL queue into the text

	// debugger's key handler and drops everything else, so letting DMODE_STEP

	// fall in here destroys every mouse and keyboard event before ImGui or the

	// machine sees it. That is reachable whenever a step leaves the PC where it

	// was -- for the duration of a WAI, and permanently on a `JMP *` self-loop,

	// which would leave the debugger input-dead with no way to quit.

	if (currentMode != DMODE_RUN && !imguiOwnsUI) {                     // Not running, we own the keyboard.

		showFullDisplay =                                               // Check showing screen.

					SDL_GetKeyboardState(NULL)[DBGSCANKEY_SHOW];

		while (SDL_PollEvent(&event)) {                                 // We now poll events here.

			// With -debug and -imgui together this loop is the only one

			// running while halted -- video_update() returns early whenever

			// the text overlay is on screen -- so it has to feed the graphical

			// debugger too. Without this the ImGui window stayed on screen but

			// received no input at all: dead buttons, dead text fields, stale

			// mouse state. -imgui -bp reaches this combination without asking

			// for it, since -bp switches the text debugger on.

			if (video_debug_ui_available()) {

				video_debug_ui_feed_event(&event);

				// Events aimed at the debugger window must not also drive the

				// text debugger's command line.

				if (video_event_targets_debug_ui(&event)) {

					if (event.type == SDL_WINDOWEVENT &&

					    event.window.event == SDL_WINDOWEVENT_CLOSE) {

						continue;   // closing the debugger must not quit

					}

					video_debug_ui_shortcut_key(&event);

					continue;

				}

			}

			switch(event.type) {

				case SDL_QUIT:                                  // Time for exit

					return -1;

				case SDL_WINDOWEVENT:

					// With the ImGui window open SDL2 no longer synthesises

					// SDL_QUIT on a window close -- it only does that for the

					// last window -- so a close arrives here as a bare event.

					// Dropping it made the emulator window's [X] inert while

					// the text debugger was on screen under -debug -imgui.

					if (event.window.event == SDL_WINDOWEVENT_CLOSE) {

						return -1;

					}

					break;

				case SDL_KEYDOWN:                               // Handle key presses.

					DEBUGHandleKeyEvent(event.key.keysym.sym, event.key.keysym.mod & (KMOD_LSHIFT|KMOD_RSHIFT));

					break;

				case SDL_TEXTINPUT:

					DEBUGBuildCmdLine(event.text.text);

					break;

			}

		}

	}

	showDebugOnRender = (currentMode != DMODE_RUN);                         // Do we draw it - only in RUN mode.

	if (currentMode == DMODE_STOP) {                                        // We're in charge.

		video_update();

		SDL_Delay(10);

		return 1;

	}

	// While running, a client still has to be able to connect and ask us to

	// break. This runs per instruction, so polling the socket every time would

	// cost more than the emulation; once every few thousand is still well

	// inside a frame.

	{

		static int poll_counter = 0;

		if (++poll_counter >= 1000) {

			poll_counter = 0;

			if (debug_server_poll()) {

				return (currentMode == DMODE_STOP) ? 1 : 0;

			}

		}

	}

	return 0;                                                               // Run wild, run free.

}

// *******************************************************************************************

//

//								Setup fonts and co

//

// *******************************************************************************************

void DEBUGInitUI(SDL_Renderer *pRenderer) {

		DEBUGInitChars(pRenderer);

		dbgRenderer = pRenderer;				// Save renderer.

}

// *******************************************************************************************

//

//								Setup fonts and co

//

// *******************************************************************************************

void DEBUGFreeUI() {

}

// *******************************************************************************************

//

//								Break into debugger from code.

//

// *******************************************************************************************

void DEBUGBreakToDebugger(void) {

	const bool wasRunning = (currentMode != DMODE_STOP);

	srcStepActive = false;   // whatever we were mid-way through, the user wins

	// Default reason for "something broke into the debugger". Set before the

	// mode changes, so no path can leave the previous stop's reason showing; a

	// caller with something more specific to say (the STP hook) overrides it

	// immediately after.

	DEBUGSetStopReason("user");   // store only; the transition notify is below

	currentMode = DMODE_STOP;

	currentPC = regs.pc;

	currentPCBank = regs.k;

	currentPCX16Bank = getCurrentBank(regs.pc, regs.k);

	// A DAP client only refreshes its view -- stack, variables, step controls --

	// when it is told execution stopped. Halting without saying so leaves it

	// believing the machine is still running. Announced only on the transition,

	// so re-entering an already-halted debugger does not re-announce.

	if (wasRunning) {

		DEBUGAnnounceStop("pause");

	}

}

// A watched address was written. Called from the CPU store path, so it does as

// little as possible: memory.c has already established that a watchpoint

// matched.

//

// The reported location is captured later, not here. At store time the CPU is

// mid-instruction: the addressing mode has already advanced regs.pc past the

// operands, but the instruction's own effect on the PC has not happened yet. An

// ordinary STA lands where regs.pc already points, but a JSR pushing its return

// address, an interrupt pushing its frame, or MVN/MVP rewinding to repeat do

// not -- and those are exactly the writes a stack watchpoint is set to catch.

// Deferring the snapshot to the next status poll reports where the CPU

// actually ended up.

void DEBUGBreakOnWatchpoint(void) {

	if (currentMode != DMODE_STOP) {

		currentMode          = DMODE_STOP;

		watchpointStopPending = true;

	}

}

// *******************************************************************************************

//

//		Execution control.

//

//		One implementation, driven either by the debug window's function keys or

//		by another front end. Previously this logic lived only inside the key

//		handler, so anything else wanting to step had to synthesise key presses

//		-- and would drift out of step with it. Each resume re-bases the timing

//		so the emulator does not fast-forward to "catch up" on the time spent

//		halted.

//

// *******************************************************************************************

static void DEBUGClearStepBreakPoint(void) {

	// Whoever owned the pending step no longer does.

	stepOwner = DEBUG_OWNER_COUNT;

	stepBreakPoint.pc = -1;

	stepBreakPoint.bank = 0;

	stepBreakPoint.x16Bank = -1;

}

/* ---------------------------------------------------------------------------

 * Stepping by source line

 *

 * The machine steps by instruction, which is what the disassembly wants. One

 * line of C is many instructions, so in the Source panel a step key appeared to

 * do nothing for several presses running -- `total = 0;` alone is a call and

 * three more instructions.

 *

 * A source step is the instruction step repeated until the PC lands on a

 * DIFFERENT source line. Nothing about the underlying step changes: step-over

 * still runs calls to completion, step-into still enters them, and both still

 * stop on any breakpoint they run into on the way.

 * ------------------------------------------------------------------------- */

#define SRC_STEP_MAX_INSNS 500000   /* a line that never ends must not hang the UI */

/* srcStepActive is declared with the module state at the top: the instruction

 * step retires inside DEBUGGetCurrentStatus(), well before this point. */

static bool          srcStepOver    = false;

static debug_owner_t srcStepOwner   = DEBUG_OWNER_UI;

static char          srcStepFile[260];

static int           srcStepLine    = -1;

static uint16_t      srcStepSP      = 0;

static long          srcStepBudget  = 0;

static bool          sourceStepPref = true;

void DEBUGSetSourceStep(bool on) { sourceStepPref = on; }

bool DEBUGGetSourceStep(void)    { return sourceStepPref; }

/* The source line the PC is on, or false when the debug info does not cover it. */

static bool debug_line_at_pc(char *file, size_t size, int *line)

{

	const char *f = NULL;

	int         l = 0;

	if (!dbg_info_addr_to_source_banked(regs.pc, (int)memory_get_ram_bank(), &f, &l) || !f)

		return false;

	snprintf(file, size, "%s", f);

	*line = l;

	return true;

}

/* Stepping by line is only offered where a line means more than one

 * instruction. For assembly the two are usually the same thing, and quietly

 * running a whole macro expansion per keypress would change how every existing

 * project steps -- so it takes effect only for cc65 high-level (C) debug info. */

static bool debug_source_step_available(void)

{

	if (!sourceStepPref || !dbg_info_has_high_level())

		return false;

	char f[260];

	int  l = 0;

	return debug_line_at_pc(f, sizeof f, &l);

}

void DEBUGCancelSourceStep(void) { srcStepActive = false; }

static void DEBUGBeginSourceStep(bool over, debug_owner_t owner)

{

	srcStepActive = false;

	if (!debug_line_at_pc(srcStepFile, sizeof srcStepFile, &srcStepLine)) {