// Commander X16 Emulator — bridge for C++ ImGui panels to read C emulator

// state.

//

// The emulator core is C. C++ panels must reach C globals/functions through a

// single, documented, C++-safe surface so that linkage is correct.

//

// FLEET PANEL AUTHORS: include THIS header (not the raw C core headers) to read

// emulator state. If an accessor you need is missing, add the *include* of the

// real emulator header here rather than a declaration of the function -- see

// the note below on why re-declaring is how this file went wrong.

//

// Why it is shaped this way:

//   * Struct/type *definitions* (POD; identical layout in C and C++) are

//     included normally — structs have no language linkage, so `struct regs`

//     is the same type in both languages. (registers.h below.)

//   * Function and variable *declarations* go inside `extern "C"` so the C++

//     compiler references the C symbol names the core actually exports.

#ifndef DEBUG_UI_BRIDGE_H

#define DEBUG_UI_BRIDGE_H

#include <stdint.h>

#include <stdbool.h>

// struct regs — the CPU register file. POD; members include:

//   .pc (uint16)  .a/.xl/.yl (uint8 low bytes)  .c/.x/.y (uint16 aliases)

//   .sp .dp (uint16)  .status .k .db .e (uint8)  .is65c816 (bool)

// See src/cpu/registers.h. Resolved via the `src` include dir.

#include "cpu/registers.h"

// Disassembly: the anchored disassembler / code map (its own extern "C" guards).

#include "code_map.h"

// The real emulator headers, rather than copies of their declarations.

//

// This file used to re-declare ~20 core functions and re-define struct

// breakpoint and struct watchpoint, on the reasoning that debugger.h drags in

// SDL. The cost of that was silent drift: the copies stopped matching the core

// and nothing said so, because a duplicate declaration compiles and links

// perfectly whether or not it is true. Three examples that were live here:

//

//   * dbg_info_label_to_addr / _symbol_at / _addr_to_label were declared with

//     uint16_t* address arguments. The core writes a 32-bit dbg_addr_t through

//     that pointer, so every symbol and source lookup wrote two bytes past the

//     caller's variable.

//   * struct watchpoint was missing the core's x16Bank field, while

//     watchPoints[] was declared extern and indexed directly -- wrong field

//     offsets and a 12-byte stride over a 16-byte array.

//   * memory_get_num_rom_banks() was declared but has never existed.

//   * cpu_irq_return_pc() was declared returning uint16_t against the core's

//     uint32_t, silently dropping the program bank of a 65C816 return address.

//

// So the rule is now the opposite one: include the real header, and where the

// panels genuinely want a different shape, convert in a documented shim below

// where the compiler can check it.

#include "debug_core.h"   // breakpoints, watchpoints, conditions, bank rules

#include "debugger.h"     // execution control + run state (pulls SDL, which is

                          // fine: the ImGui backends are SDL2 already)

#include "dbg_info.h"     // symbols and source lines; owns dbg_addr_t

#include "memory.h"       // real_read6502, write6502, bank mapping

#include "glue.h"         // is_gen2, num_banks, num_ram_banks, MHZ, warp_mode

#include "smc.h"          // smc_requested_reset

#include "timing.h"       // absolute kHz speed control

#include "perf_budget.h"  // guest cycle budget accounting

#include "vera_bandwidth.h" // VERA VRAM fetch and data-port bandwidth

#include "sprite_trace.h" // sprite multiplexing and per-line render time

#include "video.h"        // video_read/video_space_* and the VERA debug views

#include "cpu/irq_ctx.h"  // interrupt context, incl. the 24-bit return PC

#include "cpu/fake6502.h" // irq6502()

// I/O panel: the event ring plus each device's side-effect-free debug snapshot.

// Same rule as above -- the real headers, so a struct that changes shape breaks

// the build here rather than silently misreading device state in the panel.

#include "io_trace.h"   // the I/O event ring buffer

#include "sdcard.h"     // sdcard_debug_get_state, sdcard_get_path

#include "sdcard_fat.h" // the FAT index that names SD blocks

#include "vera_spi.h"   // vera_spi_debug_get_state -- the SD data path

#include "joystick.h"   // joystick_debug_get_state and the JOY_BIT_* layout

