// RAM and ROM banking: the registers at $0000 and $0001, and the two windows
// they steer.
//
// This one needs its oracle stated carefully, because it is weaker than
// anywhere else in the suite and the file is deliberately split along that
// line.
//
// VERA is an FPGA, so its Verilog is the hardware and the VERA tests cite it.
// The X16's banking has no equivalent: it is discrete logic on the board, and
// no schematic, CPLD, GAL or PLD source is published in any X16Community
// repository. The strongest source that exists is the project's own
// documentation, which is a step removed from the hardware.
//
// So:
//
//   ORACLE: C -- X16Community/x16-docs, "X16 Reference - 08 - Memory Map.md",
//   pinned at 79a8303bc33cda4ec3e85f3239f9b3d4c8c76260, for the bank
//   registers, the window sizes and the bank counts. Quoted inline. Fetch it
//   with `python tests/refs/fetch_refs.py`.
//
//   ORACLE: none, for what happens on a bank that is not installed. The
//   documentation says only that such banks are "unavailable" and never says
//   what accessing one does. Those assertions are characterization: they pin
//   what this emulator does today so a change is deliberate, and they are not
//   a claim about hardware. They are grouped separately below and say so.
//
// The fixture is a 512 KB machine -- fake_devices.c sets num_ram_banks to 64 --
// which is one of the two configurations the documentation names, and puts the
// boundary at exactly the bank number it calls out.

#include "support/fake_devices.h"
#include "support/harness.h"

#include "memory.h"

#include <stdint.h>

#define RAM_BANK_REG 0x0000
#define ROM_BANK_REG 0x0001

#define BANKED_RAM_START 0xA000
#define BANKED_RAM_END   0xBFFF
#define BANKED_ROM_START 0xC000

// fake_devices.c declares this as the installed RAM bank count. Stated here as
// a number so a change to the fixture shows up as a failure rather than
// quietly moving what "out of range" means.
#define INSTALLED_RAM_BANKS 64

static void
reset(void)
{
	fake_devices_reset();
	memory_reset();
}

static uint8_t
read(uint16_t address)
{
	return read6502(address, 0);
}

static void
write(uint16_t address, uint8_t value)
{
	write6502(address, 0, value);
}

// ─── Conformance: the documented shape ──────────────────────────────────────

// Memory Map, the banking register table:
//     |$0000    |Current RAM bank (0-255)                                      |
//     |$0001    |Current ROM/Cartridge bank (ROM is 0-31, Cartridge is 32-255) |
//
// and directly beneath it:
//     "The currently set banks can also be read back from the respective
//      memory locations. Both settings default to 0 on RESET."
static void
test_the_bank_registers_hold_and_report_a_bank(void)
{
	reset();
	check_eq(read(RAM_BANK_REG), 0, "the RAM bank defaults to 0 on reset");
	check_eq(read(ROM_BANK_REG), 0, "and so does the ROM bank");

	write(RAM_BANK_REG, 0x2A);
	check_eq(read(RAM_BANK_REG), 0x2A, "the RAM bank reads back what was written");
	check_eq(memory_get_ram_bank(), 0x2A, "and the machine is switched to it");

	write(ROM_BANK_REG, 0x1F);
	check_eq(read(ROM_BANK_REG), 0x1F, "the ROM bank reads back what was written");
	check_eq(memory_get_rom_bank(), 0x1F, "and the machine is switched to it");

	check_eq(read(RAM_BANK_REG), 0x2A, "with the two registers independent");

	// "0-255": the whole byte is the bank number, with nothing reserved.
	write(RAM_BANK_REG, 0xFF);
	check_eq(read(RAM_BANK_REG), 0xFF, "the RAM bank spans the whole byte");
	check_eq(memory_get_ram_bank(), 0xFF, "and reaches the latch unmasked");
	write(ROM_BANK_REG, 0xFF);
	check_eq(read(ROM_BANK_REG), 0xFF, "and so does the ROM bank");
	check_eq(memory_get_rom_bank(), 0xFF, "also unmasked");
}

// The other half of the same sentence: "Both settings default to 0 on RESET."
//
// On the machine $0000 and $0001 are the bank latches themselves, so a reset
// that clears the latches is a reset of what those addresses report. The
// emulator keeps the two apart -- memory.c:325 writes the byte into RAM as
// well as into the latch, and memory.c:220 reads it back out of RAM.
static void
test_a_reset_returns_both_banks_to_zero(void)
{
	reset();
	write(RAM_BANK_REG, 0xFF);
	write(ROM_BANK_REG, 0xFF);

	reset();

	check_eq(memory_get_ram_bank(), 0, "a reset switches the machine to RAM bank 0");
	check_eq(memory_get_rom_bank(), 0, "and to ROM bank 0");

	check_divergent(read(RAM_BANK_REG) == 0,
	                "$0000 reports bank 0 after a reset",
	                "memory.c:110 clears the latch but the address reads RAM[0] "
	                "(memory.c:220), which the reset leaves alone, so the byte reports the "
	                "pre-reset bank while the machine is on bank 0");
	check_divergent(read(ROM_BANK_REG) == 0,
	                "$0001 reports bank 0 after a reset",
	                "same cause as $0000: the register's RAM shadow survives the reset");
}

