// Commander X16 Emulator — debugger core: breakpoints.
//
// The breakpoint table and the decision "should execution stop here?", kept
// apart from debugger.c so the logic can be exercised on its own. debugger.c
// is an SDL window; this is not, and the interesting behaviour here -- bank
// matching, conditions, ignore counts -- is exactly the kind that is worth
// testing directly rather than by driving a UI.
//
// Upstream tracked a single breakpoint in one global. That is enough to answer
// "stop at this address" and nothing else: no second breakpoint, no way to say
// which RAM bank was meant, no "only when A == 3", no "skip the first 100
// iterations". Those are the things a debugging session actually needs, and
// they are what this adds.

#ifndef _DEBUG_CORE_H_
#define _DEBUG_CORE_H_

#include <stdint.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

// A bank selector, stored on a breakpoint or watchpoint.
//
// Banks only mean anything at $A000-$FFFF: the RAM window follows the RAM bank,
// the ROM window the ROM bank, and everything below $A000 selects memory by
// address alone. So there are exactly two things a selector can say --
// "whichever bank is mapped" or "this specific bank" -- and for an address
// outside a banked window it says nothing at all.
//
// A selector recorded for an unbanked address is normalised to DEBUG_BANK_ANY
// on the way in, so it can never become a hidden field that distinguishes two
// otherwise identical entries. (A UI should grey the field out for such an
// address, for the same reason.)
#define DEBUG_BANK_ANY (-1)

// Who asked for a breakpoint or watchpoint.
//
// Several independent things want breakpoints, they do not know about each
// other, and more than one of them can want the same address at the same time:
// a `-bp` on the command line, the user at the keyboard, and each of the three
// kinds of breakpoint a DAP client can set. Without a record of who asked, the
// first remove disarms the address for all of them -- and the entry that is
// left behind belongs to nobody, which on a headless `-debugport` run means a
// machine that halts with nothing able to resume it.
//
// The core only ever compares these, so the list can be extended freely.
typedef enum {
	DEBUG_OWNER_CLI = 0,        // -bp / -wp
	DEBUG_OWNER_UI,             // the SDL debugger's F9, and the ImGui panels
	DEBUG_OWNER_DAP_SOURCE,     // DAP setBreakpoints
	DEBUG_OWNER_DAP_FUNCTION,   // DAP setFunctionBreakpoints
	DEBUG_OWNER_DAP_INSTRUCTION,// DAP setInstructionBreakpoints
	DEBUG_OWNER_DAP_CONSOLE,    // bp_add / watch_add typed in the debug console
	DEBUG_OWNER_STEP,           // the debugger's own step-over/step-out target
	DEBUG_OWNER_COUNT
} debug_owner_t;

// A breakpoint address. `bank` is the 65C816 program bank; `x16Bank` is the
// bank selector described above. Breakpoints are identified by all three.
//
// `owners` and `enabled` are maintained by the core; a caller that builds one
// of these to hand to debug_bp_add_for() should set only the three address
// fields and leave the rest zeroed.
struct breakpoint {
	int      pc;
	uint8_t  bank;
	int      x16Bank;
	uint16_t owners;  // bitmask of debug_owner_t; never 0 for a live entry
	bool     enabled; // a disabled breakpoint keeps its place, and its count
};

// The live table. Read-only for everyone outside debug_core.c: everything that
// changes it goes through the functions below, so that ownership cannot be
// bypassed. Prefer debug_bp_count()/debug_bp_at().
extern struct breakpoint *breakPoints;
extern int                numBreakpoints;

// What a condition tests. Values are part of the debugger's external interface
// (the DAP server and the GUI both name them), so do not renumber.
enum {
	BPOPERAND_A = 0,
	BPOPERAND_X,
	BPOPERAND_Y,
	BPOPERAND_SP,
	BPOPERAND_P,
	BPOPERAND_BYTE, // the byte at operand_addr
	BPOPERAND_WORD, // the little-endian word at operand_addr
};

// How it is compared. Also external; do not renumber.
enum {
	BPCMP_EQ = 0,
	BPCMP_NE,
	BPCMP_LT,
	BPCMP_LE,
	BPCMP_GT,
	BPCMP_GE,
};