#include "via.h"        // via_debug_get_state

#include "i2c.h"        // i2c_debug_get_state

#include "rtc.h"        // rtc_debug_get_state

#include "ieee.h"       // ieee_debug_get_state -- host-FS files, by name

#include "serial.h"     // serial_port, the IEC line states

#ifdef __cplusplus

extern "C" {

#endif

// The global CPU register file (defined in the C core).

extern struct regs regs;

// Non-intrusive read of VERA video memory / register space.

// RAM banking is sized at runtime by -ram, so num_ram_banks (glue.h) is a real

// variable. ROM is not: it is a fixed ROM[NUM_ROM_BANKS * 16384] array and has

// no accessor. The panels asked for memory_get_num_rom_banks(), which linked

// only because this header declared a function nobody defined.

static inline int

memory_get_num_rom_banks(void)

{

	return NUM_ROM_BANKS;

}

// ─── Breakpoints ───────────────────────────────────────────────────────────

// struct breakpoint, breakPoints[], numBreakpoints and the debug_bp_* API all

// come from debug_core.h. The panels were written against the older DEBUG*

// spelling and a two-argument (pc, bank) identity that predates bank

// awareness. A breakpoint is now identified by (pc, bank, x16Bank), because the

// same $A000 in two RAM banks is two different breakpoints.

//

// These shims therefore take x16Bank and pass it through, rather than

// supplying DEBUG_BANK_ANY on the panels' behalf. ANY is a wildcard when a

// breakpoint is *tested* (bank_selector_matches), but debug_bp_find() compares

// x16Bank for equality, so passing ANY as a lookup key finds only breakpoints

// that were themselves stored as ANY. Since an add records a concrete bank for

// every address at $A000 and above, keying on ANY silently matched nothing for

// any breakpoint in banked RAM or ROM -- so they could be set, but never

// removed, disabled, cleared, or have their hits or condition read.

//

// Everything the panels create is owned by DEBUG_OWNER_UI. The core records who

// asked for each entry, so a breakpoint this window sets at an address a DAP

// client also wants survives that client disconnecting, and vice versa.

static inline bool

DEBUGAddBreakPoint(struct breakpoint bp)

{

	return debug_bp_add_for(bp, DEBUG_OWNER_UI) != DEBUG_ADD_FULL;

}

// The user asking for a breakpoint to go means gone, whoever else also wanted

// it. Dropping only this window's claim would leave it armed and the button

// looking broken.

static inline bool

DEBUGRemoveBreakPoint(int pc, uint8_t bank, int x16Bank)

{

	return debug_bp_delete(pc, bank, x16Bank);

}

// Disabling keeps the entry, its owners, its condition and its hit count, so

// the breakpoint still shows in every panel's gutter while it is off.

static inline bool DEBUGSetBreakpointEnabled(int pc, uint8_t bank, int x16Bank, bool on) { return debug_bp_set_enabled(pc, bank, x16Bank, on); }

static inline bool DEBUGIsBreakpointEnabled(int pc, uint8_t bank, int x16Bank) { return debug_bp_is_enabled(pc, bank, x16Bank); }

static inline void DEBUGForgetBreakpoint(int pc, uint8_t bank, int x16Bank) { debug_bp_forget(pc, bank, x16Bank); }

static inline void DEBUGClearBreakpointCondition(int pc, uint8_t bank, int x16Bank) { debug_bp_clear_condition(pc, bank, x16Bank); }

static inline uint32_t DEBUGGetBreakpointHits(int pc, uint8_t bank, int x16Bank) { return debug_bp_get_hits(pc, bank, x16Bank); }

static inline void DEBUGResetBreakpointHits(int pc, uint8_t bank, int x16Bank) { debug_bp_reset_hits(pc, bank, x16Bank); }

static inline void

DEBUGSetBreakpointCondition(int pc, uint8_t bank, int x16Bank, int operand,

                            uint16_t operand_addr, int op, uint32_t value)

{

	debug_bp_set_condition(pc, bank, x16Bank, operand, operand_addr, op, value);

}

static inline void

DEBUGSetBreakpointIgnore(int pc, uint8_t bank, int x16Bank, uint32_t ignore)

{

	debug_bp_set_ignore(pc, bank, x16Bank, ignore);

}

static inline bool

DEBUGGetBreakpointCondition(int pc, uint8_t bank, int x16Bank, int *has_cond,

                            int *operand, uint16_t *operand_addr, int *op,

                            uint32_t *value, uint32_t *ignore)

{

	return debug_bp_get_condition(pc, bank, x16Bank, has_cond, operand,

	                             operand_addr, op, value, ignore);

}

// The panels' operand/comparison names, as aliases of the core's codes rather

// than a second enum with its own numbering. debug_core.h states these values

// are external and must not be renumbered; two independent copies is exactly

// how that promise gets broken.

enum { BP_OPND_A = BPOPERAND_A, BP_OPND_X = BPOPERAND_X, BP_OPND_Y = BPOPERAND_Y,

       BP_OPND_SP = BPOPERAND_SP, BP_OPND_P = BPOPERAND_P,

       BP_OPND_BYTE = BPOPERAND_BYTE, BP_OPND_WORD = BPOPERAND_WORD };

enum { BP_CMP_EQ = BPCMP_EQ, BP_CMP_NE = BPCMP_NE, BP_CMP_LT = BPCMP_LT,

       BP_CMP_LE = BPCMP_LE, BP_CMP_GT = BPCMP_GT, BP_CMP_GE = BPCMP_GE };

// ─── VERA: accessors ───────────────────────────────────────────────────────

// Non-intrusive read of a VERA I/O register (0x00..0x1F). Pass debugOn=true so

// the read has no side effects (no address auto-increment, no FIFO changes).

// Used by the VERA panel to read the layer registers ($0D..$1A) that describe

// map/tile bases, color depth, scroll, and bitmap width.

//

// The per-scanline layer-register history, the active layer size and the VERA

// interrupt prediction all come from video.h, included above.

// ─── Memory: accessors  (Memory panel — keep minimal & shared) ─────────────

// Explicit, intended debug write into VERA video memory (0..0x1FFFF). (video.h)

// Banked-memory mapping controls (memory.c, declared in memory.h above). The

// Memory panel drives its RAM/ROM bank selectors with these.

// Explicit debug write into the CPU address space, mirroring the bank

// semantics of real_read6502(): for banked RAM ($A000-$BFFF) / ROM

// ($C000-$FFFF), x16Bank>=0 selects the bank (-1 = current mapping). Wraps

// write6502() (save/set/restore bank for banked regions).

// NOTE: the definition currently lives in panels/memory_panel.cpp; integration

// may relocate it into the core.

void debug_ui_write6502(uint16_t address, uint8_t value, uint8_t bank, int16_t x16Bank);

// ─── Memory write watchpoints ──────────────────────────────────────────────

// struct watchpoint, MAX_WATCHPOINTS and the debug_wp_* API come from

// debug_core.h. This header used to carry its own copy of the struct, and that

// copy was missing the core's x16Bank field while watchPoints[] was declared

// extern and indexed directly -- so the panel read every field after `len` from

// the wrong offset, with a 12-byte stride over a 16-byte array. The table is

// static in debug_core.c and is now read through debug_wp_at().

//

// Owned by DEBUG_OWNER_UI, like the breakpoints above: -wp on the command line

// and a DAP client's data breakpoints can name the same address, and none of

// them should be able to disarm another's.

static inline bool DEBUGAddWatchPoint(uint16_t addr, uint16_t len) { return debug_wp_add_for(addr, len, DEBUG_BANK_ANY, DEBUG_OWNER_UI) != DEBUG_ADD_FULL; }

static inline bool DEBUGRemoveWatchPoint(uint16_t addr) { return debug_wp_delete(addr, DEBUG_BANK_ANY); }

static inline bool DEBUGCheckWatchPoint(uint16_t addr) { return debug_wp_covers(addr); }

// ─── Machine model (glue.h) ────────────────────────────────────────────────

// is_gen2 is true for the X16 GS / Gen-2 machine (-gs): a 65C816 with 24-bit

// addressable RAM. In gen2, the 65C816 bank byte selects a flat 64K RAM page:

// bank 0 is the classic X16 map (I/O + windowed $A000-$BFFF/$C000-$FFFF banks);

// banks 1..num_banks-1 are flat RAM. num_banks is the total number of 64K CPU

// banks (256 in gen2, 1 otherwise) — bounds the Memory panel's CPU-bank selector.

extern bool     is_gen2;

extern uint16_t num_banks;

// ─── Execution control (debugger.c) ────────────────────────────────────────

// Drive the CPU from a panel exactly like the debugger control bar does. These

// mirror the classic F5/F10/F11 handlers and the DAP commands (including the

// timing re-base on resume). Handy for e.g. a "Run to cursor" in the disasm

// panel or a "Continue" shortcut in any panel.

// Why execution last stopped. This lived in the DAP server before, which meant

// it did not exist unless that was built; it belongs to the debugger, which is

// what actually stops. Kept under the old name so the panels read the same.

static inline const char *debug_server_last_stop_reason(void) { return DEBUGGetStopReason(); }

// Interrupt following (debugger.c). With follow-interrupts on, an interrupt

// taken while stepping stops at the handler's first instruction instead of

// being run through invisibly; break-on-interrupt stops on every entry.

// Publish the "run to cursor" target — the disassembly instruction row under// the mouse — for the Ctrl+F10 shortcut (consumed by debug_ui_run_to_cursor()).

// The Disassembly panel calls this every frame: valid=true for the hovered row,

// valid=false when nothing is hovered. Defined in debug_ui.cpp.

void debug_ui_set_cursor(uint16_t addr, uint8_t bank, bool valid);

// Cross-panel navigation. A panel (e.g. Symbols / Call Stack) calls

// debug_ui_request_goto() to jump the Disassembly + Memory panels to an address;

// those panels call debug_ui_peek_goto() each frame to pick it up. Defined in

// debug_ui.cpp. (One-frame latency; visible to all panels regardless of order.)

void debug_ui_request_goto(uint16_t addr, uint8_t bank);

bool debug_ui_peek_goto(uint16_t *addr, uint8_t *bank);

// "Add to watch": the watch list lives in the CPU panel, but the natural place

// to ask for a watch is wherever you found the address (the memory view's

// context menu, including over a drag-selected range). The CPU panel drains

// this once per frame and splits anything longer than one watch row. bank is an

// x16 RAM/ROM bank, or -1 for "whatever is currently mapped".

void debug_ui_request_watch(uint16_t addr, int16_t bank, uint16_t len);

bool debug_ui_take_watch_request(uint16_t *addr, int16_t *bank, uint16_t *len);

// ─── System control (main.c / smc.c / cpu) ─────────────────────────────────

// Reset is deferred to the emulator-loop boundary via the SMC reset flag (the

// same path Ctrl-R uses) so it never fires mid-instruction; machine_reset()

// also calls code_map_reset() so the disassembly re-aligns. IRQ/NMI are

// edge-triggered exactly like the RESTORE-key NMI already in video.c.

extern bool smc_requested_reset;  // set true to request a machine reset

// ─── Symbols / labels ──────────────────────────────────────────────────────

// dbg_info.h (included above) declares these. The panels want 16-bit addresses

// while the core deals in 24-bit dbg_addr_t, so the narrowing happens here,

// once, in shims the compiler can type-check -- rather than through a

// re-declaration with a uint16_t* parameter, which is what previously made the

// core write four bytes into the caller's two-byte variable.

// ─── Counters (status line) ─────────────────────────────────────────────────

// clockticks6502 comes from cpu/fake6502.h and instruction_counter from

// glue.h, both included above.

// ─── Emulation speed / warp (timing.h above, main.c, glue.h) ────────────────

// Speed is an absolute target clock in kHz. The machine's own clock comes from

// -mhz at startup, so timing_native_khz() is what "normal speed" means for this

// run. Warp bypasses the throttle entirely and ignores the target.

// ─── Interrupt context (cpu/fake6502.c) ─────────────────────────────────────

// The CPU core records interrupt entry/exit so the debugger can show when

// execution is inside a handler. Depth counts nesting.

// ─── VERA interrupt prediction (video.c) ────────────────────────────────────

// Cycles until the next enabled VERA interrupt and the ISR bit that will cause

// it (1 = VSYNC, 2 = LINE); false when neither is enabled.

#ifdef __cplusplus

} // extern "C"