// Memory Map, the address table:
//     |\$A000-\$BFFF|Banked RAM (8 KB window into one of 256 banks for a total of 2 MB)|
//
// One window, many banks: the same address in two banks is two different
// bytes, and switching back finds the first one again.
static void
test_the_ram_window_shows_one_bank_at_a_time(void)
{
	reset();

	write(RAM_BANK_REG, 0);
	write(BANKED_RAM_START, 0x11);
	write(BANKED_RAM_END, 0x22);

	write(RAM_BANK_REG, 1);
	write(BANKED_RAM_START, 0x33);
	write(BANKED_RAM_END, 0x44);

	check_eq(read(BANKED_RAM_START), 0x33, "bank 1 holds its own byte at the window start");
	check_eq(read(BANKED_RAM_END), 0x44, "and at the window end");

	write(RAM_BANK_REG, 0);
	check_eq(read(BANKED_RAM_START), 0x11, "and bank 0 still holds what it was given");
	check_eq(read(BANKED_RAM_END), 0x22, "at both ends of the window");

	// 8 KB: the byte below the window is fixed RAM and does not move with the
	// bank, which is what makes the window a window. $9EFF rather than $9FFF
	// because the Memory Map puts fixed RAM at "$0000-$9EFF" and I/O above it.
	write(0x9EFF, 0x55);
	write(RAM_BANK_REG, 1);
	check_eq(read(0x9EFF), 0x55, "the last byte of fixed RAM is not banked");
	check_eq(BANKED_RAM_END - BANKED_RAM_START + 1, 8192, "and the window is 8 KB");
}

// Memory Map:
//     |\$C000-\$FFFF|Banked System ROM and Cartridge ROM/RAM (16 KB window into one of 256 banks, see below)|
//     |$0001    |Current ROM/Cartridge bank (ROM is 0-31, Cartridge is 32-255) |
static void
test_the_rom_window_is_sixteen_kilobytes(void)
{
	reset();
	check_eq(0xFFFF - BANKED_ROM_START + 1, 16384, "the ROM window is 16 KB");

	// Banks 0-31 are the system ROM. With no cartridge attached the emulator
	// leaves 32-255 unmapped, which is the characterization group below.
	write(ROM_BANK_REG, 31);
	check_eq(memory_get_rom_bank(), 31, "the last system ROM bank can be selected");
}

// ─── Characterization: undocumented, pinned so a change is deliberate ───────
//
// ORACLE: none. The Memory Map chapter says of a 512 KB machine only that
// "(On systems with only 512 KB RAM, banks 64-255 are unavailable.)" and
// nowhere says what reading or writing one does. There is no schematic to
// consult. Everything below records this emulator's answer; none of it is a
// claim about what the hardware does.
//
// memory.c:262 calls it an open bus read and returns the high byte of the
// address, which is a plausible model of a floating 6502 data bus rather than
// a measured value.

static void
test_an_uninstalled_ram_bank_reads_as_the_address_high_byte(void)
{
	reset();
	check_eq(INSTALLED_RAM_BANKS, 64, "the fixture is a 512 KB machine");

	write(RAM_BANK_REG, INSTALLED_RAM_BANKS - 1);
	write(BANKED_RAM_START, 0x77);
	check_eq(read(BANKED_RAM_START), 0x77, "the last installed bank is real memory");

	write(RAM_BANK_REG, INSTALLED_RAM_BANKS);
	check_eq(read(BANKED_RAM_START), 0xA0, "the first uninstalled bank reads the address high byte");
	check_eq(read(BANKED_RAM_END), 0xBF, "which tracks the address across the window");

	write(RAM_BANK_REG, 0xFF);
	check_eq(read(BANKED_RAM_START), 0xA0, "and the highest bank reads the same");
}

static void
test_a_write_to_an_uninstalled_ram_bank_is_dropped(void)
{
	reset();

	write(RAM_BANK_REG, 0);
	write(BANKED_RAM_START, 0x5A);

	write(RAM_BANK_REG, INSTALLED_RAM_BANKS);
	write(BANKED_RAM_START, 0xA5);

	write(RAM_BANK_REG, 0);
	check_eq(read(BANKED_RAM_START), 0x5A, "a write to an uninstalled bank reaches no memory");
}

// memory.c:359-362 forwards writes to banks 32 and up to the cartridge and
// ignores the rest, so the system ROM is unwritable. The Hardware chapter
// describes a J1 jumper that makes the ROM flashable, which the emulator does
// not model in either direction.
static void
test_writes_to_system_rom_are_ignored(void)
{
	reset();
	write(ROM_BANK_REG, 0);

	const uint8_t before = read(BANKED_ROM_START);
	write(BANKED_ROM_START, (uint8_t)(before ^ 0xFF));
	check_eq(read(BANKED_ROM_START), before, "a write to system ROM changes nothing");
}

static void
test_a_rom_bank_above_the_system_rom_reads_as_open_bus(void)
{
	reset();

	// No cartridge is attached: fake_devices.c leaves CART null.
	write(ROM_BANK_REG, 32);
	check_eq(read(BANKED_ROM_START), 0xC0, "the first cartridge bank reads the address high byte");
	check_eq(read(0xFFFF), 0xFF, "which tracks the address across the window");
}

int
main(void)
{
	test_the_bank_registers_hold_and_report_a_bank();
	test_a_reset_returns_both_banks_to_zero();
	test_the_ram_window_shows_one_bank_at_a_time();
	test_the_rom_window_is_sixteen_kilobytes();

	test_an_uninstalled_ram_bank_reads_as_the_address_high_byte();
	test_a_write_to_an_uninstalled_ram_bank_is_dropped();
	test_writes_to_system_rom_are_ignored();
	test_a_rom_bank_above_the_system_rom_reads_as_open_bus();

	return x16_test_summary("memory_banking");
}