// VERA's interrupt latch and mask: IEN ($9F26) and ISR ($9F27).

//

// Four sources reach ISR -- VSYNC, LINE, sprite collision and PCM AFLOW -- but

// only three of them are latches, and only three of ISR's eight bits can be

// cleared by writing to it. Which bits a write can store and which it can

// clear is the whole of what this file checks.

//

// Raster IRQ position is not covered. The plan rules it out as needing

// co-simulation, so events are used as events: nothing here asserts which

// scanline one arrives on.

//

// ORACLE: B -- X16Community/vera-module Verilog, tag v47.0.2

// (45cc1f053376dae12173ea63612820e4d289c0da). The cited lines are quoted

// inline; `python tests/fetch_vera_rtl.py` retrieves the sources to check them

// against. The IRQ logic is identical at v48.0.1, three lines further down

// top.v.

#include "support/video_fixture.h"

#include "support/harness.h"

#include "video.h"

#include <stdint.h>

#define VERA_CTRL       0x05

#define VERA_IEN        0x06

#define VERA_ISR        0x07

#define VERA_IRQLINE    0x08 // write: IRQLINE[7:0]. read: SCANLINE[7:0]

#define VERA_AUDIO_CTRL 0x1B

#define VERA_AUDIO_DATA 0x1D

#define IRQ_VSYNC  0x01

#define IRQ_LINE   0x02

#define IRQ_SPRCOL 0x04

#define IRQ_AFLOW  0x08

#define SPRITE_ATTR 0x1FC00

#define SPRITE_GFX  0x01000

// video_step() advances the scan position by PIXEL_FREQ * steps / mhz and

// subtracts one scan width per call, so any step wider than VGA_SCAN_WIDTH

// (800) advances exactly one line.

static void

step_line(void)

{

	video_step(25.0f, 801.0f, false);

}

// SCAN_HEIGHT lines: every scanline value is passed exactly once and the

// position ends where it began.

static void

step_frame(void)

{

	for (unsigned i = 0; i < 525; i++) {

		step_line();

	}

}

static uint8_t

read_isr(void)

{

	return video_read(VERA_ISR, false);

}

static uint8_t

read_ien(void)

{

	return video_read(VERA_IEN, false);

}

// top.v:529-536

//     irq_enable_audio_fifo_low_r   <= 0;

//     irq_enable_vsync_r            <= 0;

//     irq_enable_line_r             <= 0;

//     irq_enable_sprite_collision_r <= 0;

//     irq_status_vsync_r            <= 0;

//     irq_status_line_r             <= 0;

//     irq_status_sprite_collision_r <= 0;

//     irq_line_r                    <= 0;

static void

test_reset_clears_the_enables_the_latches_and_irqline(void)

{

	video_reset();

	video_write(VERA_IEN, 0x0F);

	video_write(VERA_IRQLINE, 100);

	step_frame();

	check((read_isr() & (IRQ_VSYNC | IRQ_LINE)) != 0, "the frame left something to clear");

	video_reset();

	check_eq(read_ien() & 0x0F, 0, "reset clears the four enables");

	check_eq(read_isr() & 0x07, 0, "reset clears the three status latches");

	uint16_t line = 0xFFFF;

	video_get_irq_state(NULL, NULL, &line);

	check_eq(line, 0, "reset clears IRQLINE");

}

// top.v:334-335

//     if (do_write && access_addr == 5'h05) begin

//         fpga_reconfigure_next = write_data[7];

// Reconfiguring reloads the bitstream, so CTRL bit 7 reaches the reset block

// above rather than being a separate clear.

static void

test_ctrl_bit_7_resets_the_irq_registers(void)

{

	video_reset();

	video_write(VERA_IEN, 0x0F);

	step_frame();

	check((read_isr() & IRQ_VSYNC) != 0, "VSYNC was latched before the reset");

	video_write(VERA_CTRL, 0x80);

	check_eq(read_ien() & 0x0F, 0, "CTRL bit 7 clears the enables");

	check_eq(read_isr() & 0x07, 0, "CTRL bit 7 clears the status latches");

}

// top.v:431-437

//     if (do_write && access_addr == 5'h06) begin

