// Commander X16 Emulator — I/O event trace ring buffer.
//
// THE PROBLEM: the debugger can show you the CPU, memory, VERA and the audio
// sources, but I/O is invisible. When a program talks to the SD card, the
// joysticks, the SMC or the IEEE bus and gets the wrong answer back, there is
// nothing to look at. The state is spread across a dozen `.c` files as file
// statics, and the interesting part is not the state anyway -- it is the
// *sequence*: which command went out, what came back, in what order.
//
// THIS MODULE is the sequence half. It is a fixed-capacity ring of I/O events,
// fed from two places:
//
//   1. the $9F00-$9FFF dispatch in memory.c, which records a raw register
//      access (IO_EVENT_ACCESS), and
//   2. the devices themselves, which record decoded, human-readable events
//      (IO_EVENT_DECODED) such as "CMD17 READ_SINGLE_BLOCK lba=74216".
//
// WHY IT IS PER-DEVICE GATED: VERA's data ports are touched thousands of times
// per frame. Capturing them by default would push every other device out of the
// ring within a frame or two, so each device has its own capture bit and VERA
// starts off. `io_trace_wants()` is the inline predicate call sites use, so a
// device whose bit is clear costs one test-and-branch.
//
// WHY THIS FILE HAS NO EMULATOR DEPENDENCIES: memory.c is linked into
// tests/test_debugon_contract.c and tests/test_watchpoint_purity.c against
// recording fakes rather than the real devices. Anything memory.c calls has to
// link in that environment too, so this module includes nothing but libc and
// its own header. The CPU context stamped onto each event (PC, bank, cycle
// count) therefore arrives through a caller-installed provider rather than by
// reaching for `regs` and `clockticks6502` directly.
//
// THREADING: the emulator steps devices and renders the debugger on the same
// thread, so the ring needs no locking. The SDL audio callback thread runs
// independently but touches none of these devices. Do not call into this
// module from the audio callback.
#ifndef _IO_TRACE_H_
#define _IO_TRACE_H_

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

#ifdef __cplusplus
extern "C" {
#endif

// The devices a trace event can be attributed to. The first group corresponds
// to address ranges in the I/O page; the second to devices that sit behind
// another device's registers and can only report themselves.
typedef enum {
	IO_DEV_VIA1 = 0,
	IO_DEV_VIA2,
	IO_DEV_VERA,
	IO_DEV_SPI, // VERA $9F3E/$9F3F -- the SD card data path, see below
	IO_DEV_YM,
	IO_DEV_EMU,
	IO_DEV_MIDI,
	IO_DEV_OPENBUS,
	IO_DEV_SDCARD, // decoded SD commands and responses
	IO_DEV_IEEE,   // host-filesystem file access, with real filenames
	IO_DEV_I2C,    // the I2C bus, and the SMC/RTC behind it
	IO_DEV_JOYSTICK,
	IO_DEV_SERIAL,
	IO_DEV_COUNT
} io_device_t;

// $9F3E/$9F3F are VERA registers, but they are also the *only* way the SD card
// is reached. They get their own device so that turning VERA capture off -- the
// default, because of the data ports -- does not also blind you to SD traffic.
// This is a deliberate departure from a strict address-range mapping.

typedef enum {
	IO_EVENT_ACCESS = 0, // a raw register read or write
	IO_EVENT_DECODED,    // a device-decoded event; `text` carries the meaning
} io_event_kind_t;

#define IO_TRACE_TEXT_MAX 72

typedef struct {
	uint32_t seq;     // monotonic, never reused; survives capacity changes
	uint32_t cycles;  // clockticks6502 when recorded (wraps, and $9FB8 resets it)
	uint16_t pc;      // CPU PC at the time of the access
	uint16_t addr;    // register address; 0 for decoded events with no register
	uint8_t  pc_bank; // 65C816 program bank
	uint8_t  value;
	uint8_t  device;  // io_device_t
	uint8_t  kind;    // io_event_kind_t
	bool     is_write;
	bool     has_addr; // false for decoded events that name no register
	char     text[IO_TRACE_TEXT_MAX];
} io_event_t;

// Master switch and the per-device capture bits. Both are read directly by the
// inline predicate below, so flipping either takes effect on the next access.
extern bool     io_trace_enabled;
extern uint32_t io_trace_device_mask;

#define IO_TRACE_BIT(dev) (1u << (unsigned)(dev))

// Everything except VERA's registers and open-bus reads. See the header comment
// for why VERA is excluded: it would otherwise be the only thing in the ring.
#define IO_TRACE_MASK_DEFAULT \
	(~(IO_TRACE_BIT(IO_DEV_VERA) | IO_TRACE_BIT(IO_DEV_OPENBUS)))

// The predicate every call site uses. Kept inline and side-effect-free so that
// a disabled trace costs a load and a branch on the I/O hot path.
static inline bool
io_trace_wants(io_device_t dev)
{
	return io_trace_enabled && (io_trace_device_mask & IO_TRACE_BIT(dev)) != 0;
}

// Supplies the CPU context stamped onto each event. Installed by memory.c;
// when absent, events are recorded with a zero PC and cycle count rather than
// not at all, so the module stays usable in unit tests.
typedef void (*io_trace_context_fn)(uint16_t *pc, uint8_t *pc_bank, uint32_t *cycles);
void io_trace_set_context_provider(io_trace_context_fn fn);

// Allocates the ring. Safe to call again to resize; existing events are
// discarded because their ordering relative to a new ring is not meaningful.
// Returns false if the allocation failed, in which case capture stays off.
bool io_trace_init(int capacity);
void io_trace_shutdown(void);
void io_trace_clear(void);

int      io_trace_capacity(void);
int      io_trace_count(void);
uint32_t io_trace_total(void);   // events ever recorded, including overwritten
uint32_t io_trace_dropped(void); // events overwritten by the ring wrapping

// Index 0 is the OLDEST retained event. Returns NULL when out of range.
const io_event_t *io_trace_at(int index);

// Record a raw register access. Call AFTER the device handler for reads, so the
// value is the one the machine actually saw; reads have side effects (VERA
// auto-increment, SPI byte consumption) and must never be repeated to observe
// them. Call BEFORE the handler for writes, so that any decoded event the
// device emits in response is ordered after the access that caused it.
void io_trace_access(io_device_t dev, uint16_t addr, uint8_t value, bool is_write);

// Record a decoded event. `fmt` is printf-style and the result is truncated to
// IO_TRACE_TEXT_MAX. Call sites should still guard with io_trace_wants() to
// avoid formatting work that will be thrown away.
void io_trace_event(io_device_t dev, const char *fmt, ...);

// As io_trace_event(), but attributed to a specific register.
void io_trace_event_at(io_device_t dev, uint16_t addr, bool is_write, const char *fmt, ...);

const char *io_trace_device_name(io_device_t dev);

#ifdef __cplusplus
}
#endif

#endif