// VERA PCM channel: the FIFO the CPU feeds and the two registers that drive it.
//
// ORACLE (strength B): the VERA Verilog. VERA is an FPGA, so the RTL is not a
// description of the hardware -- it IS the hardware. Documentation and the
// emulator's own C are both downstream of it and can drift from it.
//
//   repo:   https://github.com/X16Community/vera-module
//   tag:    v47.0.2   (commit 45cc1f05)
//   files:  fpga/source/audio/audio_fifo.v
//           fpga/source/audio/pcm.v
//           fpga/source/top.v                          (register decode)
//
// v47.0.2 because that is what this emulator reports itself to be, from
// VERA_VERSION_MAJOR/MINOR/PATCH in video.c. Guest software reads those bytes
// back and adapts to them, so the version the emulator claims is the version it
// has to behave like, whatever revision any particular physical board carries.
// tests/check_vera_version.py fails if the two are changed apart.
//
// The audio RTL happens to be byte-identical in v48.0.1, so nothing here turns
// on the choice; the two differ only in the version registers and a bus
// write-address register. Line numbers in top.v do differ between them, and
// these are v47.0.2's.
//
// Use this repo and no other. X16Community/vera-module is a fork of
// fvdhoef/vera-module, but the two diverged at the v0.7 release in 2019 and are
// now different chips: the parent has no audio RTL of any kind -- no audio
// directory, no PCM, no FIFO, and only eight bus registers. Audio was added for
// production hardware and exists solely in the fork.
//
// Every expectation below quotes the RTL it rests on, so a reader can check the
// claim here rather than take it on trust or re-derive it from the repo. An
// assertion with no quoted RTL does not belong in this file.
//
// Three behaviours diverge from the RTL and are marked with check_divergent().
// Those assert what the HARDWARE does: they print loudly and do not fail the
// build. If one starts passing, the emulator has been fixed and the marker must
// be deleted rather than left lying.
//
// Pin a commit, but check the history before calling something a divergence.
// Two of the three below look like emulator inventions against the pinned RTL
// and are not: the feature was real, sat on the RTL trunk for five weeks in
// 2023, and was reverted as an accidental merge before any release. A single
// snapshot would have recorded that as "no hardware counterpart", which is
// wrong and would have justified deleting working code. VERA firmware is
// field-flashable, so what matters is what shipped, not what main holds today.
//
// vera_pcm.c includes only its own header and libc, so this links it directly
// with no fixture and no SDL.

#include "support/harness.h"

#include "vera_pcm.h"

#include <string.h>

// audio_fifo.v:20   reg [7:0] mem_r [4095:0];                 // 4096 cells
// audio_fifo.v:22   wire [11:0] wridx_next = wridx_r + 12'd1;
// audio_fifo.v:26   assign empty = (wridx_r == rdidx_r);
// audio_fifo.v:27   assign full  = (wridx_next == rdidx_r);
//
// 4096 cells exist, but `full` asserts one short of them: the write pointer is
// never allowed to catch the read pointer, because wridx == rdidx already means
// empty. So the usable depth is 4095.
#define USABLE (PCM_FIFO_SIZE - 1)

static struct pcm_debug_state
state(void)
{
	struct pcm_debug_state s;
	pcm_debug_get_state(&s);
	return s;
}

static void
fill(unsigned count, uint8_t first)
{
	for (unsigned i = 0; i < count; i++) {
		pcm_write_fifo((uint8_t)(first + i));
	}
}

// audio_fifo.v:31-34   if (rst) begin wridx_r <= 0; rdidx_r <= 0; rddata <= 0; end
// top.v:540-544        audio_pcm_sample_rate_r <= 0; ... audio_pcm_volume_r <= 0;
static void
test_reset_clears_pointers_and_registers(void)
{
	pcm_reset();
	fill(100, 0x10);
	pcm_write_ctrl(0x2F);
	pcm_write_rate(64);

	pcm_reset();
	struct pcm_debug_state s = state();
	check_eq(s.fifo_cnt, 0u, "reset empties the FIFO");
	check_eq(s.fifo_rdidx, 0u, "reset clears the read pointer");
	check_eq(s.fifo_wridx, 0u, "reset clears the write pointer");
	check_eq(s.ctrl, 0u, "reset clears the control register");
	check_eq(s.rate, 0u, "reset clears the rate register");
	check_eq(s.phase, 0u, "reset clears the rate accumulator");
}