// Does a recorded bank selector apply to `addr` right now? See DEBUG_BANK_ANY.
// Public so that every matcher in the emulator uses one rule -- the step
// breakpoint in debugger.c included -- rather than each re-deriving it and
// disagreeing about what -1 means.
bool debug_bank_selector_matches(int selector, int addr, uint8_t pbank);

// What the core will actually record for a selector at this address. Outside a
// banked window there is nothing to select, so it stores DEBUG_BANK_ANY. A
// caller that keeps its own copy of the key must normalise the same way, or its
// copy will not match the entry the core created.
int debug_normalise_bank(int selector, int addr, uint8_t pbank);

// Which RAM/ROM window `pc` sits in given program bank `pbank`, or
// DEBUG_BANK_ANY where a bank means nothing there. Exported so callers that
// produce selectors use the same rule as the matcher above: a second copy will
// eventually disagree with it, and the one that existed did -- on gen1 with a
// non-zero program bank, where read6502 forces the bank to zero and the window
// registers still apply.
int debug_current_x16_bank(int pc, uint8_t pbank);

// Build a breakpoint from an address reference, deciding what a packed bank byte
// meant. `ref` is up to 24 bits: the low 16 are the address, and a non-zero top
// byte is the 65C816 program bank on a Gen2 and the RAM/ROM window bank
// otherwise -- read6502 forces the program bank to zero off Gen2, so a top byte
// there cannot be one. `explicit_bank` carries a window bank the caller was told
// separately (the "bb:aaaa" form), or DEBUG_BANK_ANY; naming one both ways is
// refused rather than resolved. `offset` is a byte displacement, wrapped inside
// the 16-bit address so it cannot carry into the bank.
//
// Returns false when the request could never match -- a bank named for an
// address no window register reaches, or a reference out of range -- so a caller
// can say so instead of arming an entry that silently never fires. `out` is
// left alone on failure, and receives an unowned, disabled entry on success,
// ready for debug_bp_add_for().
bool debug_bp_from_ref(long ref, int explicit_bank, long offset, struct breakpoint *out);

// ---- Table management ------------------------------------------------------
// Breakpoints are identified by all three of (pc, bank, x16Bank), so the same
// address in two different RAM banks is two different breakpoints.
//
// Every entry records which owners asked for it. Two owners wanting one address
// share a single entry -- there is only ever one place the CPU can stop -- but
// the entry survives until the last of them lets go. This is the whole point of
// the API: an owner can clear everything it asked for without having to know
// what anyone else wanted.

// What debug_bp_add_for() did. "Already there" is deliberately distinct from
// "no room": a caller that conflates them silently mishandles a full table.
typedef enum {
	DEBUG_ADD_CREATED = 0, // a new entry, now owned by the caller
	DEBUG_ADD_EXISTED,     // an entry was already there; the caller now owns it too
	DEBUG_ADD_FULL         // out of memory; nothing was armed
} debug_add_result_t;

// Add `owner`'s reference. Adding one that this owner already holds is
// idempotent. A re-added breakpoint is re-enabled, since asking for a
// breakpoint is a request for it to be armed.
debug_add_result_t debug_bp_add_for(struct breakpoint bp, debug_owner_t owner);

// Drop `owner`'s reference. The entry itself only goes when the last owner
// does. Returns whether this owner held one.
//
// The condition and hit count survive, exactly as they do for any other
// removal: a front end that replaces its whole breakpoint list on every edit
// (which is how the Debug Adapter Protocol works) passes through here
// constantly, and a hit count that reset on each keystroke would be useless.
bool debug_bp_remove_for(int pc, uint8_t bank, int x16Bank, debug_owner_t owner);

// Drop every reference `owner` holds -- what each DAP "here is the complete
// list" request wants, and what session teardown wants. Returns how many
// entries were disarmed entirely (as opposed to left for another owner).
int debug_bp_clear_owner(debug_owner_t owner);

// Delete the breakpoint outright, whoever asked for it.
//
// This is the human's delete -- F9, or `bp_remove` typed in the console -- and
// it is deliberately not a refcount operation. Someone at the keyboard asking
// for a breakpoint to go and watching it stay armed because a client also
// wanted it is worse than the confusion this ownership model exists to fix.
// Returns whether anything was there.
bool debug_bp_delete(int pc, uint8_t bank, int x16Bank);

