#ifndef _DBG_INFO_H_

#define _DBG_INFO_H_

#include <stdint.h>

#include <stdbool.h>

#ifdef __cplusplus

extern "C" {

#endif

// A debug-info address. Flat 24-bit: bits 0-15 are the CPU address, bits 16-23

// the 65C816 program bank. On the 65C02 the high byte is simply zero. Code on a

// GS/Gen2 machine lives above $FFFF, so a 16-bit address cannot describe it.

typedef uint32_t dbg_addr_t;

// How confident a banked lookup is about the answer it gave.

typedef enum {

	DBG_BANK_NO_MATCH = 0, // no debug info covers this address

	DBG_BANK_RESOLVED,     // matched a segment whose RAM bank is known

	DBG_BANK_UNKNOWN,      // matched, but which bank this segment belongs to

	                       // was never established, so the answer may belong to

	                       // a different bank's segment at the same address

} dbg_bank_result_t;

// Load and parse a cc65 .dbg file. Returns 0 on success, -1 on error.

int dbg_info_load(const char *path);

// Look up source location for a given address.

// Returns true if found, fills in file_path and line_num.

// file_path points to internal storage — do not free.

bool dbg_info_addr_to_source(dbg_addr_t addr, const char **file_path, int *line_num);

// Like dbg_info_addr_to_source, but returns the line whose span *encloses* addr

// (nearest line starting at or below addr and covering it). This keeps the

// current-line highlight correct when the PC lands in the middle of a multi-byte

// instruction while stepping.

bool dbg_info_addr_to_source_nearest(dbg_addr_t addr, const char **file_path, int *line_num);

// Directory of the most recently loaded .dbg file (for locating source files).

// Returns an empty string if no .dbg has been loaded or it had no directory part.

const char *dbg_info_get_dbg_dir(void);

// True when the loaded debug info carries cc65 high-level (C) line records, so

// a source line means a whole C statement rather than one instruction. The

// debugger uses this to decide whether stepping by line is worth offering.

bool dbg_info_has_high_level(void);

// Look up address for a given source location.

// Returns true if found, fills in addr.

bool dbg_info_source_to_addr(const char *file_path, int line_num, dbg_addr_t *addr);

// Check if debug info is loaded

bool dbg_info_is_loaded(void);

// Disassembly alignment helper: returns true if `addr` is the start address of

// a known cc65 .dbg span/line (i.e. a compiler-emitted instruction boundary).

// Used by the anchored disassembler (code_map) as a fallback alignment anchor

// when live execution coverage is unavailable for that address.

bool dbg_info_is_span_start(dbg_addr_t addr);

// Remove all debug mappings in an address range (for module swap)

void dbg_info_unload_range(dbg_addr_t start, dbg_addr_t end);

// Peek at a .dbg file's segment range without loading it.

// Returns true if a matching .dbg file exists and has valid segments.

bool dbg_info_peek_file_range(const char *loaded_path, dbg_addr_t *out_start, dbg_addr_t *out_end);

// Auto-load .dbg file matching a loaded binary. Unloads overlapping range first.

// Returns 0 on success, -1 if no .dbg found.

// NOTE: this unloads the min/max span of every segment the .dbg declares before

// re-parsing, which for a normal cc65 program runs from the zero page to the top

// of the program. That is wider than what the load actually overwrote, so it

// also drops other modules' records in that window -- including debug info

// loaded with -dbgfile, which nothing re-merges.

//

// It cannot simply be narrowed. Segment, span, line and label records are still

// appended unconditionally -- only file and equate records are reused -- so a

// range that misses this module's own BSS and zero-page records leaves them

// behind while adding fresh copies, and they accumulate until an address can be

// described by a module that is no longer resident. Evicting other modules and

// replacing this one's own records want different ranges.

//

// Records do now carry the module they came from, but only the deduplicated

// ones and dbg_seg_t. Finishing this means giving dbg_span_t/dbg_line_t/

// dbg_sym_t the same owner field and having dbg_info_unload_range() drop by

// owner rather than purely by address.

//

// NOTE: load_addr is currently ignored -- the debug info always describes the

// program at its link-time addresses. A relocating load (secondary address 0)

// therefore reports source lines for where the program was linked, not where it

// actually landed.

int dbg_info_load_for_file(const char *loaded_path, dbg_addr_t load_addr);

/* Address -> source, disambiguated by the X16 RAM bank currently mapped at

 * $A000-$BFFF. Programs routinely place several segments at $A000 (one per RAM

 * bank); the .dbg records no bank, so a banked address otherwise matches every

 * one of them and the reported file/line is effectively arbitrary. Pass the

 * live RAM bank (memory_get_ram_bank()) to pick the right one; pass -1 to skip

 * bank filtering. dbg_info_addr_to_source_nearest() is the ram_bank = -1 form.

 *

 * Segments whose bank could not be established stay eligible, so a mapping is

 * never lost -- but the answer may then belong to another bank's segment at the

 * same address. Use the _ex form to tell the two cases apart and say so, rather

 * than showing a confident file/line that might be from the wrong bank. */

bool dbg_info_addr_to_source_banked(dbg_addr_t addr, int ram_bank,

                                    const char **file_path, int *line_num);

dbg_bank_result_t dbg_info_addr_to_source_banked_ex(dbg_addr_t addr, int ram_bank,

                                                    const char **file_path, int *line_num);

/* Tell the debug info that a runtime LOAD placed `size` bytes at `load_addr`

 * while RAM bank `ram_bank` was mapped. When that uniquely identifies a banked

 * segment, the segment is associated with that bank. No-op outside

 * $A000-$BFFF. (Banks are also seeded from RAM_BANK_* equates in the .dbg.) */

void dbg_info_note_bank_load(dbg_addr_t load_addr, uint32_t size, uint8_t ram_bank);

// Free all loaded debug info

void dbg_info_free(void);

// ---- Symbol / label lookups (from cc65 .dbg `sym` records) ------------------

// Symbol names point to internal storage owned by the loaded debug info. Unlike

// file paths, they do NOT survive a module swap: dbg_info_unload_range() frees

// the names of the symbols it drops. Copy anything that has to outlive a load

// or unload.

// Address label at exactly `addr` (type=lab). `name` points to internal storage

// — do not free. Returns false if none.

bool dbg_info_addr_to_label(dbg_addr_t addr, const char **name);

// Label that `addr` falls inside: the nearest one at or below it, with its own

// address returned in `label_addr` so callers can render "name+offset".

//

// A return address on the stack points just past a JSR, which is almost never

// exactly a label, so an exact lookup leaves every caller frame anonymous. This

// is what the Call Stack needs to name its frames.

//

// It will happily match a far-away label for an address the debug info does not

// really cover, so only trust it where the address is known to be in mapped

// code (e.g. when dbg_info_addr_to_source_banked() also succeeds).

bool dbg_info_addr_to_label_nearest(dbg_addr_t addr, const char **name, dbg_addr_t *label_addr);

// Address of a label by name (case-insensitive, exact match). Returns false if

// no such label.

bool dbg_info_label_to_addr(const char *name, dbg_addr_t *addr);

// Value of a cc65 `equ` record by name (case-insensitive). Equates are the

// KERNAL entry points, hardware register names, zero-page variable addresses

// and plain constants a program defines; they are deliberately kept out of the

// label map (which stays a clean address→name map for the disassembler) but are

// exactly what a user hovers in source. Returns false if no such equate.

bool dbg_info_equate_to_value(const char *name, dbg_addr_t *val);

// What kind of name dbg_info_name_to_value() resolved.

#define DBG_NAME_LABEL  0

#define DBG_NAME_EQUATE 1

// Resolve any name the debug info knows: program labels first, then equates.

// `kind` (optional) receives DBG_NAME_LABEL or DBG_NAME_EQUATE.

bool dbg_info_name_to_value(const char *name, dbg_addr_t *val, int *kind);

// Enumerate all address labels (sorted by address). dbg_info_symbol_at fills

// `name` (internal storage) and `addr` for 0 <= index < dbg_info_symbol_count().

int  dbg_info_symbol_count(void);

bool dbg_info_symbol_at(int index, const char **name, dbg_addr_t *addr);

// ---- Source-file enumeration (for the debugger's file picker) ---------------

// Maximum path length used by dbg_info_scan_dbg_files().

#define DBG_INFO_PATH_MAX 260

// Enumerate the source files referenced by the loaded .dbg (by the name as

// recorded — usually a basename). Lets the debugger pre-open any known source

// file to set breakpoints / run-to before the PC reaches it. `name` points to

// internal storage — do not free. Valid for 0 <= index < dbg_info_file_count().

//

// When the .dbg carries cc65 high-level (C) line info, the ".s" files cc65

// generated on the way from C to the assembler are left out: they are not what

// the user wrote, and cl65 deletes them, so offering them opens a file that is

// not there. A hand-written .s stays on offer — see refresh_line_type_state()

// for exactly what has to hold before one is treated as generated. The indices

// are dense either way, so a caller walks 0..count-1 as before.

int  dbg_info_file_count(void);

bool dbg_info_file_at(int index, const char **name);

// Scan a directory (non-recursive) for cc65 ".dbg" files, writing up to `max`

// full paths into `out`. Portable (uses dirent). Safe if dir is NULL/empty.

// Returns the number of paths written. Lets the debugger surface other .dbg

// modules that the running code may LOAD later, so their sources/line

// breakpoints can be queued up ahead of time.

int  dbg_info_scan_dbg_files(const char *dir, char out[][DBG_INFO_PATH_MAX], int max);

#ifdef __cplusplus

}

#endif

#endif