//         irq_line_next[8]                 = write_data[7];

//         irq_enable_audio_fifo_low_next   = write_data[3];

//         irq_enable_sprite_collision_next = write_data[2];

//         irq_enable_line_next             = write_data[1];

//         irq_enable_vsync_next            = write_data[0];

//     end

//

// top.v:175

//     5'h06: rddata = {irq_line_r[8], scanline[8], 2'b0, irq_enable_audio_fifo_low_r, irq_enable_sprite_collision_r, irq_enable_line_r, irq_enable_vsync_r};

static void

test_ien_stores_four_enables_and_nothing_else(void)

{

	video_reset();

	for (unsigned bit = 0; bit < 4; bit++) {

		video_write(VERA_IEN, (uint8_t)(1u << bit));

		check_eq(read_ien() & 0x0F, 1u << bit, "each enable bit round-trips on its own");

	}

	// Bits 5 and 4 are 2'b0 in the read and have no target in the write.

	video_write(VERA_IEN, 0x30);

	check_eq(read_ien() & 0x3F, 0, "IEN bits 5 and 4 store nothing");

	// Through the register alone that is indistinguishable from a fifth bit

	// stored and then masked out on the way back, so check the byte itself:

	// top.v:433-436 assign four flops and there is nowhere else to put one.

	uint8_t stored = 0xFF;

	video_get_irq_state(&stored, NULL, NULL);

	check_eq(stored, 0, "and reach no enable register behind it");

	video_write(VERA_IEN, 0xFF);

	check_eq(read_ien() & 0x3F, 0x0F, "and read zero even when written as ones");

	video_get_irq_state(&stored, NULL, NULL);

	check_eq(stored, 0x0Fu, "with only the four enables stored");

}

// Bit 6 of the read is scanline[8], live, with no write target. Nothing is

// written to it here, so a set bit can only have come from the counter.

static void

test_ien_bit_6_reports_the_scanline(void)

{

	video_reset();

	video_write(VERA_IEN, 0x00);

	check_eq(read_ien() & 0x40, 0, "bit 6 is clear while the scanline MSB is");

	check_eq(video_read(VERA_IRQLINE, false), 0, "with $9F28 reporting the low byte");

	for (unsigned i = 0; i < 256; i++) {

		step_line();

	}

	check_eq(read_ien() & 0x40, 0x40, "bit 6 follows the scanline MSB");

	check_eq(video_read(VERA_IRQLINE, false), 0, "as the low byte wraps to zero");

}

// top.v:444-446

//     if (do_write && access_addr == 5'h08) begin

//         irq_line_next[7:0] = write_data;

//     end

// with bit 8 arriving from IEN at top.v:432, so the compare value is split

// across two registers and one of them also carries the enables.

static void

test_irqline_spans_ien_bit_7_and_9f28(void)

{

	uint16_t line;

	video_reset();

	video_write(VERA_IRQLINE, 0x55);

	video_get_irq_state(NULL, NULL, &line);

	check_eq(line, 0x055, "$9F28 writes the low eight bits");

	video_write(VERA_IEN, 0x80);

	video_get_irq_state(NULL, NULL, &line);

	check_eq(line, 0x155, "IEN bit 7 writes bit 8 and leaves the low byte");

	check_eq(read_ien() & 0x80, 0x80, "and reads back from IRQLINE, not from an enable");

	video_write(VERA_IEN, 0x0F);

	video_get_irq_state(NULL, NULL, &line);

	check_eq(line, 0x055, "so setting the enables clears bit 8 with them");

}

// top.v:438-443

//     if (do_write && access_addr == 5'h07) begin

//         // Clear status bits

//         irq_status_sprite_collision_next = irq_status_sprite_collision_r & !write_data[2];

//         irq_status_line_next             = irq_status_line_r             & !write_data[1];

//         irq_status_vsync_next            = irq_status_vsync_r            & !write_data[0];

//     end

static void

test_isr_latches_are_cleared_by_writing_one(void)

