// VERA PSG: the sixteen-voice sound generator behind $9F40-$9F7F.

//

// ORACLE (strength B): the VERA Verilog, fpga/source/audio/psg.v.

//

//   repo:   https://github.com/X16Community/vera-module

//   tag:    v48.0.1   (commit 6e8bea68)

//

// R48 for this file, where the PCM tests use R47. psg.v is the only audio

// source that differs between the two tags, and the emulator implements the R48

// form: vera_psg.c:122-123 XOR the saw and triangle waveforms with the inverted

// pulse width, which entered the RTL as a8135f32 (2024-10-21) and shipped in

// v48.0.1. R47 has the unmodulated waveforms. The emulator backported it in

// #290 on 2024-08-11, two months before the RTL change landed, which is why it

// reports 47.0.2 while behaving like 48 here. See tests/check_vera_version.py.

//

// Every expectation quotes the RTL line it rests on, so a claim can be checked

// without fetching the repo. tests/fetch_vera_rtl.py retrieves the sources.

//

// vera_psg.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_psg.h"

#include <string.h>

// Registers are four bytes per voice: two of frequency, one of volume and

// panning, one of pulse width and waveform.

#define R_FREQL(ch) ((ch) * 4 + 0)

#define R_FREQH(ch) ((ch) * 4 + 1)

#define R_VOL(ch)   ((ch) * 4 + 2)

#define R_WAVE(ch)  ((ch) * 4 + 3)

static struct psg_debug_channel

chan(int ch)

{

	struct psg_debug_channel c;

	memset(&c, 0, sizeof c);

	psg_debug_get_channel(ch, &c);

	return c;

}

// Drive one voice with everything needed to make sound, so a test can vary the

// single field it cares about.

static void

voice(int ch, uint16_t freq, uint8_t vol, uint8_t waveform, uint8_t pw)

{

	psg_writereg(R_FREQL(ch), freq & 0xFF);

	psg_writereg(R_FREQH(ch), freq >> 8);

	psg_writereg(R_VOL(ch), 0xC0 | (vol & 0x3F));   // left and right enabled

	psg_writereg(R_WAVE(ch), (uint8_t)(waveform << 6) | (pw & 0x3F));

}

// psg.v:126   lfsr_r <= 16'd1;                         // on reset

static void

test_reset_seeds_the_noise_lfsr(void)

{

	psg_writereg(R_FREQL(0), 0x34);

	psg_writereg(R_VOL(0), 0x3F);

	psg_reset();

	check_eq(psg_debug_get_noise_state(), 1u,

	         "reset seeds the noise LFSR to 1");

	check_eq(chan(0).freq, 0u, "reset clears the frequency");

	check_eq(chan(0).vol_raw, 0u, "reset clears the volume");

	check_eq(chan(0).phase, 0u, "reset clears the phase accumulator");

	check_eq(psg_debug_get_reg(R_FREQL(0)), 0u, "reset clears the register shadow");

}

// psg.v:39-44   cur_freq       = cur_channel_attr_r[15:0];

//               cur_volume     = cur_channel_attr_r[21:16];

//               cur_left_en    = cur_channel_attr_r[22];

//               cur_right_en   = cur_channel_attr_r[23];

//               cur_pulsewidth = cur_channel_attr_r[29:24];

//               cur_waveform   = cur_channel_attr_r[31:30];

//

// Four attribute bytes per voice, so byte 2 carries volume in bits 5:0 with

// left on bit 6 and right on bit 7, and byte 3 carries pulse width in bits 5:0

// with the waveform in bits 7:6.

static void

test_register_decode(void)

{

	psg_reset();

	psg_writereg(R_FREQL(3), 0x34);

	psg_writereg(R_FREQH(3), 0x12);

	check_eq(chan(3).freq, 0x1234u, "the two frequency bytes form a 16-bit word");

	psg_writereg(R_VOL(3), 0x80 | 0x2A);

	check_eq(chan(3).vol_raw, 0x2Au, "volume is bits 5:0");

	check(chan(3).right, "bit 7 enables right");

	check(!chan(3).left, "bit 6 alone controls left");

	psg_writereg(R_VOL(3), 0x40 | 0x2A);

	check(chan(3).left, "bit 6 enables left");

	check(!chan(3).right, "and bit 7 alone controls right");

	psg_writereg(R_WAVE(3), 0x80 | 0x15);

	check_eq(chan(3).pw, 0x15u, "pulse width is bits 5:0");

	check_eq(chan(3).waveform, (uint32_t)PSG_WF_TRIANGLE, "waveform is bits 7:6");

}

// psg.v:26-28   dpram #(.ADDR_WIDTH(6) ...) audio_attr_ram(

//                   .rd_addr({cur_channel_r, cur_channel_byte_r[1:0]}),

//

// A 6-bit address: sixteen voices of four bytes, and nothing beyond. The

// emulator masks the register index to match, so a write past the end lands

// back at the start rather than running off the array.

static void

test_register_index_wraps_at_64(void)

