FPGA-Neural/hardware/v3/rtl/ddr_prefetch_mgr.v

`timescale 1ns/1ps

// ============================================================
// V3 -- ddr_prefetch_mgr.v: the DDRManager's real phase-1 deliverable
// (EXP-0083), implementing the user's own proposed idea -- "vorrei che
// orchestrator potesse 'prenotare' le letture future in RAM ... in modo
// da azzerare i tempi di attesa (o almeno ridurli al minimo)" -- scoped,
// per this project's own "one variable at a time" discipline and the
// validation plan docs/ARCHITECTURE_ANALYSIS.md S5.2 laid out, to a
// SINGLE slot's own activation-tile look-ahead first, before attempting
// a cross-slot/whole-Director-queue scheduler.
//
// WHAT THIS DOES: wraps act_tile_fetch.v (unmodified, reused as the
// "fetch exactly one tile" engine) with a depth-2 ping-pong buffer and a
// sequencer that issues the NEXT tile's fetch the INSTANT the fetch
// engine is free and that tile's buffer bank is free -- NOT waiting for
// packed_slot.v to have consumed the CURRENT tile first. This overlaps
// "fetching tile N+1" with "packed_slot.v consuming tile N", which the
// original per-tile req/wait loop (EXP-0079/0081) never did.
//
// WHAT THIS DOES NOT DO (disclosed, not glossed over): it does not
// change the real 1.24 GB/s physical DDR3 ceiling (S3.1 of the
// architecture doc) or the per-fetch latency of any SINGLE tile fetch --
// it only removes the small, real per-tile RE-REQUEST overhead (the
// S_TILEREQ pulse cycle + the S_OPERAND consume cycle packed_slot.v's
// own FSM previously spent NOT fetching, between one tile's data
// arriving and the next tile's fetch being issued). Given
// neural_processor_packed.v's own pipeline accepts one operand PER
// CYCLE once in NP_WAIT_OPERANDS (operand_ready is state-only, not
// gated on any internal pipeline stall), the real compute-side
// consumption cost per tile is ~1 cycle -- meaning this fix's real
// ceiling is bounded by that small per-tile overhead, not by hiding a
// large compute-bound stall. The real, measured improvement is reported
// in the EXP-0083 log entry, not assumed here.
//
// WHY A DOUBLE BUFFER (depth 2), not deeper: matches
// layer_weight_buffer.v's own proven ping-pong pattern in this
// codebase, and depth 2 is provably sufficient here -- the fetch
// sequencer can be at most 1 tile ahead of the consumer, since issuing
// tile N+2's fetch requires bank[(N+2)%2] == bank[N%2] to already be
// free, which only happens once tile N has been consumed. No unbounded
// lookahead is possible or attempted.
//
// WHY THIS IS TIMING-SAFE: bank selection for both the fill side
// (fetch_idx[0]) and the read side (consume_idx[0]) is a REGISTERED
// index bit, exactly the same "select known long before the data it
// gates" discipline act_tile_fetch.v's own header (EXP-0081) already
// established as safe -- never a bit racing live data. Requires its own
// real P&R re-check before being trusted at N>1 scale, per this
// project's standing practice (not assumed safe by analogy alone).
// ============================================================
module ddr_prefetch_mgr #(
    parameter DATA_WIDTH  = 8,
    parameter P_IN        = 8,
    parameter BURST_LEN   = 8,
    parameter ADDR_WIDTH  = 25   // word address, matches act_tile_fetch.v's own convention
)(
    input  wire clk,
    input  wire rst,

    // ---- job-level control (packed_slot.v issues this ONCE per job,
    // not once per tile -- the whole tile loop's lookahead is driven
    // internally from here) ----
    input  wire                        job_start,   // one-shot pulse
    input  wire [ADDR_WIDTH-1:0]       base_a,
    input  wire [ADDR_WIDTH-1:0]       base_b,
    input  wire [15:0]                 n_tiles,

    // ---- per-tile consumption interface (packed_slot.v side) ----
    // tile_valid is a LEVEL signal (unlike act_tile_fetch.v's one-cycle
    // `valid` pulse) -- it stays high as long as the current
    // consume-index's buffer bank holds unconsumed data, which may
    // already be true the cycle packed_slot.v asks, if the lookahead
    // fetch completed early. packed_slot.v pulses tile_consume once it
    // has latched data_a/data_b, which frees this bank for the next
    // lookahead fetch.
    output wire                              tile_valid,
    output wire signed [DATA_WIDTH*P_IN-1:0] data_a,
    output wire signed [DATA_WIDTH*P_IN-1:0] data_b,
    input  wire                              tile_consume, // one-shot pulse

    // ---- shared DDR3 controller port (identical shape to
    // act_tile_fetch.v's own -- this module is a pure passthrough
    // wrapper on this side, connects straight through to the inner
    // act_tile_fetch instance) ----
    output wire                     mem_active,
    input  wire                     mem_grant,
    output wire                     ctrl_req,
    output wire                     ctrl_wr,
    output wire [ADDR_WIDTH-1:0]    ctrl_addr,
    output wire [32*BURST_LEN-1:0]  ctrl_wdata,
    output wire [4*BURST_LEN-1:0]   ctrl_wmask,
    input  wire [32*BURST_LEN-1:0]  ctrl_rdata,
    input  wire                     ctrl_ready,
    input  wire                     ctrl_busy
);
    reg [ADDR_WIDTH-1:0] base_a_lat, base_b_lat;
    reg [15:0]            n_tiles_lat;
    reg [15:0]             fetch_idx, consume_idx;
    reg                     fetch_inflight;

    // ---- depth-2 ping-pong buffer ----
    reg signed [DATA_WIDTH*P_IN-1:0] bank_data_a [0:1];
    reg signed [DATA_WIDTH*P_IN-1:0] bank_data_b [0:1];
    reg [1:0] bank_valid;

    assign tile_valid = bank_valid[consume_idx[0]];
    assign data_a     = bank_data_a[consume_idx[0]];
    assign data_b     = bank_data_b[consume_idx[0]];

    // ---- inner fetch engine: act_tile_fetch.v, reused unmodified,
    // driven one tile at a time by this sequencer ----
    reg                      act_req;
    wire                     act_valid;
    wire signed [DATA_WIDTH*P_IN-1:0] act_data_a_w, act_data_b_w;

    act_tile_fetch #(
        .DATA_WIDTH(DATA_WIDTH), .P_IN(P_IN), .BURST_LEN(BURST_LEN), .ADDR_WIDTH(ADDR_WIDTH)
    ) u_act (
        .clk(clk), .rst(rst),
        .req(act_req), .base_a(base_a_lat), .base_b(base_b_lat),
        .tcnt(fetch_idx), .valid(act_valid), .data_a(act_data_a_w), .data_b(act_data_b_w),
        .mem_active(mem_active), .mem_grant(mem_grant),
        .ctrl_req(ctrl_req), .ctrl_wr(ctrl_wr), .ctrl_addr(ctrl_addr),
        .ctrl_wdata(ctrl_wdata), .ctrl_wmask(ctrl_wmask),
        .ctrl_rdata(ctrl_rdata), .ctrl_ready(ctrl_ready), .ctrl_busy(ctrl_busy)
    );

    // can_issue: the inner fetch engine is free, there is a next tile
    // left in this job, and that tile's destination bank has already
    // been consumed (or was never filled yet, at job start).
    wire can_issue = !fetch_inflight && (fetch_idx < n_tiles_lat) && !bank_valid[fetch_idx[0]];

    always @(posedge clk) begin
        if (rst) begin
            base_a_lat     <= {ADDR_WIDTH{1'b0}};
            base_b_lat     <= {ADDR_WIDTH{1'b0}};
            n_tiles_lat    <= 16'd0;
            fetch_idx      <= 16'd0;
            consume_idx    <= 16'd0;
            fetch_inflight <= 1'b0;
            act_req        <= 1'b0;
            bank_valid     <= 2'b00;
        end else begin
            act_req <= 1'b0;

            if (job_start) begin
                base_a_lat     <= base_a;
                base_b_lat     <= base_b;
                n_tiles_lat    <= n_tiles;
                fetch_idx      <= 16'd0;
                consume_idx    <= 16'd0;
                fetch_inflight <= 1'b0;
                bank_valid     <= 2'b00;
            end else begin
                if (can_issue) begin
                    act_req        <= 1'b1;
                    fetch_inflight <= 1'b1;
                end

                if (act_valid) begin
                    bank_data_a[fetch_idx[0]] <= act_data_a_w;
                    bank_data_b[fetch_idx[0]] <= act_data_b_w;
                    bank_valid[fetch_idx[0]]  <= 1'b1;
                    fetch_idx      <= fetch_idx + 16'd1;
                    fetch_inflight <= 1'b0;
                end

                if (tile_consume) begin
                    bank_valid[consume_idx[0]] <= 1'b0;
                    consume_idx <= consume_idx + 16'd1;
                end
            end
        end
    end
endmodule