// VERA register banking: CTRL at $9F25, and the four registers it banks.
//
// ORACLE (strength B): the VERA Verilog.
//
//   repo:   https://github.com/X16Community/vera-module
//   tag:    v47.0.2   (commit 45cc1f05)
//   file:   fpga/source/top.v
//
// VERA has 32 register addresses and far more than 32 registers, so $9F29-$9F2C
// mean different things depending on DCSEL. Get the banking wrong and a write
// lands in an unrelated register -- a scroll position becomes a border colour
// -- which is the kind of fault that shows up as a corrupted display three
// subsystems away from the cause.
//
// See tests/support/video_fixture.c for the link seam.

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

#include "video.h"

#include <string.h>

#define VERA_CTRL    0x05
#define VERA_DC_0    0x09
#define VERA_DC_1    0x0A
#define VERA_DC_2    0x0B
#define VERA_DC_3    0x0C

// top.v:334-337   if (do_write && access_addr == 5'h05) begin
//                     fpga_reconfigure_next = write_data[7];
//                     dc_select_next        = write_data[6:1];
//                     vram_addr_select_next = write_data[0];
static uint8_t
ctrl(unsigned dcsel, unsigned addrsel)
{
	return (uint8_t)(((dcsel & 0x3F) << 1) | (addrsel & 1));
}

static void
select_dcsel(unsigned dcsel)
{
	video_write(VERA_CTRL, ctrl(dcsel, 0));
}

// top.v:86    reg [5:0] dc_select_r, dc_select_next;
// top.v:336   dc_select_next = write_data[6:1];
//
// Six bits, so 64 banks -- not the four or eight a reader might assume from the
// registers actually in use.
static void
test_dcsel_is_six_bits(void)
{
	video_reset();

	select_dcsel(0);
	check_eq(video_read(VERA_CTRL, true) >> 1 & 0x3F, 0u, "DCSEL 0 reads back");

	select_dcsel(63);
	check_eq(video_read(VERA_CTRL, true) >> 1 & 0x3F, 63u,
	         "DCSEL 63 reads back, so the field is six bits wide");

	select_dcsel(0x2A);
	check_eq(video_read(VERA_CTRL, true) >> 1 & 0x3F, 0x2Au, "and an arbitrary value survives");
}

// top.v:173   5'h05: rddata = {1'b0, dc_select_r, vram_addr_select_r};
//
// Bit 7 reads back as zero regardless of what was written. On a write it is
// fpga_reconfigure (top.v:335), a command rather than stored state, so there is
// nothing to read back.
static void
test_ctrl_bit7_reads_as_zero(void)
{
	video_reset();

	video_write(VERA_CTRL, 0x80);
	check_eq(video_read(VERA_CTRL, true) & 0x80, 0u,
	         "bit 7 reads back as zero after being written high");

	video_write(VERA_CTRL, 0xFF);
	check_eq(video_read(VERA_CTRL, true) & 0x80, 0u, "and still zero with every bit set");
	check_eq(video_read(VERA_CTRL, true) & 0x7F, 0x7Fu,
	         "while DCSEL and ADDRSEL keep what was written");
}

// top.v:337   vram_addr_select_next = write_data[0];
//
// ADDRSEL shares the register with DCSEL, so changing one must not disturb the
// other. Both are written by the same byte, and software sets them separately.
static void
test_addrsel_and_dcsel_are_independent(void)
{
	video_reset();

	video_write(VERA_CTRL, ctrl(5, 1));
	uint8_t got = video_read(VERA_CTRL, true);
	check_eq(got & 1, 1u, "ADDRSEL is bit 0");
	check_eq((got >> 1) & 0x3F, 5u, "and DCSEL is unaffected by it");

	video_write(VERA_CTRL, ctrl(5, 0));
	got = video_read(VERA_CTRL, true);
	check_eq(got & 1, 0u, "ADDRSEL clears");
	check_eq((got >> 1) & 0x3F, 5u, "and DCSEL still holds");
}

