// Commander X16 Emulator — debug info for programs the guest loads at runtime.

//

// Debug info given on the command line only ever describes the program that was

// named there. The moment the program under test loads something of its own --

// an overlay, a second stage, a level -- source lookups stop describing what is

// actually executing. This watches host-filesystem loads and merges the debug

// info that sits beside each loaded file.

//

// The facts about a load are collected per channel, as the transfer happens,

// rather than read out of globals when it finishes. Two channels can be open at

// once, and a load that crosses $C000 moves the RAM bank mid-transfer, so

// anything sampled at the end describes the wrong thing.

#ifndef _DBG_LOAD_H_

#define _DBG_LOAD_H_

#include <stdbool.h>

#include <stdint.h>

#ifdef __cplusplus

extern "C" {

#endif

#define DBG_LOAD_PATH_MAX 1024

#define DBG_LOAD_CHANNELS 16

// Everything known about one completed load, copied out of the channel so it

// cannot be disturbed by whatever the guest does next.

typedef struct {

	char     path[DBG_LOAD_PATH_MAX]; // host path the data came from

	uint16_t addr;                    // where the first byte landed

	uint8_t  bank;                    // RAM bank mapped at that moment

	uint32_t size;                    // bytes transferred into memory

	bool     valid;

} dbg_load_event_t;

// Whether to act on loads at all.

//

// The policy is a tri-state because "on" normally means "whenever the debugger

// is on", and the debugger can be switched on by the running machine itself

// (emu_write register 0) long after the command line was parsed. A snapshot

// taken at startup would then be wrong for the rest of the session.

//

//   policy < 0  follow the debugger

//   policy == 0 off, whatever the debugger is doing

//   policy > 0  on, whatever the debugger is doing

void dbg_load_set_policy(int policy);

// The debugger was switched on or off. Ignored unless the policy is to follow.

void dbg_load_note_debugger(bool on);

// Force it on or off, equivalent to setting the policy to 1 or 0.

void dbg_load_set_enabled(bool on);

bool dbg_load_is_enabled(void);

// ---- Reported by the file layer --------------------------------------------

// The host path behind -prg. That load bypasses filename resolution entirely:

// the KERNAL asks for ":*" and the file layer hands back an already-open

// handle, so nothing ever resolves a name for it. Without recording the path up

// front, the most common debugging workflow there is would be the one case that

// silently got no symbols.

void dbg_load_set_prg_path(const char *path);

// A channel was opened onto that -prg file.

void dbg_load_begin_prg(int channel);

// A channel was opened to read `host_path`. Forgets anything the channel was

// previously doing.

void dbg_load_begin(int channel, const char *host_path);

// One byte of a block transfer is going to `addr` with `bank` mapped, `last`

// marking the final byte of the file. Reported just before the write rather

// than just after, because the transfer loop closes its channel the moment it

// sees the end of the file.

//

// Counting the byte and finishing the load are one call on purpose. They were

// three, and that close landed between them -- so the completion ran a few

// lines before the last byte was counted, and every load came out one byte

// short. Doing both here means the call site cannot order them wrongly.

//

// Only the first call for a channel records the destination: that is the one

// that says where the program starts, and which bank it started in. A load

// crossing $C000 moves the RAM bank on as it goes, so a later byte would name a

// different segment.

void dbg_load_note_byte(int channel, uint16_t addr, uint8_t bank, bool last);

// The channel was closed without finishing; drop what was collected.

void dbg_load_abandon(int channel);

// ---- Consumed by the debugger ----------------------------------------------

// Take the completed load, if there is one. Clears it, so it is reported once.

bool dbg_load_take(dbg_load_event_t *out);

// Take any completed load and merge the debug info beside it: load the .dbg

// first, then tell it which bank the program went into, because loading

// replaces the mappings in that address range and would discard an annotation

// made beforehand. Returns true if debug info was loaded.

bool dbg_load_poll(void);

// Whether a host path names a .dbg file. A wildcard LOAD can match the debug

// info sitting beside a program, and reading that as debug info for itself

// would attribute its segments to wherever its text happened to land.

bool dbg_load_path_is_dbg(const char *path);

// Forget everything. For machine reset and tests.

void dbg_load_reset(void);

#ifdef __cplusplus

}

#endif

#endif // _DBG_LOAD_H_