#endif

// ─── Audio: accessors ───────────────────────────────────────────────────────

// The three audio sources each expose a small, side-effect-free debug surface

// for the PSG / YM2151 / PCM panels. Unlike debugger.h (which drags in SDL),

// these headers are plain and carry their own extern "C" guards, so panels get

// the POD debug structs *and* the correctly-linked declarations by including

// them here — hence they are included rather than re-declared.

//

// Threading: psg_render(), pcm_render() and YM_stream_update() all run from

// audio_render() on the emulator main thread, which is the same thread that

// calls debug_ui_render(). The scope ring buffers are therefore

// single-producer/single-consumer on one thread and need no locking.

//

// Scope capture is SELF-ARMING: each *_scope_read() call re-arms capture for

// about half a second, and the audio cores stop capturing on their own once

// nothing reads. Panels just call the read every frame while their Scope tab is

// visible — there is no enable/disable to balance, and no cost when hidden.

#include "vera_psg.h" // PSG voices, registers, scope   (psg_debug_*)

#include "vera_pcm.h" // VERA PCM FIFO + scope          (pcm_debug_*)

#include "ymglue.h"   // YM2151 registers, EG, scope    (YM_debug_*)

// Follow the current X16 bank (mirrors USE_CURRENT_X16_BANK from memory.h).