{

	video_reset();

	video_write(VERA_IRQLINE, 100);

	step_frame();

	// Exact rather than masked: a frame with no sprites must latch VSYNC and

	// LINE and nothing else, over AFLOW live from the empty FIFO.

	check_eq(read_isr(), IRQ_VSYNC | IRQ_LINE | IRQ_AFLOW, "a frame latches VSYNC and LINE");

	video_write(VERA_ISR, 0x00);

	check_eq(read_isr(), IRQ_VSYNC | IRQ_LINE | IRQ_AFLOW, "writing zero clears nothing");

	video_write(VERA_ISR, IRQ_LINE);

	check_eq(read_isr(), IRQ_VSYNC | IRQ_AFLOW, "writing one bit clears only that bit");

	// The latch holds until it is written, not until the next line.

	step_line();

	step_line();

	check_eq(read_isr(), IRQ_VSYNC | IRQ_AFLOW, "the remaining latch survives more scanlines");

	video_write(VERA_ISR, IRQ_VSYNC);

	check_eq(read_isr(), IRQ_AFLOW, "and clears when its own bit is written");

}

// top.v:176 takes bit 3 from a wire, and the write above has no clause for it.

//     5'h07: rddata = {sprite_collisions,   audio_fifo_low,              irq_status_sprite_collision_r, irq_status_line_r, irq_status_vsync_r};

//

// audio_fifo.v:24,28

//     wire [11:0] fifo_count = wridx_r - rdidx_r;

//     assign almost_empty = fifo_count < 12'd1024;

static void

test_aflow_is_live_and_cannot_be_written_away(void)

{

	video_reset();

	check_eq(read_isr() & IRQ_AFLOW, IRQ_AFLOW, "an empty FIFO reads as AFLOW");

	video_write(VERA_ISR, 0xFF);

	check_eq(read_isr() & IRQ_AFLOW, IRQ_AFLOW, "which a write of $FF does not clear");

	for (unsigned i = 0; i < 1023; i++) {

		video_write(VERA_AUDIO_DATA, 0x40);

	}

	check_eq(read_isr() & IRQ_AFLOW, IRQ_AFLOW, "1023 bytes is still below the mark");

	video_write(VERA_AUDIO_DATA, 0x40);

	check_eq(read_isr() & IRQ_AFLOW, 0, "1024 clears it with no write to ISR at all");

	// $9F3B bit 7 empties the FIFO, so the bit returns without ISR being

	// touched in either direction.

	video_write(VERA_AUDIO_CTRL, 0x80);

	check_eq(read_isr() & IRQ_AFLOW, IRQ_AFLOW, "and emptying the FIFO brings it back");

}

// top.v:1197-1200

//     wire [3:0] irq_enable = {irq_enable_audio_fifo_low_r, irq_enable_sprite_collision_r, irq_enable_line_r, irq_enable_vsync_r};

//     wire [3:0] irq_status = {audio_fifo_low,              irq_status_sprite_collision_r, irq_status_line_r, irq_status_vsync_r};

//

//     assign extbus_irq_n = (irq_status & irq_enable) == 0;

static void

test_the_irq_line_is_status_and_enable(void)

{

	video_reset();

	// AFLOW is set throughout, so a released line is a statement about IEN

	// rather than about there being nothing to report.

	check_eq(read_isr() & IRQ_AFLOW, IRQ_AFLOW, "AFLOW is set");

	check(!video_get_irq_out(), "a status bit with no enable does not assert");

	video_write(VERA_IEN, IRQ_AFLOW);

	check(video_get_irq_out(), "enabling that source asserts it");

	video_write(VERA_IEN, IRQ_VSYNC);

	check(!video_get_irq_out(), "a different enable does not");

	step_frame();

	check(video_get_irq_out(), "a latch against its own enable asserts it");

	video_write(VERA_ISR, IRQ_VSYNC);

	check(!video_get_irq_out(), "and clearing that latch releases it");

}

// Nothing in the read at top.v:175-176 has a side effect; only the write at

// top.v:438-443 clears. A debugger polling ISR must therefore not cost the

// program an interrupt.

static void

test_reading_the_status_does_not_clear_it(void)