// Does `owner` hold a reference here? For a UI marking its own breakpoints.
bool debug_bp_has_owner(int pc, uint8_t bank, int x16Bank, debug_owner_t owner);

// The human's F9: delete whatever is at this address, or create one owned by
// `owner` if there is nothing there.
void debug_bp_toggle_for(int pc, uint8_t bank, int x16Bank, debug_owner_t owner);

int  debug_bp_find(int pc, uint8_t bank, int x16Bank);
void debug_bp_clear_all(void);

// ---- Enable / disable ------------------------------------------------------
// A disabled breakpoint keeps its entry, its owners, its condition and its hit
// count, and simply does not stop the machine.
//
// Front ends used to implement this by removing the entry and remembering it
// themselves, which is the same mistake as reconstructing ownership from
// outside: the breakpoint vanishes from the table, so every other view of it
// loses its marker and its count.
bool debug_bp_set_enabled(int pc, uint8_t bank, int x16Bank, bool enabled);
bool debug_bp_is_enabled(int pc, uint8_t bank, int x16Bank);

// ---- Read-only view --------------------------------------------------------
// For UIs and the DAP server listing what is set. `debug_bp_at` returns NULL if
// `index` is out of range, and its result is valid only until the next call
// that adds or removes a breakpoint.
int                      debug_bp_count(void);
const struct breakpoint *debug_bp_at(int index);

// ---- The hot-path question -------------------------------------------------
// Tell the core the CPU has arrived at (pc, bank), and get back whether to stop.
//
// Named as an event rather than a question because it IS one: it counts the hit
// and spends the ignore budget. Call it once per instruction, only while
// actually running, and only from whatever owns execution. Calling it while
// halted re-counts the same arrival -- the debugger polls with the PC parked on
// the breakpoint, so that would burn through an ignore count while the machine
// stands still. Use debug_bp_is_set() for the read-only question.
bool debug_bp_on_arrival(int pc, uint8_t bank);

// Whether any *enabled* breakpoint covers (pc, bank), asking nothing and
// changing nothing. This is the one to use for "would the machine stop here?".
// A disabled breakpoint is still in the table -- see debug_bp_at() for a view
// that includes it.
bool debug_bp_is_set(int pc, uint8_t bank);

// ---- Conditions and counts -------------------------------------------------
// A breakpoint stops when its condition (if any) holds AND it has been hit more
// times than its ignore count. Counting is per breakpoint and starts the first
// time that breakpoint is reached, so a count exists even for one that was
// never given a condition. Only arrivals that satisfy the condition are
// counted, so "ignore the first 100" means 100 that would otherwise have
// stopped, not 100 that merely passed through.
//
// A count deliberately survives removing and re-adding the same breakpoint,
// since that is how a UI implements an enable/disable toggle and a toggle
// should not silently reset it. That applies to owner-scoped removal too, so a
// client re-sending its breakpoint list does not reset the counts it is about
// to ask about. The two calls that discard a count are debug_bp_forget(), for
// one breakpoint, and debug_bp_clear_all(), which is a delete of everything
// rather than a disable.
//
// A condition belongs to the address, not to whoever asked for it. Two owners
// wanting different conditions at one address is a real conflict with no
// correct answer, and per-owner conditions would mean per-owner evaluation on
// arrival, on the hot path. The last writer wins; a front end that replaces a
// breakpoint list should therefore state the condition it wants every time,
// including clearing it, rather than assuming removal cleared it.
void     debug_bp_set_condition(int pc, uint8_t bank, int x16Bank, int operand,
                                uint16_t operand_addr, int op, uint32_t value);
void     debug_bp_clear_condition(int pc, uint8_t bank, int x16Bank);
void     debug_bp_forget(int pc, uint8_t bank, int x16Bank);
void     debug_bp_set_ignore(int pc, uint8_t bank, int x16Bank, uint32_t ignore);
uint32_t debug_bp_get_hits(int pc, uint8_t bank, int x16Bank);
void     debug_bp_reset_hits(int pc, uint8_t bank, int x16Bank);
bool     debug_bp_get_condition(int pc, uint8_t bank, int x16Bank, int *has_cond, int *operand,
                                uint16_t *operand_addr, int *op, uint32_t *value,
                                uint32_t *ignore);

