cpu5.sv

// the top level cpu
module cpu5
   #(
   parameter CACHE_ENTRIES = 8,                       // how many entries in the cache
   parameter CACHE_TAGSZ = 32,                        // tag bits - entire address
   parameter CACHE_ADDR_LEFT=$clog2(CACHE_ENTRIES)-1  // log2 of #of entries
   )
   (
   output logic      halt,      // halt signal to end simulation
   output logic      exception, // the exception interupt signal

   input             clk,  // system clock
   input             rst_  // system reset
   );

   `include "cpu_params.vh"

   // ═══════════════════════════════════════════════════════════════
   // STAGE 1: Instruction Fetch (IF) Signals
   // ═══════════════════════════════════════════════════════════════
   logic [BITS-1:0]            pc_addr;      // current address
   logic [BITS-1:0]            i_mem_rdata;  // instruction memory read data
   logic [BITS-1:0]            instr_word;   // value fed into instr_reg

   // ═══════════════════════════════════════════════════════════════
   // CACHE Signals (between i_memory and instr_reg)
   // ═══════════════════════════════════════════════════════════════
   logic [BITS-1:0]            cache_data;       // instruction from cache
   logic                       cache_hit;        // cache hit signal
   logic                       cache_full;       // cache is full
   logic                       cache_read;       // cache read enable
   logic                       cache_write_;     // cache write enable
   logic [CACHE_ADDR_LEFT:0]   cache_w_addr;     // cache write address
   logic                       new_valid;        // cache valid bit
   logic                       cache_stall;      // cache stall signal
   logic                       branch_or_jump;   // control hazard signal

   // ═══════════════════════════════════════════════════════════════
   // STAGE 2: Instruction Decode (ID) Signals
   // ═══════════════════════════════════════════════════════════════
   logic [REG_ADDR_LEFT:0]     r1_addr;      // register file read addr 1
   logic [REG_ADDR_LEFT:0]     r2_addr;      // register file read addr 2
   logic [REG_ADDR_LEFT:0]     waddr;        // register file write addr
   logic [SHIFT_BITS-1:0]      shamt;        // shift amount
   logic [OP_BITS-1:0]         alu_op;       // alu operation
   logic [IMM_LEFT-1:0]        imm;          // immediate data
   logic [JMP_LEFT:0]          addr;         // jump address to program counter
   logic                       rw_;          // register file read write signal
   logic                       mem_rw_;      // data memory read write signal
   logic                       sel_mem;      // select the output from the memory
   logic                       alu_imm;      // use immediate data for the alu
   logic                       signed_ext;   // whether or not to extend the sign bit
   logic [ 3:0]                byte_en;      // byte enables
   logic                       jmp;          // doing a jump
   logic                       breq;         // doing a branch on equal
   logic                       brne;         // doing o branch o not equal
   logic                       jal;          // doing a jump and link
   logic                       jreg;         // jumping to an address in a register
   logic                       stall;        // stall signal for branches/jumps
   logic                       halt_decoded; // halt signal from instruction decode (Stage 2)
   logic [BITS-1:0]            r1_data;      // register file read data 1
   logic [BITS-1:0]            r2_data;      // register file read data 2
   logic [BITS-1:0]            sign_ext_imm; // immediate data that has been sign extended
   logic                       equal;        // values were equal for branches
   logic                       not_equal;    // values were not equal for branches

   // LL/SC signals (Stage 2)
   logic                       ll;           // LL instruction
   logic                       sc;           // SC instruction
   logic                       atomic;       // atomic operation (SC)
   logic                       load_link_;   // load and link (LL)
   logic                       check_link;   // check link validity for SC

   // ═══════════════════════════════════════════════════════════════
   // STAGE 3: Execute (EX) Signals
   // ═══════════════════════════════════════════════════════════════
   logic [BITS-1:0]            r1_data_s3;
   logic [BITS-1:0]            r2_data_s3;
   logic [BITS-1:0]            sign_ext_imm_s3;
   logic [REG_ADDR_LEFT:0]     r1_addr_s3;
   logic [REG_ADDR_LEFT:0]     r2_addr_s3;
   logic [REG_ADDR_LEFT:0]     waddr_s3;
   logic [SHIFT_BITS-1:0]      shamt_s3;
   logic [OP_BITS-1:0]         alu_op_s3;
   logic                       alu_imm_s3;
   logic                       rw_s3;
   logic                       mem_rw_s3;
   logic                       sel_mem_s3;
   logic [3:0]                 byte_en_s3;
   logic                       halt_s3;
   logic                       atomic_s3;
   logic                       load_link_s3;
   logic                       check_link_s3;
   logic [BITS-1:0]            alu_out;      // alu output
   logic [BITS-1:0]            alu_in_1;     // alu input 1
   logic [BITS-1:0]            alu_in_2;     // alu input 2

   // ═══════════════════════════════════════════════════════════════
   // STAGE 4: Memory (MEM) Signals
   // ═══════════════════════════════════════════════════════════════
   logic [BITS-1:0]            alu_out_s4;
   logic [BITS-1:0]            r2_data_s4;
   logic [REG_ADDR_LEFT:0]     waddr_s4;
   logic                       rw_s4;
   logic                       mem_rw_s4;
   logic                       sel_mem_s4;
   logic [3:0]                 byte_en_s4;
   logic                       halt_s4;
   logic                       atomic_s4;
   logic                       load_link_s4;
   logic                       check_link_s4;
   logic [BITS-1:0]            d_mem_rdata;  // data memory read data
   logic                       link_rw_;     // SC write control
   logic                       use_mem_rw_;  // Final memory write signal

   // LL/SC state machine signals
   logic [BITS-1:0]            link_addr;    // Address from LL
   logic                       link_valid;   // Link active?

   // ═══════════════════════════════════════════════════════════════
   // STAGE 5: Write Back (WB) Signals
   // ═══════════════════════════════════════════════════════════════
   logic [BITS-1:0]            alu_out_s5;
   logic [BITS-1:0]            d_mem_rdata_s5;
   logic [REG_ADDR_LEFT:0]     waddr_s5;
   logic                       rw_s5;
   logic                       sel_mem_s5;
   logic [3:0]                 byte_en_s5;
   logic                       halt_s5;
   logic                       atomic_s5;
   logic                       link_rw_s5;
   logic                       sc_success_s5;  // SC success result pipelined to WB
   logic [BITS-1:0]            reg_wdata;      // data to write to the register file


   // ═══════════════════════════════════════════════════════════════
   // Forwarding and Stall Signals
   // ═══════════════════════════════════════════════════════════════
   logic                      r1_fwd_s4;   // Forward from Stage 4 to r1 (Stage 3)
   logic                      r2_fwd_s4;   // Forward from Stage 4 to r2 (Stage 3)
   logic                      r1_fwd_s5;   // Forward from Stage 5 to r1 (Stage 3)
   logic                      r2_fwd_s5;   // Forward from Stage 5 to r2 (Stage 3)
   logic                      r1_fwd_s6;   // Forward from Stage 5 to r1 (Stage 2)
   logic                      r2_fwd_s6;   // Forward from Stage 5 to r2 (Stage 2)
   logic                      j_fwd_s4;    // Forward from Stage 4 to PC for JR
   logic                      j_fwd_s5;    // Forward from Stage 5 to PC for JR
   logic                      b_r1_fwd_s4; // Forward from Stage 4 to r1 for branches
   logic                      b_r2_fwd_s4; // Forward from Stage 4 to r2 for branches
   logic                      b_r1_fwd_s5; // Forward from Stage 5 to r1 for branches
   logic                      b_r2_fwd_s5; // Forward from Stage 5 to r2 for branches
   logic                      stall_pipe;  // Stall signal for load-use hazard

   // Forwarded data for Stage 2 (before entering pipeline)
   logic [BITS-1:0]           r1_data_fwd;
   logic [BITS-1:0]           r2_data_fwd;

   // ═══════════════════════════════════════════════════════════════
   // STAGE 1: INSTRUCTION FETCH (IF)
   // ═══════════════════════════════════════════════════════════════

   // Feed instruction from cache (not directly from memory)
   assign instr_word = cache_data;
   
   // Cache control: detect branches and jumps (only when ACTUALLY taken)
   assign branch_or_jump = jmp | jal | jreg | (breq & equal) | (brne & not_equal);

   // the program counter
   pc #(.BITS(BITS) ) pc (
          .pc_addr(pc_addr), .clk(clk), .addr(addr), .rst_(rst_),
          .jmp(jmp), .load_instr(!halt_decoded), .sign_ext_imm(sign_ext_imm),
          .equal(equal), .not_equal(not_equal), .breq(breq), .brne(brne),
          .jreg(jreg), .r1_data(r1_data), .stall_pipe(stall_pipe),
          .j_fwd_s4(j_fwd_s4), .j_fwd_s5(j_fwd_s5),
          .alu_out_s4(alu_out_s4), .reg_wdata(reg_wdata),
          .cache_stall(cache_stall) );

   // the instruction memory
   memory #( .BITS(BITS), .WORDS(I_MEM_WORDS), .BASE_ADDR(I_MEM_BASE_ADDR) ) i_memory(
       .rdata(i_mem_rdata), .clk(clk), .wdata(32'b0), .rw_(1'b1),
       .addr(pc_addr), .byte_en(4'hF) );

   // Cache control state machine
   ca_ctrl #(
      .CACHE_ENTRIES(CACHE_ENTRIES),
      .CACHE_ADDR_LEFT(CACHE_ADDR_LEFT)
   ) ca_ctrl (
      .cache_read(cache_read),
      .cache_write_(cache_write_),
      .cache_w_addr(cache_w_addr),
      .new_valid(new_valid),
      .cache_stall(cache_stall),
      .cache_hit(cache_hit),
      .cache_full(cache_full),
      .branch_or_jump(branch_or_jump),
      .clk(clk),
      .rst_(rst_)
   );

   // Instruction cache (CAM)
   cam2 #(
      .WORDS(CACHE_ENTRIES),
      .BITS(BITS),
      .TAG_SZ(CACHE_TAGSZ)
   ) cam (
      .cache_data(cache_data),
      .cache_hit(cache_hit),
      .cache_full(cache_full),
      .check_tag(pc_addr),           // Tag is the full PC address
      .read(cache_read),
      .write_(cache_write_),
      .w_addr(cache_w_addr),
      .wdata(i_mem_rdata),           // Data from instruction memory
      .new_tag(pc_addr),             // Tag for new entry
      .new_valid(new_valid),
      .clk(clk),
      .rst_(rst_)
   );

   // ═══════════════════════════════════════════════════════════════
   // STAGE 2: INSTRUCTION DECODE (ID) & REGISTER FILE READ
   // ═══════════════════════════════════════════════════════════════

   // the instruction register - includes instruction decode
   logic load_byte, load_half;

   instr_reg #( .BITS(BITS), .REG_WORDS(REG_WORDS) ) instr_reg (
       .r1_addr(r1_addr), .r2_addr(r2_addr), .waddr(waddr),
       .shamt(shamt), .alu_op(alu_op), .imm(imm), .addr(addr),
       .rw_(rw_), .sel_mem(sel_mem), .alu_imm(alu_imm),
       .signed_ext(signed_ext), .byte_en(byte_en), .halt(halt_decoded),
       .mem_rw_(mem_rw_), .jmp(jmp), .breq(breq), .brne(brne),
       .jal(jal), .jreg(jreg), .exception(exception), .stall(stall),
       .load_byte(load_byte), .load_half(load_half),
       .clk(clk), .load_instr(1'b1), .mem_data(instr_word), .rst_(rst_),
       .equal(equal), .not_equal(not_equal),
       .ll(ll), .sc(sc), .stall_pipe(stall_pipe),
       .cache_stall(cache_stall), .halt_in(halt_decoded) );

   // Sign-extend the 16-bit immediate value to 32 bits
   assign sign_ext_imm = signed_ext ? {{16{imm[15]}}, imm} : {{16{1'b0}}, imm};

   // Map LL/SC to professor's signal names
   assign load_link_ = ll;      // LL instruction
   assign atomic = sc;          // SC instruction (atomic operation)
   assign check_link = sc;      // Check link when doing SC

   // the register file
   regfile #( .WORDS(REG_WORDS), .BITS(BITS) ) regfile(
       .r1_data(r1_data), .r2_data(r2_data), .clk(clk), .rst_(rst_),
       .rw_(rw_s5), .wdata(reg_wdata), .waddr(waddr_s5),
       .r1_addr(r1_addr), .r2_addr(r2_addr), .byte_en(byte_en_s5),
       .pc_addr(pc_addr), .jal(jal) );

   // ═══════════════════════════════════════════════════════════════
   // Three-Stage Forwarding Mux (Stage 2 - before entering pipeline)
   // ═══════════════════════════════════════════════════════════════

   // Forward reg_wdata from Stage 5 to Stage 2 if needed
   assign r1_data_fwd = r1_fwd_s6 ? reg_wdata : r1_data;
   assign r2_data_fwd = r2_fwd_s6 ? reg_wdata : r2_data;

   // ═══════════════════════════════════════════════════════════════
   // PIPELINE REGISTER: ID/EX (Stage 2 → Stage 3)
   // ═══════════════════════════════════════════════════════════════
   pipe_id_ex #(
      .BITS(BITS),
      .REG_ADDR_BITS(REG_ADDR_LEFT+1),
      .SHIFT_BITS(SHIFT_BITS),
      .OP_BITS(OP_BITS)
   ) pipe_id_ex_inst (
      .clk(clk),
      .rst_(rst_),
      .stall_pipe(stall_pipe),    // Stall signal for bubble insertion
      .r1_data(r1_data_fwd),      // Use forwarded data
      .r2_data(r2_data_fwd),      // Use forwarded data
      .r1_addr(r1_addr),
      .r2_addr(r2_addr),
      .sign_ext_imm(sign_ext_imm),
      .waddr(waddr),
      .shamt(shamt),
      .alu_op(alu_op),
      .alu_imm(alu_imm),
      .rw_(rw_),
      .mem_rw_(mem_rw_),
      .sel_mem(sel_mem),
      .byte_en(byte_en),
      .halt(halt_decoded),
      .atomic(atomic),
      .load_link_(load_link_),
      .check_link(check_link),
      .r1_data_s3(r1_data_s3),
      .r2_data_s3(r2_data_s3),
      .r1_addr_s3(r1_addr_s3),
      .r2_addr_s3(r2_addr_s3),
      .sign_ext_imm_s3(sign_ext_imm_s3),
      .waddr_s3(waddr_s3),
      .shamt_s3(shamt_s3),
      .alu_op_s3(alu_op_s3),
      .alu_imm_s3(alu_imm_s3),
      .rw_s3(rw_s3),
      .mem_rw_s3(mem_rw_s3),
      .sel_mem_s3(sel_mem_s3),
      .byte_en_s3(byte_en_s3),
      .halt_s3(halt_s3),
      .atomic_s3(atomic_s3),
      .load_link_s3(load_link_s3),
      .check_link_s3(check_link_s3)
   );

   // ═══════════════════════════════════════════════════════════════
   // STAGE 3: EXECUTE (EX)
   // ═══════════════════════════════════════════════════════════════

   // Forwarding unit
   forward #(
      .BITS(BITS),
      .REG_ADDR_BITS(REG_ADDR_LEFT+1)
   ) forward_inst (
      // Stage 2 addresses (for three-stage hazards and stall detection)
      .r1_addr(r1_addr),
      .r2_addr(r2_addr),
      // Stage 3 addresses (for one/two-stage hazards)
      .r1_addr_s3(r1_addr_s3),
      .r2_addr_s3(r2_addr_s3),
      // Stage 3 control signals (for stall detection)
      .sel_mem_s3(sel_mem_s3),
      .waddr_s3(waddr_s3),
      .rw_s3(rw_s3),
      // Stage 4 writeback info
      .rw_s4(rw_s4),
      .waddr_s4(waddr_s4),
      .sel_mem_s4(sel_mem_s4),
      // Stage 5 writeback info
      .rw_s5(rw_s5),
      .waddr_s5(waddr_s5),
      // Control hazard signals
      .jreg(jreg),
      .breq(breq),
      .brne(brne),
      // Forwarding control outputs
      .r1_fwd_s4(r1_fwd_s4),
      .r2_fwd_s4(r2_fwd_s4),
      .r1_fwd_s5(r1_fwd_s5),
      .r2_fwd_s5(r2_fwd_s5),
      .r1_fwd_s6(r1_fwd_s6),
      .r2_fwd_s6(r2_fwd_s6),
      // Jump register forwarding
      .j_fwd_s4(j_fwd_s4),
      .j_fwd_s5(j_fwd_s5),
      // Branch forwarding
      .b_r1_fwd_s4(b_r1_fwd_s4),
      .b_r2_fwd_s4(b_r2_fwd_s4),
      .b_r1_fwd_s5(b_r1_fwd_s5),
      .b_r2_fwd_s5(b_r2_fwd_s5),
      // Stall control output
      .stall_pipe(stall_pipe)
   );

   // ═══════════════════════════════════════════════════════════════
   // ALU Input Selection with Forwarding
   // ═══════════════════════════════════════════════════════════════

   // ALU Input 1: Always forward if needed
   // Priority: Stage 4 > Stage 5 > Register File
   assign alu_in_1 = r1_fwd_s4 ? alu_out_s4 :       // Forward from Stage 4 (highest priority)
                     r1_fwd_s5 ? reg_wdata :         // Forward from Stage 5
                     r1_data_s3;                     // Normal register file data

   // ALU Input 2: Use immediate if needed, otherwise forward
   // For stores: alu_imm_s3=1, so ALU gets immediate (correct!)
   assign alu_in_2 = alu_imm_s3 ? sign_ext_imm_s3 : // Immediate value (for stores/immediate ops)
                     r2_fwd_s4 ? alu_out_s4 :       // Forward from Stage 4 (highest priority)
                     r2_fwd_s5 ? reg_wdata :         // Forward from Stage 5
                     r2_data_s3;                     // Normal register file data

   // ═══════════════════════════════════════════════════════════════
   // STEP 5: r2_data Forwarding for Store Instructions
   // Forward r2_data separately so memory gets correct data to store
   // ═══════════════════════════════════════════════════════════════

   logic [BITS-1:0] r2_data_s3_fwd;  // Forwarded r2_data for memory operations

   // Forward r2_data for stores (independent of ALU input forwarding)
   assign r2_data_s3_fwd = r2_fwd_s4 ? alu_out_s4 :  // Forward from Stage 4
                           r2_fwd_s5 ? reg_wdata :    // Forward from Stage 5
                           r2_data_s3;                // Normal register file data

   // the alu
   alu #( .NUM_BITS(BITS) ) alu (
       .alu_out(alu_out),
       .data1(alu_in_1), .data2(alu_in_2),
       .alu_op(alu_op_s3), .shamt(shamt_s3) );

   // equality module for branches (Stage 2 - needed for PC branch decision)
   equality #( .NUM_BITS(BITS) ) equality (
        .equal(equal), .not_equal(not_equal),
        .data1(r1_data), .data2(r2_data),
        .b_r1_fwd_s4(b_r1_fwd_s4), .b_r2_fwd_s4(b_r2_fwd_s4),
        .b_r1_fwd_s5(b_r1_fwd_s5), .b_r2_fwd_s5(b_r2_fwd_s5),
        .alu_out_s4(alu_out_s4), .reg_wdata(reg_wdata) );

   // ═══════════════════════════════════════════════════════════════
   // PIPELINE REGISTER: EX/MEM (Stage 3 → Stage 4)
   // ═══════════════════════════════════════════════════════════════
   pipe_ex_mem #(
      .BITS(BITS),
      .REG_ADDR_BITS(REG_ADDR_LEFT+1)
   ) pipe_ex_mem_inst (
      .clk(clk),
      .rst_(rst_),
      .alu_out(alu_out),
      .r2_data_s3(r2_data_s3_fwd),  // Use forwarded r2_data for stores
      .waddr_s3(waddr_s3),
      .rw_s3(rw_s3),
      .mem_rw_s3(mem_rw_s3),
      .sel_mem_s3(sel_mem_s3),
      .byte_en_s3(byte_en_s3),
      .halt_s3(halt_s3),
      .atomic_s3(atomic_s3),
      .load_link_s3(load_link_s3),
      .check_link_s3(check_link_s3),
      .alu_out_s4(alu_out_s4),
      .r2_data_s4(r2_data_s4),
      .waddr_s4(waddr_s4),
      .rw_s4(rw_s4),
      .mem_rw_s4(mem_rw_s4),
      .sel_mem_s4(sel_mem_s4),
      .byte_en_s4(byte_en_s4),
      .halt_s4(halt_s4),
      .atomic_s4(atomic_s4),
      .load_link_s4(load_link_s4),
      .check_link_s4(check_link_s4)
   );

   // ═══════════════════════════════════════════════════════════════
   // STAGE 4: MEMORY ACCESS (MEM)
   // ═══════════════════════════════════════════════════════════════

   // SC success determination (must be computed BEFORE state update)
   logic sc_success_s4;
   assign sc_success_s4 = link_valid & (alu_out_s4 == link_addr);

   // SC write control logic
   assign link_rw_ = check_link_s4 & ~sc_success_s4;
   assign use_mem_rw_ = mem_rw_s4 | link_rw_;

   // LL/SC state management
   always @(posedge clk or negedge rst_) begin
      if (!rst_) begin
         link_valid <= 1'b0;
         link_addr  <= {BITS{1'b0}};
      end else begin
         if (load_link_s4) begin
            link_addr  <= alu_out_s4;
            link_valid <= 1'b1;
         end
         else if (atomic_s4) begin
            link_valid <= 1'b0;
         end
         else if (!use_mem_rw_ && link_valid && (alu_out_s4 == link_addr)) begin
            link_valid <= 1'b0;
         end
      end
   end

   // the data memory - NO shifting, memory module handles byte_en directly
   memory #( .BITS(BITS), .WORDS(D_MEM_WORDS), .BASE_ADDR(D_MEM_BASE_ADDR) ) d_memory (
        .rdata(d_mem_rdata), .clk(clk), .wdata(r2_data_s4),
        .rw_(use_mem_rw_), .addr(alu_out_s4), .byte_en(byte_en_s4) );

   // ═══════════════════════════════════════════════════════════════
   // PIPELINE REGISTER: MEM/WB (Stage 4 → Stage 5)
   // ═══════════════════════════════════════════════════════════════
   pipe_mem_wb #(
      .BITS(BITS),
      .REG_ADDR_BITS(REG_ADDR_LEFT+1)
   ) pipe_mem_wb_inst (
      .clk(clk),
      .rst_(rst_),
      .alu_out_s4(alu_out_s4),
      .d_mem_rdata(d_mem_rdata),
      .waddr_s4(waddr_s4),
      .rw_s4(rw_s4),
      .sel_mem_s4(sel_mem_s4),
      .byte_en_s4(byte_en_s4),
      .halt_s4(halt_s4),
      .atomic_s4(atomic_s4),
      .link_rw_(link_rw_),
      .sc_success_s4(sc_success_s4),
      .alu_out_s5(alu_out_s5),
      .d_mem_rdata_s5(d_mem_rdata_s5),
      .waddr_s5(waddr_s5),
      .rw_s5(rw_s5),
      .sel_mem_s5(sel_mem_s5),
      .byte_en_s5(byte_en_s5),
      .halt_s5(halt_s5),
      .atomic_s5(atomic_s5),
      .link_rw_s5(link_rw_s5),
      .sc_success_s5(sc_success_s5)
   );

   // ═══════════════════════════════════════════════════════════════
   // STAGE 5: WRITE BACK (WB)
   // ═══════════════════════════════════════════════════════════════

   // Extract and extend loaded data based ONLY on byte_en (no address offset consideration)
   logic [BITS-1:0] load_data;

   always @(*) begin
      if (byte_en_s5 == 4'b0001) begin
         // LBU: extract lowest byte only
         load_data = {{24{1'b0}}, d_mem_rdata_s5[7:0]};
      end else if (byte_en_s5 == 4'b0011) begin
         // LHU: extract lowest halfword only
         load_data = {{16{1'b0}}, d_mem_rdata_s5[15:0]};
      end else begin
         // LW: use full word
         load_data = d_mem_rdata_s5;
      end
   end

   // Select data to write to register file
   // For SC: write success flag (1 = success, 0 = failure)
   // For LW/LBU/LHU: write extracted and extended memory data
   // For ALU ops: write ALU result
   assign reg_wdata = atomic_s5 ? {{(BITS-1){1'b0}}, sc_success_s5} :
                      (sel_mem_s5 ? load_data : alu_out_s5);

   // ═══════════════════════════════════════════════════════════════
   // Output Assignments
   // ═══════════════════════════════════════════════════════════════
   // Halt when the halt instruction reaches Stage 5 (Write Back)
   assign halt = halt_s5;

endmodule