// audio_fifo.v:37-40   if (wr_en && !full) begin
//                          mem_r[wridx_r] <= wrdata;
//                          wridx_r <= wridx_next;
//                      end
//
// The write is gated on !full with no else branch, so a byte arriving at a full
// FIFO is dropped: nothing wraps, nothing is overwritten, no error is raised.
static void
test_fifo_depth_is_one_less_than_its_memory(void)
{
	pcm_reset();
	fill(USABLE, 0);
	check_eq(state().fifo_cnt, (unsigned)USABLE,
	         "the FIFO fills to 4095, one short of its 4096 cells");

	pcm_write_fifo(0xAA);
	check_eq(state().fifo_cnt, (unsigned)USABLE,
	         "a write to a full FIFO is dropped");
}

// top.v:227   5'h1B: rddata = {audio_fifo_full, audio_fifo_empty,
//                              audio_mode_16bit_r, audio_mode_stereo_r,
//                              audio_pcm_volume_r};
//
// Bits 7 and 6 of a read are the live FIFO flags from audio_fifo.v:26-27, not
// stored register bits.
static void
test_full_and_empty_status_bits(void)
{
	pcm_reset();
	check(pcm_read_ctrl() & 0x40, "an empty FIFO reports empty");
	check(!(pcm_read_ctrl() & 0x80), "an empty FIFO does not report full");

	pcm_write_fifo(0x01);
	check(!(pcm_read_ctrl() & 0x40), "one byte is not empty");
	check(!(pcm_read_ctrl() & 0x80), "one byte is not full");

	fill(USABLE - 1, 0);
	check(pcm_read_ctrl() & 0x80, "4095 bytes reports full");
	check(!(pcm_read_ctrl() & 0x40), "a full FIFO does not report empty");
}

// audio_fifo.v:24   wire [11:0] fifo_count = wridx_r - rdidx_r;
// audio_fifo.v:28   assign almost_empty = fifo_count < 12'd1024;
//
// A strict less-than against a literal 1024, on a real subtraction-based count
// rather than a pointer-MSB approximation. 1023 asserts and 1024 does not, and
// that edge is what drives the AFLOW interrupt.
static void
test_almost_empty_is_strictly_below_1024(void)
{
	pcm_reset();
	check(pcm_is_fifo_almost_empty(), "an empty FIFO is almost empty");

	fill(1023, 0);
	check(pcm_is_fifo_almost_empty(), "1023 bytes is almost empty");
	check(state().almost_empty, "and the debug view agrees");

	pcm_write_fifo(0);
	check_eq(state().fifo_cnt, 1024u, "1024 bytes queued");
	check(!pcm_is_fifo_almost_empty(), "1024 bytes is not almost empty");
	check(!state().almost_empty, "and the debug view agrees");
}

// top.v:473-477   if (do_write && access_addr == 5'h1B) begin
//                     audio_fifo_reset_next  = write_data[7];
//                     audio_mode_16bit_next  = write_data[5];
//                     audio_mode_stereo_next = write_data[4];
//                     audio_pcm_volume_next  = write_data[3:0];
//
// Bit 5 is the 16-bit flag, bit 4 selects stereo, bits 3:0 are volume. Those
// six bits are the whole of the stored state, and a read returns them under the
// two status bits.
static void
test_ctrl_stores_mode_and_volume_only(void)
{
	pcm_reset();
	pcm_write_ctrl(0x3F);
	check_eq(state().ctrl, 0x3Fu, "16-bit, stereo and full volume are stored");

	pcm_reset();
	pcm_write_ctrl(0x15);
	check_eq(state().ctrl, 0x15u, "stereo and volume 5 are stored");
}

