// Commander X16 Emulator — disassembly-accuracy core ("code map").
//
// THE PROBLEM: 65C02/65C816 instructions are variable length, and on the
// 65C816 the operand width of many instructions depends on the M/X bits of the
// processor status register. A naive linear disassembler therefore drifts out
// of alignment: start one byte off (or assume the wrong operand width) and
// every following instruction is garbage until it accidentally re-syncs.
//
// THE FIX: capture ground truth while the program actually runs. Every time the
// CPU fetches an instruction we record (a) that the address is a REAL
// instruction start, keyed by the bank context that actually backs it, and (b)
// the effective processor status (M/X/E folded in) at that moment. The anchored
// disassembler then aligns instruction boundaries using, in priority order:
//   1. recorded instruction starts (live execution ground truth),
//   2. cc65 .dbg span starts (compiler-emitted boundaries),
//   3. a backward self-sync heuristic (try candidate offsets, keep the one that
//      decodes cleanly onto the anchor).
// A decode is never allowed to swallow a recorded start UNLESS it is itself
// recorded -- two recorded starts that overlap are two real execution paths,
// not a bad guess straddling a good one -- so an over-wide guess is corrected
// at the next piece of hard evidence rather than drifting on.
//
// WHERE THE WIDTHS ARE STILL A GUESS, so callers know what they are getting:
// only five instructions change the 65C816 register widths -- REP, SEP, XCE,
// PLP and RTI. REP and SEP apply their own status bits exactly (the bits are in
// the operand), though the widths those imply are still subject to the E
// estimate below. XCE is exact only when both of its inputs are right, and
// neither is guaranteed: it swaps the carry and emulation flags, and the carry
// is not tracked through any data-dependent change (ADC, SBC, the compares, the
// shifts and rotates), while E is not recorded by anchors at all. The last two
// restore a status byte pulled off the stack; this linear, instruction-stream
// analysis does not recover it.
//
// None of these gaps is bounded unconditionally.
//
// A wrong STATUS estimate can be corrected when an accurate, believed anchor is
// reached -- but that anchor fixes its OWN line, and accuracy does not
// automatically carry forward: an anchor on a PLP or an RTI supplies the status
// going INTO it, and the byte it restores is still not modelled, so the very
// next line can be wrong again. A same-opcode stale anchor is "recorded" and
// hands back its old status, and there may be no accurate anchor ahead at all.
//
// A wrong E is weaker again, because anchors do not store E: an anchor fixes
// the width of its own line, and propagation then folds the stale E back in,
// which can mis-size the next unanchored line wherever the stale E and the real
// one imply different widths. It is not unrecoverable -- an XCE decoded with an
// accurate carry writes a correct E, as does an explicit CLC/SEC before one --
// but nothing guarantees such a sequence appears, so no persistent recovery is
// promised.
//
// Note the emulation-mode escape clause applies to the ESTIMATE, not the
// machine: the real CPU in emulation mode always has 8-bit widths, but the
// fold-in here uses the estimated E, so a diverged estimate can size operands
// as though native while the machine is really in emulation. Pinned by tests.
//
// This costs nothing in practice unless all of the following hold at once: the
// machine is a 65C816 (on the 65C02 widths never vary), the line being drawn
// has no currently believed anchor, and the status the estimate carries into
// that line is not the status the code there really runs with. That last one is
// broader than the unmodelled instructions above -- an address-linear walk over
// a branch or call, or a walk started away from the PC, does it too. See
// docs/code-map-width-propagation.md. Every line this could affect already
// reports `recorded = false`.
//
// Anchors are not deleted when the code under them changes -- there is no write
// hook -- so each stores the opcode byte that was executing and is ignored once
// memory no longer matches. That catches most overlay loads, a second program
// loaded over the first, and self-modifying code, without needing a hook on
// every memory write. It is a one-byte check, not a proof: replacement code
// that happens to repeat the same opcode byte at the same address keeps the old
// anchor, and with it the old recorded status. Such an anchor is still
// believed, so it can cover a genuine instruction start in the new code; and on
// a 65C816 its stale status can also make the line decode wider -- or narrower
// -- than the new code really is. Self-correcting once an accurate anchor it
// has not swallowed is reached, if there is one ahead, and pinned by tests. See
// docs/code-map-width-propagation.md.
//
// This header is plain C and is shared by the C core (recording hooks, DAP) and
// the C++ ImGui panel (via debug_ui_bridge.h).
#ifndef _CODE_MAP_H_
#define _CODE_MAP_H_

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