#define DEBUG_UI_CURRENT_BANK (-1)

// Convenience wrapper mirroring memory.h's debug_read6502() macro, for use from

// C++ panels: read one CPU byte for display with no side effects.

static inline uint8_t

debug_ui_read6502(uint16_t address, uint8_t bank, int16_t x16Bank)

{

    return real_read6502(address, bank, true, x16Bank);

}

// VERA: accessors — bulk copy a run of VERA video memory into `dest`. Wraps the

// 17-bit VRAM space ($00000..$1FFFF) so a viewer can never read out of bounds.

// Convenient for decoding tiles/sprites/bitmaps a whole tile-row at a time.

static inline void

debug_ui_vram_read_range(uint8_t *dest, uint32_t address, uint32_t size)

{

    for (uint32_t i = 0; i < size; ++i) {

        dest[i] = video_space_read((address + i) & 0x1FFFF);

    }

}

// ─── Symbol / source lookups, narrowed ─────────────────────────────────────

// The core addresses code with a 24-bit dbg_addr_t; the panels work in the

// 16-bit CPU address space. Each shim narrows in one place, under the

// compiler's supervision. Passing a uint16_t* straight to the core -- which is

// what this header used to declare -- silently corrupted two bytes of the

// caller's stack on every call.

static inline bool