// top.v:474   audio_fifo_reset_next = write_data[7];
// top.v:320   audio_fifo_reset_next = 0;          // default, every cycle
// pcm.v:31    wire audio_fifo_reset = rst || fifo_reset;
//
// Bit 7 is a one-shot command rather than a stored setting: the default
// assignment clears it every cycle, so it pulses for the write cycle only and
// resets both FIFO pointers via audio_fifo.v:32-33.
static void
test_ctrl_bit7_resets_the_fifo(void)
{
	pcm_reset();
	fill(50, 0);
	pcm_write_ctrl(0x80);
	check_eq(state().fifo_cnt, 0u, "bit 7 empties the FIFO");
	check_eq(state().ctrl, 0u, "bit 7 itself is not stored");
}

// DIVERGENCE 1 -- AUDIO_RATE is stored raw on hardware; the emulator folds it.
//
// top.v:139       reg [7:0] audio_pcm_sample_rate_r, audio_pcm_sample_rate_next;
// top.v:479-480   if (do_write && access_addr == 5'h1C) begin
//                     audio_pcm_sample_rate_next = write_data;
// top.v:228       5'h1C: rddata = audio_pcm_sample_rate_r;
// pcm.v:67        sr_accum_r <= sr_accum_r + sample_rate;
// pcm.v:72        wire new_sample = next_sample_r && (sr_accum7_r != sr_accum_r[7]);
//
// All 8 bits are stored unchanged -- no fold, no mask, no clamp -- read back
// unchanged, and added whole to the rate accumulator. A new sample fires when
// bit 7 of that accumulator flips, so a LARGER value plays FASTER, all the way
// to 255.
//
// This is a leftover from the loop feature, not a reading of the hardware. No
// RTL revision has ever transformed this register:
//
//   2020-03-08  1b402ea2 (original PCM)  sr_accum_r <= sr_accum_r + sample_rate;
//   2023-08-12  70a03e00 (loop era)      5'h1C: audio_pcm_sample_rate_next = write_data;
//   v47.0.2     45cc1f05 (this oracle)   same, top.v:480
//
// The original emulator code by VERA's designer was `rate = val`, matching all
// three. Upstream #116 then added a loop feature triggered by writing
// AUDIO_RATE > 128, and masked to recover the rate: `loop = (val > 128);
// rate = loop ? (val & 0x7f) : val`. When #159 moved that trigger onto
// AUDIO_CTRL bits 6 and 7 -- correctly, to match the RTL of the day -- it left
// a transform behind on the rate register and changed it to `256 - val`.
//
// loop is now assigned only in pcm_write_ctrl, so nothing reads loop state out
// of this register. The fold survives with no purpose beyond corrupting rates
// above 128: 200 becomes 56, playing at roughly a quarter of the hardware speed
// and reading back as 56. Values up to and including 128 are unaffected, and
// 128 is the fold's fixed point, so the boundary itself is invisible -- which
// is why this has gone unnoticed.
static void
test_rate_register_stores_the_raw_value(void)
{
	pcm_reset();

	pcm_write_rate(0);
	check_eq(pcm_read_rate(), 0u, "rate 0 is stored as 0");
	pcm_write_rate(64);
	check_eq(pcm_read_rate(), 64u, "rate 64 is stored as 64");
	pcm_write_rate(128);
	check_eq(pcm_read_rate(), 128u, "rate 128 is stored as 128");

	pcm_write_rate(129);
	check_divergent(pcm_read_rate() == 129, "rate 129 is stored as 129",
	                "emulator folds to 127; top.v:480 stores write_data unchanged");

	pcm_write_rate(200);
	check_divergent(pcm_read_rate() == 200, "rate 200 is stored as 200",
	                "emulator folds to 56; on hardware 200 plays faster than 128, not slower");

	pcm_write_rate(255);
	check_divergent(pcm_read_rate() == 255, "rate 255 is stored as 255",
	                "emulator folds to 1, near-silence, where hardware runs near maximum");
}