{

	psg_reset();

	psg_writereg(0, 0x11);

	psg_writereg(64, 0x22);   // wraps onto register 0

	check_eq(chan(0).freq & 0xFF, 0x22u, "register 64 wraps onto register 0");

	psg_writereg(65, 0x33);

	check_eq(chan(0).freq >> 8, 0x33u, "register 65 wraps onto register 1");

	psg_writereg(255, 0x44);  // 255 & 0x3f == 63

	check_eq(chan(15).pw, 0x04u, "register 255 wraps onto register 63");

	check_eq(chan(15).waveform, (uint32_t)PSG_WF_SAWTOOTH, "and decodes there normally");

}

// psg.v:47-48   // cur_volume_log = cur_volume * 4                     ; cur_volume < 4

//               //                = 511 * exp2((cur_volume - 63) / 12) ; cur_volume >= 4

//

// Two regimes: linear below 4, then 0.5 dB per step. The joint at 4 is the

// interesting part, and the ends are fixed points.

static void

test_volume_curve(void)

{

	psg_reset();

	const struct { uint8_t raw; uint16_t want; } cases[] = {

		{0, 0}, {1, 4}, {2, 8}, {3, 12},   // linear regime

		{4, 16},                            // first logarithmic step

		{63, 511},                          // full scale

	};

	for (unsigned i = 0; i < sizeof cases / sizeof cases[0]; i++) {

		psg_writereg(R_VOL(0), 0xC0 | cases[i].raw);

		check_eq(chan(0).vol_lut, cases[i].want, "volume maps through the curve");

	}

}

// psg.v:140   new_phase = (cur_left_en | cur_right_en) ? (cur_phase + cur_freq) : 17'd0;

//

// A silenced voice does not merely stop being heard, it is held at phase zero.

// So unmuting always restarts from the beginning of the waveform rather than

// wherever the voice would have been -- worth pinning because it is the sort of

// detail an implementation "tidies up" into a plain gate on the output.

static void

test_phase_is_held_at_zero_while_silent(void)

{

	psg_reset();

	int16_t buf[256];

	// 0x0700 over 64 samples does not land back on a multiple of the 17-bit

	// range, so "advanced" is distinguishable from "reset". 0x0800 would wrap

	// to exactly zero and the check would pass for the wrong reason.

	voice(0, 0x0700, 63, PSG_WF_SAWTOOTH, 0x20);

	psg_render(buf, 64);

	check(chan(0).phase != 0, "an audible voice advances its phase");

	// Clear both pan bits, keeping frequency and volume.

	psg_writereg(R_VOL(0), 0x3F);

	psg_render(buf, 64);

	check_eq(chan(0).phase, 0u, "a voice with neither side enabled resets to phase zero");

	psg_writereg(R_VOL(0), 0xC0 | 0x3F);

	psg_render(buf, 64);

	check(chan(0).phase != 0, "and runs again once a side is re-enabled");

}

// psg.v:124-130   always @(posedge clk ...) lfsr_r <=

//                     {lfsr_r[14:0], lfsr_r[1] ^ lfsr_r[2] ^ lfsr_r[4] ^ lfsr_r[15]};

//

// A 16-bit Fibonacci LFSR with taps at 1, 2, 4 and 15, shifting left, seeded to

// 1. The tap set is the part worth pinning: a wrong one still produces

// plausible noise, so only the exact sequence tells them apart.

//

// The rate is a modelling choice rather than something the RTL fixes at this

// granularity. In hardware the LFSR advances every system clock while the state

// machine walks the voices in turn (psg.v:180-188), which is why two voices

// latching in the same sample see different values. The emulator reproduces

// that by stepping it once per voice, so sixteen times per rendered sample

// (vera_psg.c:105-109). That is an approximation of a clock-rate process at

// sample resolution, and it is what this checks.

static void

test_noise_lfsr_sequence(void)

{

	psg_reset();

	check_eq(psg_debug_get_noise_state(), 1u, "seeded to 1");

	int16_t buf[8];

	uint16_t expect = psg_debug_get_noise_state();

	for (int sample = 0; sample < 8; sample++) {

		for (int voice_step = 0; voice_step < PSG_NUM_CHANNELS; voice_step++) {

			unsigned bit = ((expect >> 1) ^ (expect >> 2) ^ (expect >> 4) ^ (expect >> 15)) & 1;

			expect = (uint16_t)((expect << 1) | bit);

		}

		psg_render(buf, 1);

		check_eq(psg_debug_get_noise_state(), expect,

		         "the LFSR follows taps 1, 2, 4 and 15, once per voice");

	}

}

// psg.v:142-143   do_noise_sample = cur_phase[16] && !new_phase[16];

//                 new_noise = do_noise_sample ? noise_value_r : cur_noise;

// psg.v:123       noise_value_r = lfsr_r[6:1];

//

// A noise voice does not follow the LFSR sample by sample. It latches six bits

// of it only when the phase accumulator's top bit falls, so frequency controls

// the rate of new noise values while the LFSR runs on underneath.

static void