{

	const uint8_t want = IRQ_VSYNC | IRQ_LINE | IRQ_AFLOW;

	video_reset();

	video_write(VERA_IEN, 0x0D);

	step_frame();

	check_eq(read_isr(), want, "the frame latched VSYNC and LINE");

	check_eq(video_read(VERA_ISR, false), want, "a second real read reports the same");

	check_eq(video_read(VERA_ISR, true), want, "and so does a debug read");

	check_eq(read_isr(), want, "with the latches still set after both");

	uint8_t dbg_ien = 0;

	uint8_t dbg_isr = 0;

	video_get_irq_state(&dbg_ien, &dbg_isr, NULL);

	check_eq(dbg_isr, want, "the debugger's own accessor agrees");

	check_eq(dbg_ien, 0x0Du, "as does its view of the enables");

	check_eq(read_isr(), want, "and reading through it clears nothing either");

}

// ─── Sprite collision, ISR bits 7:4 ─────────────────────────────────────────

//

// Unlike the three status latches, the collision nibble is not part of the

// interrupt register at all. It belongs to the sprite renderer, and the ISR

// write path has no way to reach it.

//

// sprite_renderer.v:37

//     assign collisions = frame_collision_mask_r;

//

// sprite_renderer.v:400-403

//     if (frame_done) begin

//         sprcol_irq                = (cur_collision_mask_r != 4'b0);

//         frame_collision_mask_next = cur_collision_mask_r;

//         cur_collision_mask_next   = 4'b0;

//     end

// Sixteen lines of 4bpp, eight bytes each, every pixel colour index 1.

// Collisions are recorded for non-transparent pixels only, so index 0 would

// never collide however the sprites are placed.

static void

fill_sprite_graphics(void)

{

	for (unsigned i = 0; i < 16 * 8; i++) {

		video_space_write(SPRITE_GFX + i, 0x11);

	}

}

// Eight attribute bytes per sprite. Byte 6 holds the collision mask in bits

// 7:4 and the z-depth in bits 3:2; a z-depth of zero is not drawn.

static void

place_sprite(unsigned n, uint8_t mask, uint8_t zdepth)

{

	const uint32_t attr = SPRITE_ATTR + n * 8;

	video_space_write(attr + 0, SPRITE_GFX >> 5);                  // address 12:5

	video_space_write(attr + 1, 0x00);                             // 4bpp, address 16:13

	video_space_write(attr + 2, 0x00);                             // X

	video_space_write(attr + 3, 0x00);

	video_space_write(attr + 4, 0x00);                             // Y

	video_space_write(attr + 5, 0x00);

	video_space_write(attr + 6, (uint8_t)(mask | (zdepth << 2)));

	video_space_write(attr + 7, 0x50);                             // 16x16, palette offset 0

}

// Two sprites on the same pixels. The second one drawn sees the first one's

// mask already in the line buffer, so the reported collision is the AND of

// the two masks.

static void

arm_two_sprites(uint8_t mask_a, uint8_t mask_b, uint8_t zdepth_b)

{

	video_reset();

	fill_sprite_graphics();

	place_sprite(0, mask_a, 1);

	place_sprite(1, mask_b, zdepth_b);

	video_write(VERA_CTRL, 0x00);

	video_write(0x09, 0x41); // DCSEL 0, $9F29: sprites on, VGA output

}

static void

test_a_collision_latches_the_status_and_the_nibble(void)

{

	arm_two_sprites(0x70, 0xD0, 1);

	step_frame();

	check_eq(read_isr() & 0xF0, 0x50, "the nibble reports the masks the sprites share");

	check_eq(read_isr() & IRQ_SPRCOL, IRQ_SPRCOL, "and the collision status latches with it");

}

// frame_collision_mask_next is assigned unconditionally at frame_done, so the

// nibble describes the frame just ended and nothing earlier. The status bit

// beside it is a latch and does not follow.

static void

test_the_nibble_is_replaced_each_frame_while_the_latch_holds(void)

{

	arm_two_sprites(0x70, 0xD0, 1);

	step_frame();

	check_eq(read_isr() & 0xF0, 0x50, "a collision in the first frame");

	// Take the second sprite out of the picture, so the next frame collides

	// with nothing.

	place_sprite(1, 0xD0, 0);

	step_frame();

	check_eq(read_isr() & 0xF0, 0x00, "a frame without one replaces the nibble with zero");

	check_eq(read_isr() & IRQ_SPRCOL, IRQ_SPRCOL, "while the status latch holds until written");

}