// DIVERGENCE 2 -- AUDIO_CTRL bit 6 does nothing on any released hardware.
//
// top.v:473-477 decodes only bits 7, 5, 4 and 3:0 of a write to 0x1B; bit 6 is
// never read. Searching top.v for write_data[6] finds one use, at top.v:340,
// for sprites_enabled on an unrelated register. audio_fifo.v assigns rdidx_r in
// exactly two places, :33 (reset, together with wridx_r) and :44 (increment on
// read), so nothing rewinds the read pointer alone.
//
// The emulator treats bit 6 as a "restart" that rewinds the read pointer while
// keeping the queued data. That was NOT invented: the RTL briefly carried the
// same feature, and the emulator implemented it faithfully.
//
//   2023-08-09  VERA v0.3.1 released -- no loop or restart
//   2023-08-12  vera-module 70a03e00 adds fifo_restart and fifo_loop, decoding
//                 audio_fifo_reset_next   = write_data[7:6] == 2'b10;
//                 audio_fifo_restart_next = write_data[6];
//                 audio_fifo_loop_next    = write_data[7:6] == 2'b11;
//               and an rd_rst input on the FIFO that clears rdidx_r alone
//   2023-08-13  emulator #159 matches that decode exactly, one day later
//   2023-09-16  vera-module b1ada295 reverts it: "Was accidentally merged in"
//   2023-11-20  v0.3.2, then v47.0.2 and v48.0.1 -- none contain fifo_loop or
//               fifo_restart
//
// So the feature existed on the RTL trunk for five weeks, by mistake, and is in
// no released bitstream. The emulator tracked the addition and not the revert.
// Recorded rather than removed, since software written in the meantime may use
// it -- but no real machine has ever had it.
static void
test_ctrl_bit6_is_ignored(void)
{
	// The read pointer has to be somewhere other than zero for this to mean
	// anything: rewinding to zero from zero is indistinguishable from doing
	// nothing, so render first to advance it.
	pcm_reset();
	fill(100, 0x40);
	int16_t buf[128];
	pcm_write_rate(128);
	pcm_render(buf, 20);

	unsigned rd_before = state().fifo_rdidx;
	unsigned cnt_before = state().fifo_cnt;
	check(rd_before > 0, "the read pointer has advanced");

	pcm_write_ctrl(0x40);
	check_divergent(state().fifo_rdidx == rd_before,
	                "bit 6 leaves the read pointer alone",
	                "emulator rewinds it to 0; bit 6 of 0x1B is not decoded in top.v");
	check_divergent(state().fifo_cnt == cnt_before,
	                "bit 6 leaves the queued count alone",
	                "emulator requeues everything written; there is no restart in the RTL");
}

// DIVERGENCE 3 -- there is no loop mode on any released hardware.
//
// The string "loop" does not occur anywhere in top.v, audio.v, pcm.v or
// audio_fifo.v at the pinned commit. There is no loop register, no loop input
// on the pcm module (pcm.v:8-20), and no re-read path in the FIFO.
//
// The emulator reads bits 7 and 6 set together as loop mode and, in that case,
// deliberately does not reset the FIFO. On the pinned RTL bit 7 resets it
// regardless of bit 6, because bit 6 is not decoded at all.
//
// Same history as divergence 2: the reverted RTL had
//     if (fifo_empty && fifo_loop) fifo_restart_next = 1;
// which is precisely the emulator's `if (loop && fifo_cnt == 0) fifo_restart()`.
// The emulator is a faithful implementation of a design that was accidentally
// merged and then reverted before any release.
static void
test_no_loop_mode(void)
{
	pcm_reset();
	fill(50, 0);
	pcm_write_ctrl(0xC0);
	check_divergent(state().fifo_cnt == 0,
	                "bit 7 resets the FIFO even with bit 6 set",
	                "emulator reads bits 7+6 as loop mode and keeps the data; no loop in the RTL");
}