#ifdef __cplusplus
extern "C" {
#endif

// Record a real instruction start as the CPU executes it. Call this at every
// instruction fetch, from every execution site, so coverage is complete.
//   pc       : the instruction-start address (regs.pc before step6502()).
//   pbank    : CPU program bank (regs.k; always 0 on the 65C02). Part of the
//              key only where it actually selects memory -- on a Gen2 machine a
//              non-zero program bank maps its own flat 64K, while on gen1 the
//              program bank selects nothing even with -c816.
//   rambank  : active RAM bank  (memory_get_ram_bank())  — banks $A000-$BFFF.
//   rombank  : active ROM bank  (memory_get_rom_bank())  — banks $C000-$FFFF.
//   status   : effective processor status. The caller folds the emulation-mode
//              width bits in (E set => M/X forced to 8-bit) so the value can be
//              fed straight into disasm()'s implied_status.
// Cheap: one bitset set, one status store and one opcode read/store. Safe to
// call every instruction.
void code_map_record(uint16_t pc, uint8_t pbank, uint8_t rambank, uint8_t rombank, uint8_t status);

// True if `pc` has been recorded as a real instruction start in the given bank
// context AND the opcode byte recorded there still matches memory.
bool code_map_is_recorded_start(uint16_t pc, uint8_t pbank, uint8_t rambank, uint8_t rombank);

// The effective status recorded at `pc`, or `fallback` if `pc` was never
// recorded in this context -- or if its anchor is no longer believed, because
// the opcode byte under it has changed.
uint8_t code_map_recorded_status(uint16_t pc, uint8_t pbank, uint8_t rambank, uint8_t rombank, uint8_t fallback);

typedef enum {
	CM_LINE_INSTRUCTION = 0, // a whole instruction: text is its disassembly
	CM_LINE_DATA        = 1, // raw bytes: text is ".byte $xx,..." over exactly
	                         // `size` bytes, and there is no effective address
} code_map_line_kind_t;

// One disassembled line produced by the anchored disassembler.
typedef struct {
	uint16_t addr;         // start address of this line
	uint8_t  size;         // bytes this line covers (always >= 1)
	uint8_t  status;       // implied_status actually used to decode it
	int32_t  eff_addr;     // effective address, or -1 if none
	bool     recorded;     // a whole instruction, backed by live-execution
	                       // coverage. False for every CM_LINE_DATA row.
	uint8_t  kind;         // code_map_line_kind_t: instruction or raw data
	bool     start_recorded; // this ADDRESS carries a currently believed anchor.
	                         // Distinguishes "no live-execution evidence here"
	                         // from "there is, but the row could not be shown
	                         // whole on this path". Not proof the current code
	                         // ran: an anchor can be evicted with its bank
	                         // context (false negative) or survive a same-opcode
	                         // overwrite (false confidence).
	uint8_t  bytes[4];     // raw bytes (first `size` valid)
	char     text[48];     // mnemonic + operands, or ".byte $xx,..."
} code_map_line_t;

// Produce an aligned disassembly window centered on `center`.
//   center            : address to center on (usually regs.pc).
//   bank              : CPU program bank (regs.k; 0 on the 65C02 / X16 gen1).
//   rambank, rombank  : bank context for banked reads and coverage lookup.
//   lines_before      : number of instructions the backward walk resolves
//                       before `center` (capped at 255; negative is treated as
//                       none). Tiling can turn one resolved instruction into
//                       several rows -- see the note on the returned count
//                       below.
//   lines_after       : number of rows from `center` onward, including the
//                       center row itself. A row count, not an instruction
//                       count: a decode forced to give way emits a
//                       CM_LINE_DATA row, which consumes one of them.
//   out               : caller-provided array receiving the lines, low->high.
//   max_out           : capacity of `out`.
//   out_center_index  : receives the index within `out` of the `center` line
//                       (-1 if it did not fit); may be NULL.
//
// The lines written TILE the range they cover: each one starts exactly where
// the previous one ended, with no gaps and no overlaps, so a caller can render
// them as consecutive rows without reconciling contradictory byte ranges.
//
// Holding that invariant occasionally costs an extra line. Where a decode has
// to be cut short -- it would swallow an address live execution proved is an
// instruction start, or it disagrees with a boundary the backward walk already
// resolved -- the bytes up to the next start are covered by a further line
// rather than left out. The count returned can therefore exceed
// `lines_before + lines_after`; it never exceeds `max_out`. Callers wanting a
// fixed row count should use the returned count, not the requested one.
//
// Returns the number of lines written (<= max_out). Only `out[0 .. returned-1]`
// are meaningful: resolving the window may use the rest of the buffer up to
// `max_out` as scratch, so a caller must not expect entries beyond the returned
// count to be preserved. Nothing is ever written past `max_out`.
int code_map_disasm_window(uint16_t center, uint8_t bank, uint8_t rambank, uint8_t rombank,
                           int lines_before, int lines_after,
                           code_map_line_t *out, int max_out, int *out_center_index);

// Disassemble a run of `count` rows starting at `start`, aligned via the flag
// map. Fills `out` low->high and returns the count written. Used by the DAP
// `disassemble` request. `next_addr` (may be NULL) receives the address just
// past the last row. Rows are normally whole instructions, but a decode forced
// to give way to a recorded start inside it comes back as CM_LINE_DATA, so a
// caller asking for N rows may get fewer than N instructions' worth of address
// range.
int code_map_disasm_forward(uint16_t start, uint8_t bank, uint8_t rambank, uint8_t rombank,
                            int count, code_map_line_t *out, int max_out, uint16_t *next_addr);

// Given a known instruction boundary `addr`, resolve the start address of the
// instruction immediately preceding it, using recorded starts, then .dbg spans,
// then a backward self-sync heuristic. Returns the predecessor address (falls
// back to addr-1 when nothing aligns cleanly).
uint16_t code_map_prev_instruction(uint16_t addr, uint8_t bank, uint8_t rambank, uint8_t rombank);

// Forget all recorded coverage and flags (e.g. on machine reset).
void code_map_reset(void);

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

#endif // _CODE_MAP_H_