// top.v:440 clears the status latch and nothing beside it:

//     irq_status_sprite_collision_next = irq_status_sprite_collision_r & !write_data[2];

static void

test_clearing_the_status_leaves_the_nibble(void)

{

	arm_two_sprites(0x70, 0xD0, 1);

	step_frame();

	video_write(VERA_ISR, IRQ_SPRCOL);

	check_eq(read_isr() & IRQ_SPRCOL, 0, "the collision status clears when written");

	check_eq(read_isr() & 0xF0, 0x50, "leaving the nibble it was reported with");

	// The nibble has no clause in the ISR write at all, so the byte a program

	// reaches for to acknowledge everything at once cannot touch it either.

	arm_two_sprites(0x70, 0xD0, 1);

	step_frame();

	video_write(VERA_ISR, 0xFF);

	check_divergent((read_isr() & 0xF0) == 0x50,

	                "a write of $FF acknowledges the latches without disturbing the nibble",

	                "video.c:2910 clears all eight bits, but ISR bits 7:4 are "

	                "sprite_renderer.v's frame_collision_mask_r, which the write at "

	                "top.v:438-443 cannot reach; on the machine the nibble holds until "

	                "the next vblank replaces it");

}

// sprite_renderer.v:326-328

//     wire [3:0] collision =

//         linebuf_idx_r < 'd640 &&

//         (!pixel_is_transparent && sprite_collision_mask_r != 4'b0) ? (linebuf_rddata[15:12] & sprite_collision_mask_r) : 4'b0;

//

// The mask is used directly. It was inverted until 4f46cb32 (2023-01-26, "Fix

// sprite collision and improve write timings (again)"), which is the only

// change to this expression in the RTL's history -- so masks that share no bit

// distinguish the two forms rather than merely exercising one.

static void

test_masks_collide_only_where_they_overlap(void)

{

	arm_two_sprites(0x30, 0xC0, 1);

	step_frame();

	check_eq(read_isr() & 0xF0, 0x00, "disjoint masks do not collide");

	check_eq(read_isr() & IRQ_SPRCOL, 0, "and raise no collision status");

}

// top.v:1198 builds irq_status from four bits, and the nibble is not among

// them:

//     wire [3:0] irq_status = {audio_fifo_low, irq_status_sprite_collision_r, irq_status_line_r, irq_status_vsync_r};

static void

test_the_nibble_cannot_raise_the_interrupt_line(void)

{

	arm_two_sprites(0x70, 0xD0, 1);

	step_frame();

	video_write(VERA_ISR, IRQ_VSYNC | IRQ_LINE | IRQ_SPRCOL);

	for (unsigned i = 0; i < 1024; i++) {

		video_write(VERA_AUDIO_DATA, 0x40);

	}

	check_eq(read_isr(), 0x50, "with every latch cleared only the nibble is left");

	// Every enable there is: IEN has no bit for the nibble, which is the whole

	// of why it cannot interrupt.

	video_write(VERA_IEN, 0xFF);

	check(!video_get_irq_out(), "which no enable can turn into an interrupt");

}

int

main(void)

{

	test_reset_clears_the_enables_the_latches_and_irqline();

	test_ctrl_bit_7_resets_the_irq_registers();

	test_ien_stores_four_enables_and_nothing_else();

	test_ien_bit_6_reports_the_scanline();

	test_irqline_spans_ien_bit_7_and_9f28();

	test_isr_latches_are_cleared_by_writing_one();

	test_aflow_is_live_and_cannot_be_written_away();

	test_the_irq_line_is_status_and_enable();

	test_reading_the_status_does_not_clear_it();

	test_a_collision_latches_the_status_and_the_nibble();

	test_the_nibble_is_replaced_each_frame_while_the_latch_holds();

	test_clearing_the_status_leaves_the_nibble();

	test_masks_collide_only_where_they_overlap();

	test_the_nibble_cannot_raise_the_interrupt_line();

	return x16_test_summary("vera_irq");

}