// audio_fifo.v:17-18   reg [11:0] wridx_r = 0;  reg [11:0] rdidx_r = 0;
// audio_fifo.v:22-23   wridx_next = wridx_r + 12'd1;  rdidx_next = rdidx_r + 12'd1;
//
// The pointers are 12 bits and wrap mod 4096 by natural overflow, so the RTL
// needs no explicit bounds check and neither should the emulator.
static void
test_pointers_wrap_within_the_ring(void)
{
	pcm_reset();
	fill(USABLE, 0);

	int16_t buf[4096];
	pcm_write_rate(128);
	pcm_render(buf, 2000);

	unsigned before = state().fifo_cnt;
	check(before < (unsigned)USABLE, "rendering consumed part of the queue");

	fill(100, 0x80);
	struct pcm_debug_state s = state();
	check_eq(s.fifo_cnt, before + 100, "writes after the wrap are queued");
	check(s.fifo_wridx < PCM_FIFO_SIZE, "the write pointer stays in the ring");
	check(s.fifo_rdidx < PCM_FIFO_SIZE, "the read pointer stays in the ring");
}

// audio_fifo.v:42   if (rd_en && !empty) begin
//
// Reads are gated on !empty, so an empty FIFO advances nothing. The debug peek
// has no RTL counterpart -- it exists only for the debugger -- so what is
// pinned here is that it disturbs none of the state the RTL does define.
static void
test_debug_peek_consumes_nothing(void)
{
	pcm_reset();
	fill(10, 0x30);

	uint8_t seen[10];
	unsigned got = pcm_debug_peek_fifo(seen, 0, sizeof seen);
	check_eq(got, 10u, "peeking returns what was queued");
	check_eq(seen[0], 0x30u, "peeking starts at the read pointer");
	check_eq(seen[9], 0x39u, "and reads forward in order");
	check_eq(state().fifo_cnt, 10u, "peeking consumes nothing");
	check_eq(state().fifo_rdidx, 0u, "and does not move the read pointer");

	got = pcm_debug_peek_fifo(seen, 8, sizeof seen);
	check_eq(got, 2u, "peeking past the end stops at the queued data");
	check_eq(seen[0], 0x38u, "the offset is applied from the read pointer");

	check_eq(pcm_debug_peek_fifo(seen, 10, 4), 0u,
	         "an offset at the end of the queue returns nothing");
}

// pcm.v:60    sr_accum_r <= 0;                       // and the sample registers
// pcm.v:160   right_output_next = mode_stereo ? right_sample : left_sample;
//
// With nothing queued the sample state machine never leaves IDLE and the output
// registers hold. From reset those registers are zero, so rendering an empty
// FIFO produces silence rather than stale buffer contents.
static void
test_empty_fifo_renders_silence(void)
{
	pcm_reset();
	int16_t buf[64];
	memset(buf, 0x7F, sizeof buf);
	pcm_render(buf, 32);
	bool silent = true;
	for (int i = 0; i < 64; i++) {
		if (buf[i] != 0) {
			silent = false;
		}
	}
	check(silent, "rendering an empty FIFO writes silence");
}

int
main(void)
{
	test_reset_clears_pointers_and_registers();
	test_fifo_depth_is_one_less_than_its_memory();
	test_full_and_empty_status_bits();
	test_almost_empty_is_strictly_below_1024();
	test_ctrl_stores_mode_and_volume_only();
	test_ctrl_bit7_resets_the_fifo();
	test_rate_register_stores_the_raw_value();
	test_ctrl_bit6_is_ignored();
	test_no_loop_mode();
	test_pointers_wrap_within_the_ring();
	test_debug_peek_consumes_nothing();
	test_empty_fifo_renders_silence();
	return x16_test_summary("vera_pcm");
}