// Commander X16 Emulator — interrupt context tracking.

//

// The CPU core has no notion of "currently servicing an interrupt": it vectors

// through, and the only trace is a return address on the stack. A debugger

// needs more than that. It wants to say whether you are inside a handler and

// how deep, to stop at the first instruction of one instead of stepping over

// the whole thing invisibly, and to show where the handler will return to.

//

// interrupt6502() reports an entry and rti() reports a leave; the two are

// paired by matching the stack pointer at entry exactly, which keeps nested

// handlers straight and unwinds several at once when a handler returns past

// its own frame.

//

// A handler that leaves by some other route -- discarding its frame and exiting

// through RTS or JMP, or a BRK that lands in a warm start which resets the

// stack -- has no matching RTI. Those entries are retired the next time an

// interrupt is taken at or above where they were recorded, since the stack

// having risen back past a frame proves it is gone. Until then the depth reads

// high rather than low, which is the safe direction: claiming no interrupt is

// running while one is would be worse than being stale.

//

// What this cannot survive is the stack pointer moving for a reason other than

// nesting. Both rules -- frames decreasing in sp, and a balanced RTI landing

// exactly on the recorded pointer -- read position as evidence of depth. A

// guest that pushes past the bottom of page 1 wraps, and a handler that

// relocates the stack with TXS or TCS moves it outright; either can make a live

// outer frame look like one the stack has passed, and it will be retired.

//

// No rule based on the stack pointer alone can tell those apart. What decides

// it is not which case is commoner but how each fails: retiring wrongly drops

// however many outer handlers the bad comparison covered, but only until the

// next interrupt taken at a sane stack level, whereas never retiring leaves a

// frame open for the rest of the session and adds another every time it

// happens. A bounded, self-healing error beats an unbounded permanent one.

//

// A consumer that acts on cpu_irq_return_pc() -- setting a breakpoint there to

// step over a handler, say -- therefore wants an explicit validity signal, so

// it can fall back to single-stepping rather than trusting a stale address.

// That belongs with the consumer, which does not exist yet.

//

// Kept apart from fake6502.c so that the CPU core carries only the two calls,

// and so the bookkeeping can be tested without standing up a machine.

#ifndef _CPU_IRQ_CTX_H_

#define _CPU_IRQ_CTX_H_

#include <stdbool.h>

#include <stdint.h>

#ifdef __cplusplus

extern "C" {

#endif

// How many nested handlers keep per-frame detail. Deep enough for any plausible

// nesting: the X16 has IRQ, NMI and BRK, and a handler that re-enables

// interrupts can nest a few more. Past this the depth still counts, but the

// per-frame detail stops being recorded. Exposed so tests cannot drift from it.

#define CPU_IRQ_CTX_MAX 16

// ---- Reported by the CPU core ----------------------------------------------

// `vector` is the enum InterruptType that got us here, `from_pc` the 24-bit PC

// that was interrupted -- the program bank is part of it on the 65816, and is

// zeroed on entry, so it cannot be recovered later -- and `sp` the stack

// pointer BEFORE the interrupt pushed anything, which is what the matching RTI

// will restore it to.

void cpu_irq_ctx_enter(int vector, uint32_t from_pc, uint16_t sp);

void cpu_irq_ctx_leave(uint16_t sp);

void cpu_irq_ctx_reset(void);

// ---- Asked by the debugger -------------------------------------------------

bool     cpu_in_interrupt(void);

int      cpu_irq_depth(void);      // nested handlers currently open

uint32_t cpu_irq_count(void);      // interrupts taken since reset

int      cpu_irq_last_vector(void);

uint32_t cpu_irq_return_pc(void);  // where the innermost handler returns to (24-bit)

// True once per interrupt entry; reading it clears the flag. Lets a debugger

// notice "an interrupt was just taken" without polling the depth and having to

// work out whether it changed.

bool cpu_irq_take_entered_flag(void);

#ifdef __cplusplus

}

#endif

#endif // _CPU_IRQ_CTX_H_