debug_ui_label_to_addr(const char *name, uint16_t *addr)

{

	dbg_addr_t wide = 0;

	if (!dbg_info_label_to_addr(name, &wide)) return false;

	*addr = (uint16_t)(wide & 0xFFFF);

	return true;

}

static inline bool

debug_ui_source_to_addr(const char *file, int line, uint16_t *addr)

{

	dbg_addr_t wide = 0;

	if (!dbg_info_source_to_addr(file, line, &wide)) return false;

	*addr = (uint16_t)(wide & 0xFFFF);

	return true;

}

static inline bool

debug_ui_symbol_at(int index, const char **name, uint16_t *addr)

{

	dbg_addr_t wide = 0;

	if (!dbg_info_symbol_at(index, name, &wide)) return false;

	*addr = (uint16_t)(wide & 0xFFFF);

	return true;

}

static inline bool

debug_ui_addr_to_label_nearest(uint16_t addr, const char **name, uint16_t *sym_addr)

{

	dbg_addr_t wide = 0;

	if (!dbg_info_addr_to_label_nearest(addr, name, &wide)) return false;

	*sym_addr = (uint16_t)(wide & 0xFFFF);

	return true;

}

static inline bool

debug_ui_name_to_value(const char *name, uint16_t *addr, int *out_kind)

{

	dbg_addr_t wide = 0;

	if (!dbg_info_name_to_value(name, &wide, out_kind)) return false;

	*addr = (uint16_t)(wide & 0xFFFF);

	return true;

}

#endif // DEBUG_UI_BRIDGE_H