// Release everything. Only needed at shutdown or in tests.
void debug_core_free(void);

// ---- Memory write watchpoints ----------------------------------------------
// "Stop when something writes to this address" -- the counterpart to a
// breakpoint for data rather than code, and the tool for finding what is
// corrupting a variable when you have no idea which code is responsible.
//
// Checked by a linear scan on every CPU store, so the scan is skipped entirely
// while none are set: the cost is only paid during an active debugging session.
// The table is fixed-size because a scan per store has to stay small, and 64 is
// roomy enough to watch a whole structure a field at a time.
#define MAX_WATCHPOINTS 64

struct watchpoint {
	uint16_t addr;
	uint16_t len;       // 1 = a single byte, >1 = a range starting at addr
	int      x16Bank;   // bank selector, as for a breakpoint (see DEBUG_BANK_ANY)
	bool     active;
	bool     has_value; // when set, only fire if the written value compares true
	uint8_t  value;
	int      op;        // BPCMP_* comparison code
	uint16_t owners;    // bitmask of debug_owner_t; maintained by the core
};

// Watch `len` bytes from `addr` in bank `x16Bank` (see DEBUG_BANK_ANY).
// Identified by (addr, x16Bank), like a breakpoint, so the same address can be
// watched in more than one bank.
//
// Ownership works exactly as it does for breakpoints, and for the same reason:
// `-wp` on the command line, the debugger and a DAP client can all want one
// address, and the first remove must not disarm it for the others. A watch that
// already exists keeps its length and value filter; the new owner is asking to
// be told about the address, not to redefine someone else's watch.
debug_add_result_t debug_wp_add_for(uint16_t addr, uint16_t len, int x16Bank, debug_owner_t owner);
bool debug_wp_remove_for(uint16_t addr, int x16Bank, debug_owner_t owner);
int  debug_wp_clear_owner(debug_owner_t owner);
bool debug_wp_delete(uint16_t addr, int x16Bank);
bool debug_wp_has_owner(uint16_t addr, int x16Bank, debug_owner_t owner);
void debug_wp_clear_all(void);
int  debug_wp_count(void);
// Read-only access to watchpoint `index`, for listing them in a UI. NULL when
// the index is out of range. The pointer is into the live table, so it is only
// valid until the next add/remove.
const struct watchpoint *debug_wp_at(int index);
// Exact-identity test, the counterpart to debug_wp_covers(). Use this to decide
// whether a toggle should add or remove, so that the decision and the removal
// agree on the key.
bool debug_wp_exists(uint16_t addr, int x16Bank);

// Only fire when the value being written compares true against `value`, so
// "stop when this becomes zero" does not stop on every other write to it.
// Returns false if no watchpoint starts at (addr, x16Bank).
bool debug_wp_set_value(uint16_t addr, int x16Bank, int op, uint8_t value);
// Remove a value filter set by debug_wp_set_value(), so the watchpoint fires on
// any write again.
bool debug_wp_clear_value(uint16_t addr, int x16Bank);

// Temporarily stop a watchpoint firing without forgetting how it was set up.
bool debug_wp_set_active(uint16_t addr, int x16Bank, bool active);

// Does any watchpoint cover `addr`? Read-only; for a UI marking watched bytes.
bool debug_wp_covers(uint16_t addr);

// Read-only view of the watchpoint table, for UIs and the DAP server that need
// to list what is being watched. Returns NULL if `index` is out of range.
// Valid until the next call that adds or removes a watchpoint.
const struct watchpoint *debug_wp_at(int index);

// The CPU is writing `value` to `addr`: should execution stop? Honours the
// value filter. Called from the store path, so callers should test
// debug_wp_count() first and skip this entirely when nothing is being watched.
bool debug_wp_check_write(uint16_t addr, uint8_t value);

#ifdef __cplusplus
} // extern "C"
#endif

#endif // _DEBUG_CORE_H_