// retroDE_ps2 — tb_platform_video_stub
//
// Milestone A integration: gs_stub → platform_video_stub. Verifies that a
// BGCOLOR write at the GS privileged-register port propagates into the
// raster output, that hsync/vsync behave sensibly, and that the platform
// emits one EV_MODE trace per completed frame.
//
// Uses tiny timing overrides so each frame is ~112 cycles (vs. ~420k for
// default VGA 640x480). Turnaround stays fast while the full active/front/
// sync/back-porch structure is still exercised.
//
// Plan ref: docs/stub_module_plan.md. Milestone A ref:
//   docs/decisions/0004-first-visible-milestone.md.

`timescale 1ns/1ps

module tb_platform_video_stub;

    // Tiny timing. Frame = H_TOTAL * V_TOTAL = 14 * 8 = 112 cycles.
    localparam int H_ACTIVE = 8;
    localparam int H_FRONT  = 2;
    localparam int H_SYNC   = 2;
    localparam int H_BACK   = 2;
    localparam int V_ACTIVE = 4;
    localparam int V_FRONT  = 1;
    localparam int V_SYNC   = 2;
    localparam int V_BACK   = 1;

    logic clk;
    logic rst_n;

    initial clk = 1'b0;
    always #5 clk = ~clk;

    // ------------------------------------------------------------------
    // gs_stub
    // ------------------------------------------------------------------

    logic        gs_reg_wr_en;
    logic [15:0] gs_reg_wr_addr;
    logic [63:0] gs_reg_wr_data;

    logic [7:0]  bg_r, bg_g, bg_b;

    logic                  gs_ev_valid;
    trace_pkg::subsys_e    gs_ev_subsys;
    trace_pkg::event_e     gs_ev_event;
    logic [63:0]           gs_ev_arg0, gs_ev_arg1, gs_ev_arg2, gs_ev_arg3;
    logic [31:0]           gs_ev_flags;

    gs_stub u_gs (
        .clk(clk), .rst_n(rst_n),
        .reg_wr_en(gs_reg_wr_en), .reg_wr_addr(gs_reg_wr_addr),
        .reg_wr_data(gs_reg_wr_data),
        .gif_reg_wr_en(1'b0), .gif_reg_num(8'd0), .gif_reg_data(64'd0),
        .prim_q(), .rgbaq_q(), .xyz2_q(), .xyzf2_q(), .frame_1_q(), .zbuf_1_q(),
        .prim_complete(), .prim_complete_count(),
        .prim_v0_q(), .prim_v1_q(), .prim_v2_q(),
        .prim_color_q(),
        .prim_color_v0_q(), .prim_color_v1_q(), .prim_color_v2_q(),
        .prim_v0_decoded_q(), .prim_v1_decoded_q(), .prim_v2_decoded_q(),
        .prim_v0_color_decoded_q(), .prim_v1_color_decoded_q(), .prim_v2_color_decoded_q(),
        .pixel_emit(), .pixel_emit_count(),
        .pixel_x_q(), .pixel_y_q(),
        .pixel_color_q(),
        .pixel_fbp_q(), .pixel_fbw_q(), .pixel_psm_q(),
        .pixel_fb_addr_q(),
        .raster_pixel_emit(), .raster_pixel_emit_count(),
        .raster_pixel_x_q(), .raster_pixel_y_q(),
        .raster_pixel_color_q(),
        .raster_pixel_fb_addr_q(),
        .raster_active(), .raster_overflow(),
        .raster_degenerate(),
        .bg_r(bg_r), .bg_g(bg_g), .bg_b(bg_b),
        .ev_valid(gs_ev_valid), .ev_subsys(gs_ev_subsys), .ev_event(gs_ev_event),
        .ev_arg0(gs_ev_arg0), .ev_arg1(gs_ev_arg1),
        .ev_arg2(gs_ev_arg2), .ev_arg3(gs_ev_arg3),
        .ev_flags(gs_ev_flags)
    );

    // ------------------------------------------------------------------
    // platform_video_stub
    // ------------------------------------------------------------------

    logic       hsync, vsync, de;
    logic [7:0] r, g, b;

    logic                  plat_ev_valid;
    trace_pkg::subsys_e    plat_ev_subsys;
    trace_pkg::event_e     plat_ev_event;
    logic [63:0]           plat_ev_arg0, plat_ev_arg1, plat_ev_arg2, plat_ev_arg3;
    logic [31:0]           plat_ev_flags;

    platform_video_stub #(
        .H_ACTIVE(H_ACTIVE), .H_FRONT(H_FRONT), .H_SYNC(H_SYNC), .H_BACK(H_BACK),
        .V_ACTIVE(V_ACTIVE), .V_FRONT(V_FRONT), .V_SYNC(V_SYNC), .V_BACK(V_BACK)
    ) u_plat (
        .clk(clk), .rst_n(rst_n),
        .bg_r(bg_r), .bg_g(bg_g), .bg_b(bg_b),
        .hsync(hsync), .vsync(vsync), .de(de),
        .r(r), .g(g), .b(b),
        .ev_valid(plat_ev_valid), .ev_subsys(plat_ev_subsys), .ev_event(plat_ev_event),
        .ev_arg0(plat_ev_arg0), .ev_arg1(plat_ev_arg1),
        .ev_arg2(plat_ev_arg2), .ev_arg3(plat_ev_arg3),
        .ev_flags(plat_ev_flags)
    );

    // ------------------------------------------------------------------
    // Trace sinks (one per subsystem)
    // ------------------------------------------------------------------

    trace_sink_stub #(.FILENAME("milestone_a_gs.trace"), .SINK_LABEL("gs"))
        u_trace_gs (
            .clk(clk), .rst_n(rst_n),
            .ev_valid(gs_ev_valid), .ev_subsys(gs_ev_subsys), .ev_event(gs_ev_event),
            .ev_arg0(gs_ev_arg0), .ev_arg1(gs_ev_arg1),
            .ev_arg2(gs_ev_arg2), .ev_arg3(gs_ev_arg3),
            .ev_flags(gs_ev_flags)
        );

    trace_sink_stub #(.FILENAME("milestone_a_plat.trace"), .SINK_LABEL("plat"))
        u_trace_plat (
            .clk(clk), .rst_n(rst_n),
            .ev_valid(plat_ev_valid), .ev_subsys(plat_ev_subsys), .ev_event(plat_ev_event),
            .ev_arg0(plat_ev_arg0), .ev_arg1(plat_ev_arg1),
            .ev_arg2(plat_ev_arg2), .ev_arg3(plat_ev_arg3),
            .ev_flags(plat_ev_flags)
        );

    // ------------------------------------------------------------------
    // Checkers
    // ------------------------------------------------------------------

    int  active_pixels_seen;
    int  frame_events;
    int  hsync_pulses;
    int  vsync_pulses;
    int  errors;

    logic hsync_d;
    logic vsync_d;

    initial begin
        active_pixels_seen = 0;
        frame_events       = 0;
        hsync_pulses       = 0;
        vsync_pulses       = 0;
        errors             = 0;
        hsync_d            = 1'b1;
        vsync_d            = 1'b1;
    end

    // Every active pixel must equal the current bg_{r,g,b}.
    always_ff @(posedge clk) begin
        if (rst_n && de) begin
            active_pixels_seen <= active_pixels_seen + 1;
            if (r !== bg_r || g !== bg_g || b !== bg_b) begin
                $error("[tb_platform_video_stub] pixel mismatch: rgb=(%02h,%02h,%02h) bg=(%02h,%02h,%02h)",
                       r, g, b, bg_r, bg_g, bg_b);
                errors <= errors + 1;
            end
        end
    end

    // Count sync pulses by falling edges (active-low default).
    always_ff @(posedge clk) begin
        hsync_d <= hsync;
        vsync_d <= vsync;
        if (rst_n) begin
            if (hsync_d && !hsync) hsync_pulses <= hsync_pulses + 1;
            if (vsync_d && !vsync) vsync_pulses <= vsync_pulses + 1;
        end
    end

    // Count frame-completion events from platform trace.
    always_ff @(posedge clk) begin
        if (rst_n && plat_ev_valid && plat_ev_event == trace_pkg::EV_MODE) begin
            frame_events <= frame_events + 1;
        end
    end

    // ------------------------------------------------------------------
    // Stimulus: four frame windows — one at the reset-default mid-grey,
    // then three BGCOLOR writes (red, green, blue).
    // ------------------------------------------------------------------

    task automatic write_bgcolor(input logic [23:0] rgb);
        @(negedge clk);
        gs_reg_wr_en   = 1'b1;
        gs_reg_wr_addr = 16'h00E0;
        gs_reg_wr_data = {40'd0, rgb};
        @(negedge clk);
        gs_reg_wr_en   = 1'b0;
        gs_reg_wr_addr = 16'd0;
        gs_reg_wr_data = 64'd0;
    endtask

    initial begin
        rst_n          = 1'b0;
        gs_reg_wr_en   = 1'b0;
        gs_reg_wr_addr = 16'd0;
        gs_reg_wr_data = 64'd0;

        repeat (4) @(posedge clk);
        rst_n = 1'b1;

        // Frame 0: default mid-grey from gs_stub reset value.
        repeat (120) @(posedge clk);

        // Frame 1: primary-red test.
        write_bgcolor(24'hFF_0000);
        repeat (120) @(posedge clk);

        // Frame 2: primary-green test.
        write_bgcolor(24'h00_FF00);
        repeat (120) @(posedge clk);

        // Frame 3: primary-blue test.
        write_bgcolor(24'h00_00FF);
        repeat (120) @(posedge clk);

        // ------------------------------------------------------------------
        $display("[tb_platform_video_stub] frames=%0d active_pixels=%0d hsync_pulses=%0d vsync_pulses=%0d errors=%0d",
                 frame_events, active_pixels_seen, hsync_pulses, vsync_pulses, errors);

        if (frame_events < 3)
            $error("[tb_platform_video_stub] expected >= 3 frame events, got %0d", frame_events);
        if (active_pixels_seen < (3 * H_ACTIVE * V_ACTIVE))
            $error("[tb_platform_video_stub] expected >= %0d active pixels, got %0d",
                   3 * H_ACTIVE * V_ACTIVE, active_pixels_seen);
        if (vsync_pulses < 3)
            $error("[tb_platform_video_stub] expected >= 3 vsync pulses, got %0d", vsync_pulses);

        if (errors == 0 && frame_events >= 3 && vsync_pulses >= 3)
            $display("[tb_platform_video_stub] PASS");
        else
            $display("[tb_platform_video_stub] FAIL");

        $finish;
    end

    initial begin
        #200000;
        $error("[tb_platform_video_stub] timeout");
        $finish;
    end

endmodule : tb_platform_video_stub