// top.v:179-208   5'h09..5'h0C each switch on dc_select_r
//
// The same four addresses carry different registers per bank. This writes a
// value in one bank and checks it is still there after a round trip through
// another, which is what a program does when it touches scroll and scale in the
// same frame.
static void
test_banked_registers_do_not_alias(void)
{
	video_reset();

	// DCSEL 0: $9F2A is DC_HSCALE, $9F2C is DC_BORDER.
	select_dcsel(0);
	video_write(VERA_DC_1, 0x40);
	video_write(VERA_DC_3, 0x11);

	// DCSEL 1: the same addresses are the active-area window.
	select_dcsel(1);
	video_write(VERA_DC_1, 0x99);
	video_write(VERA_DC_3, 0x77);

	select_dcsel(0);
	check_eq(video_read(VERA_DC_1, true), 0x40u, "bank 0 kept its own value");
	check_eq(video_read(VERA_DC_3, true), 0x11u, "and so did its other register");

	select_dcsel(1);
	check_eq(video_read(VERA_DC_1, true), 0x99u, "bank 1 kept its own value");
	check_eq(video_read(VERA_DC_3, true), 0x77u, "and so did its other register");
}

// top.v:184   default: rddata = "V";
// top.v:191   default: rddata = 8'd47;
// top.v:199   default: rddata = 8'd0;
// top.v:207   default: rddata = 8'd0;
//
// Banks with nothing mapped do not read as zero or as open bus: they return the
// version string, which is how software identifies the chip. DCSEL 3 has
// nothing mapped at any of the four addresses.
//
// The last byte diverges. The RTL in tag v47.0.2 reports 47.0.0 -- its version
// registers were never bumped to match the tag name -- while this emulator
// reports 47.0.2 from VERA_VERSION_PATCH in video.c. v48.0.1 introduced
// VERSION_MAJOR/MINOR/BUILD defines and is self-consistent, so no revision
// actually reports 47.0.2.
static void
test_unmapped_banks_return_the_version(void)
{
	video_reset();
	select_dcsel(3);

	// Real reads, not debug reads: video.c:2690 diverts a debug read to the
	// stored composer array before the version path is reached.
	check_eq(video_read(VERA_DC_0, false), (uint32_t)'V',
	         "an unmapped bank reports 'V' at the first address");
	check_eq(video_read(VERA_DC_1, false), 47u, "the major version at the second");
	check_eq(video_read(VERA_DC_2, false), 0u, "the minor version at the third");

	check_divergent(video_read(VERA_DC_3, false) == 0,
	                "the patch version at the fourth reads 0",
	                "emulator reports 2 from VERA_VERSION_PATCH; the RTL in tag v47.0.2 "
	                "reports 47.0.0, so no revision reports 47.0.2");
}

// video.c:2690   if (debugOn) return video_get_dc_value(i);
//
// The debugger reads these registers by a different route than the machine
// does, and for an unmapped bank the two disagree: the CPU sees the version
// string, the debugger sees the stored composer bytes. Nothing in the RTL
// corresponds to a debug read, so this is not a hardware divergence -- it is
// the debugger showing something the running machine would never see, which is
// worth knowing before trusting a register panel.
//
// The debugOn contract elsewhere is about side effects. This is about the value
// itself, which that contract does not cover.
static void
test_debug_and_real_reads_disagree_on_unmapped_banks(void)
{
	video_reset();
	select_dcsel(3);

	check(video_read(VERA_DC_0, true) != video_read(VERA_DC_0, false),
	      "a debug read of an unmapped bank does not match what the CPU sees");
	check_eq(video_read(VERA_DC_0, true), 0u, "the debugger sees the stored composer byte");
	check_eq(video_read(VERA_DC_0, false), (uint32_t)'V', "while the CPU sees the version");
}

// Reading the version does not depend on having selected a bank first, and does
// not disturb the selection: a program probes the chip and carries on.
static void
test_reading_the_version_leaves_the_bank_alone(void)
{
	video_reset();
	select_dcsel(3);

	video_read(VERA_DC_0, true);
	video_read(VERA_DC_1, true);

	check_eq(video_read(VERA_CTRL, true) >> 1 & 0x3F, 3u,
	         "probing the version leaves DCSEL where it was");
}

int
main(void)
{
	test_dcsel_is_six_bits();
	test_ctrl_bit7_reads_as_zero();
	test_addrsel_and_dcsel_are_independent();
	test_banked_registers_do_not_alias();
	test_unmapped_banks_return_the_version();
	test_debug_and_real_reads_disagree_on_unmapped_banks();
	test_reading_the_version_leaves_the_bank_alone();
	return x16_test_summary("vera_regbank");
}