test_noise_is_latched_on_phase_wrap(void)

{

	psg_reset();

	int16_t buf[8];

	// With frequency 0x0800 the 17-bit phase advances 0x800 per sample, so bit

	// 16 rises at sample 32 and falls when the accumulator wraps at sample 64.

	// That is exactly one latch in the first 64 samples, at a known point.

	voice(0, 0x0800, 63, PSG_WF_NOISE, 0);

	unsigned changes = 0;

	int changed_at = -1;

	uint16_t prev = chan(0).noiseval;

	for (int sample = 1; sample <= 64; sample++) {

		uint16_t lfsr_before = psg_debug_get_noise_state();

		psg_render(buf, 1);

		check(psg_debug_get_noise_state() != lfsr_before,

		      "the LFSR advances on every sample");

		uint16_t now = chan(0).noiseval;

		if (now != prev) {

			changes++;

			changed_at = sample;

			prev = now;

		}

	}

	check_eq(changes, 1u, "the voice latches noise once per phase wrap");

	check_eq((uint32_t)changed_at, 64u, "and does so when the accumulator wraps");

	check(chan(0).noiseval <= 0x3F, "the latched value is six bits");

}

// psg.v:168-173   2'b00: signal = signal_pw;

//                 2'b01: signal = signal_saw;

//                 2'b10: signal = signal_triangle;

//                 2'b11: signal = signal_noise;

static void

test_waveform_codes(void)

{

	psg_reset();

	const uint8_t codes[] = {PSG_WF_PULSE, PSG_WF_SAWTOOTH, PSG_WF_TRIANGLE, PSG_WF_NOISE};

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

		psg_writereg(R_WAVE(1), (uint8_t)(codes[i] << 6));

		check_eq(chan(1).waveform, codes[i], "the waveform code round-trips");

	}

}

// Render a voice from reset and report whether anything came out differently.

static bool

renders_same(uint8_t waveform, uint8_t pw_a, uint8_t pw_b)

{

	int16_t a[256], b[256];

	psg_reset();

	voice(0, 0x0400, 63, waveform, pw_a);

	psg_render(a, 128);

	psg_reset();

	voice(0, 0x0400, 63, waveform, pw_b);

	psg_render(b, 128);

	return memcmp(a, b, sizeof a) == 0;

}

// psg.v:162-164   signal_pw       = (cur_phase[16:10] > {1'b0, cur_pulsewidth}) ? 6'd0 : 6'd63;

//                 signal_saw      = cur_phase[16:11] ^ ~cur_pulsewidth[5:0];

//                 signal_triangle = (cur_phase[16] ? ~cur_phase[15:10] : cur_phase[15:10])

//                                   ^ ~cur_pulsewidth[5:0];

//

// This is the R47/R48 divide, and the reason this file is pinned to R48. In R47

// saw and triangle read the phase directly and ignore the pulse width entirely;

// in R48 both are XORed with its complement, so the field shapes all three

// non-noise waveforms rather than only the pulse.

//

// Testing that the output *changes* with pulse width is what separates the two

// revisions, and it does so without depending on the exact sample values.

static void

test_pulse_width_shapes_saw_and_triangle(void)

{

	check(!renders_same(PSG_WF_PULSE, 0x10, 0x30),

	      "pulse width changes the pulse waveform");

	check(!renders_same(PSG_WF_SAWTOOTH, 0x00, 0x3F),

	      "pulse width changes the sawtooth (R48; R47 ignores it)");

	check(!renders_same(PSG_WF_TRIANGLE, 0x00, 0x3F),

	      "pulse width changes the triangle (R48; R47 ignores it)");

	// The complement is what is XORed in, so a full-scale pulse width

	// contributes nothing and leaves the plain waveform behind.

	check(renders_same(PSG_WF_SAWTOOTH, 0x3F, 0x3F),

	      "the same pulse width gives the same sawtooth");

}

// psg.v:175   signed_signal = signal ^ 6'h20;

//

// The waveform is generated unsigned and converted by flipping its top bit, so

// silence sits at the middle of the range rather than at zero. A voice at

// volume zero must still produce exactly nothing.

static void

test_silence_at_zero_volume(void)

{

	psg_reset();

	int16_t buf[128];

	memset(buf, 0x7F, sizeof buf);

	voice(0, 0x0400, 0, PSG_WF_SAWTOOTH, 0x20);

	psg_render(buf, 64);

	bool silent = true;

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

		if (buf[i] != 0) {

			silent = false;

		}

	}

	check(silent, "volume zero renders exact silence");

}

int

main(void)

{

	test_reset_seeds_the_noise_lfsr();

	test_register_decode();

	test_register_index_wraps_at_64();

	test_volume_curve();

	test_phase_is_held_at_zero_while_silent();

	test_noise_lfsr_sequence();

	test_noise_is_latched_on_phase_wrap();

	test_waveform_codes();

	test_pulse_width_shapes_saw_and_triangle();

	test_silence_at_zero_volume();

	return x16_test_summary("vera_psg");

}