Complete Design Document (#1865)

core/alu.sv

@@ -23,11 +23,16 @@ module alu
 #(
     parameter config_pkg::cva6_cfg_t CVA6Cfg = config_pkg::cva6_cfg_empty
 ) (
-    input  logic         clk_i,            // Clock
-    input  logic         rst_ni,           // Asynchronous reset active low
-    input  fu_data_t     fu_data_i,
+    // Subsystem Clock - SUBSYSTEM
+    input logic clk_i,
+    // Asynchronous reset active low - SUBSYSTEM
+    input logic rst_ni,
+    // FU data needed to execute instruction - ISSUE_STAGE
+    input fu_data_t fu_data_i,
+    // ALU result - ISSUE_STAGE
     output riscv::xlen_t result_o,
-    output logic         alu_branch_res_o
+    // ALU branch compare result - branch_unit
+    output logic alu_branch_res_o
 );
 
   riscv::xlen_t                   operand_a_rev;

core/branch_unit.sv

@@ -15,22 +15,34 @@
 module branch_unit #(
     parameter config_pkg::cva6_cfg_t CVA6Cfg = config_pkg::cva6_cfg_empty
 ) (
+    // Subsystem Clock - SUBSYSTEM
     input logic clk_i,
+    // Asynchronous reset active low - SUBSYSTEM
     input logic rst_ni,
+    // Debug mode state - CSR_REGFILE
     input logic debug_mode_i,
+    // FU data needed to execute instruction - ISSUE_STAGE
     input ariane_pkg::fu_data_t fu_data_i,
-    input logic [riscv::VLEN-1:0] pc_i,  // PC of instruction
+    // Instruction PC - ISSUE_STAGE
+    input logic [riscv::VLEN-1:0] pc_i,
+    // Instruction is compressed - ISSUE_STAGE
     input logic is_compressed_instr_i,
-    input  logic                      fu_valid_i,             // any functional unit is valid, check that there is no accidental mis-predict
+    // any functional unit is valid, check that there is no accidental mis-predict - TO_BE_COMPLETED
+    input logic fu_valid_i,
+    // Branch unit instruction is valid - ISSUE_STAGE
     input logic branch_valid_i,
-    input logic branch_comp_res_i,  // branch comparison result from ALU
+    // ALU branch compare result - ALU
+    input logic branch_comp_res_i,
+    // Brach unit result - ISSUE_STAGE
     output logic [riscv::VLEN-1:0] branch_result_o,
-
-    input ariane_pkg::branchpredict_sbe_t branch_predict_i,  // this is the address we predicted
-    output ariane_pkg::bp_resolve_t               resolved_branch_o,      // this is the actual address we are targeting
-    output logic resolve_branch_o,  // to ID to clear that we resolved the branch and we can
-                                    // accept new entries to the scoreboard
-    output ariane_pkg::exception_t branch_exception_o  // branch exception out
+    // Information of branch prediction - ISSUE_STAGE
+    input ariane_pkg::branchpredict_sbe_t branch_predict_i,
+    // Signaling that we resolved the branch - ISSUE_STAGE
+    output ariane_pkg::bp_resolve_t resolved_branch_o,
+    // Branch is resolved, new entries can be accepted by scoreboard - ID_STAGE
+    output logic resolve_branch_o,
+    // Branch exception out - TO_BE_COMPLETED
+    output ariane_pkg::exception_t branch_exception_o
 );
   logic [riscv::VLEN-1:0] target_address;
   logic [riscv::VLEN-1:0] next_pc;

core/csr_buffer.sv

@@ -19,18 +19,24 @@ module csr_buffer
 #(
     parameter config_pkg::cva6_cfg_t CVA6Cfg = config_pkg::cva6_cfg_empty
 ) (
-    input logic clk_i,   // Clock
-    input logic rst_ni,  // Asynchronous reset active low
+    // Subsystem Clock - SUBSYSTEM
+    input logic clk_i,
+    // Asynchronous reset active low - SUBSYSTEM
+    input logic rst_ni,
+    // Flush CSR - CONTROLLER
     input logic flush_i,
-
+    // FU data needed to execute instruction - ISSUE_STAGE
     input fu_data_t fu_data_i,
-
-    output logic                csr_ready_o,   // FU is ready e.g. not busy
-    input  logic                csr_valid_i,   // Input is valid
-    output riscv::xlen_t        csr_result_o,
-    input  logic                csr_commit_i,  // commit the pending CSR OP
-    // to CSR file
-    output logic         [11:0] csr_addr_o     // CSR address to commit stage
+    // CSR FU is ready - ISSUE_STAGE
+    output logic csr_ready_o,
+    // CSR instruction is valid - ISSUE_STAGE
+    input logic csr_valid_i,
+    // CSR buffer result - ISSUE_STAGE
+    output riscv::xlen_t csr_result_o,
+    // commit the pending CSR OP - TO_BE_COMPLETED
+    input logic csr_commit_i,
+    // CSR address to write - COMMIT_STAGE
+    output logic [11:0] csr_addr_o
 );
   // this is a single entry store buffer for the address of the CSR
   // which we are going to need in the commit stage

core/csr_regfile.sv

@@ -83,15 +83,15 @@ module csr_regfile
     output riscv::xs_t                                                     vs_o,
     // interrupt management to id stage - ID_STAGE
     output irq_ctrl_t                                                      irq_ctrl_o,
-    // enable VA translation - EX_STAGE
+    // Enable virtual address translation - EX_STAGE
     output logic                                                           en_translation_o,
-    // enable VA translation for load and stores - EX_STAGE
+    // Enable virtual address translation for load and stores - EX_STAGE
     output logic                                                           en_ld_st_translation_o,
     // Privilege level at which load and stores should happen - EX_STAGE
     output riscv::priv_lvl_t                                               ld_st_priv_lvl_o,
-    // TO_BE_COMPLETED - EX_STAGE
+    // Supervisor User Memory - EX_STAGE
     output logic                                                           sum_o,
-    // TO_BE_COMPLETED - EX_STAGE
+    // Make Executable Readable - EX_STAGE
     output logic                                                           mxr_o,
     // TO_BE_COMPLETED - EX_STAGE
     output logic              [          riscv::PPNW-1:0]                  satp_ppn_o,

core/cva6.sv

@@ -131,7 +131,7 @@ module cva6
     input logic time_irq_i,
     // Debug (async) request - SUBSYSTEM
     input logic debug_req_i,
-    // Probes to build RVFI, can be left open when not used - SUBSYSTEM
+    // Probes to build RVFI, can be left open when not used - RVFI
     output rvfi_probes_t rvfi_probes_o,
     // CVXIF request - SUBSYSTEM
     output cvxif_req_t cvxif_req_o,

core/cvxif_fu.sv

@@ -15,22 +15,33 @@ module cvxif_fu
 #(
     parameter config_pkg::cva6_cfg_t CVA6Cfg = config_pkg::cva6_cfg_empty
 ) (
+    // Subsystem Clock - SUBSYSTEM
     input  logic                                       clk_i,
+    // Asynchronous reset active low - SUBSYSTEM
     input  logic                                       rst_ni,
+    // FU data needed to execute instruction - ISSUE_STAGE
     input  fu_data_t                                   fu_data_i,
+    // Current privilege mode - CSR_REGFILE
     input  riscv::priv_lvl_t                           priv_lvl_i,
-    //from issue
+    // CVXIF instruction is valid - ISSUE_STAGE
     input  logic                                       x_valid_i,
+    // CVXIF is ready - ISSUE_STAGE
     output logic                                       x_ready_o,
+    // Offloaded instruction - ISSUE_STAGE
     input  logic                   [             31:0] x_off_instr_i,
-    //to writeback
+    // CVXIF transaction ID - ISSUE_STAGE
     output logic                   [TRANS_ID_BITS-1:0] x_trans_id_o,
+    // CVXIF exception - ISSUE_STAGE
     output exception_t                                 x_exception_o,
+    // CVXIF FU result - ISSUE_STAGE
     output riscv::xlen_t                               x_result_o,
+    // CVXIF result valid - ISSUE_STAGE
     output logic                                       x_valid_o,
+    // CVXIF write enable - ISSUE_STAGE
     output logic                                       x_we_o,
-    //to coprocessor
+    // CVXIF request - SUBSYSTEM
     output cvxif_pkg::cvxif_req_t                      cvxif_req_o,
+    // CVXIF response - SUBSYSTEM
     input  cvxif_pkg::cvxif_resp_t                     cvxif_resp_i
 );
   localparam X_NUM_RS = ariane_pkg::NR_RGPR_PORTS;

core/ex_stage.sv

@@ -26,7 +26,7 @@ module ex_stage
     input logic rst_ni,
     // Fetch flush request - CONTROLLER
     input logic flush_i,
-    // TO_BE_COMPLETED - CSR_REGFILE
+    // Debug mode is enabled - CSR_REGFILE
     input logic debug_mode_i,
     // rs1 forwarding - ISSUE_STAGE
     input logic [riscv::VLEN-1:0] rs1_forwarding_i,
@@ -38,11 +38,11 @@ module ex_stage
     input logic [riscv::VLEN-1:0] pc_i,
     // Report whether isntruction is compressed - ISSUE_STAGE
     input logic is_compressed_instr_i,
-    // TO_BE_COMPLETED - ISSUE_STAGE
+    // Fixed Latency Unit result - ISSUE_STAGE
     output riscv::xlen_t flu_result_o,
     // ID of the scoreboard entry at which a=to write back - ISSUE_STAGE
     output logic [TRANS_ID_BITS-1:0] flu_trans_id_o,
-    // TO_BE_COMPLETED - ISSUE_STAGE
+    // Fixed Latency Unit exception - ISSUE_STAGE
     output exception_t flu_exception_o,
     // FLU is ready - ISSUE_STAGE
     output logic flu_ready_o,
@@ -62,7 +62,7 @@ module ex_stage
     input logic csr_valid_i,
     // CSR address to write - COMMIT_STAGE
     output logic [11:0] csr_addr_o,
-    // TO_BE_COMPLETED - COMMIT_STAGE
+    // CSR commit - COMMIT_STAGE
     input logic csr_commit_i,
     // MULT instruction is valid - ISSUE_STAGE
     input logic mult_valid_i,
@@ -86,11 +86,11 @@ module ex_stage
     output logic [TRANS_ID_BITS-1:0] store_trans_id_o,
     // Exception generated by store instruction - ISSUE_STAGE
     output exception_t store_exception_o,
-    // TO_BE_COMPLETED - COMMIT_STAGE
+    // LSU commit - COMMIT_STAGE
     input logic lsu_commit_i,
     // Commit queue ready to accept another commit request - COMMIT_STAGE
     output logic lsu_commit_ready_o,
-    // TO_BE_COMPLETED - COMMIT_STAGE
+    // Commit transaction ID - COMMIT_STAGE
     input logic [TRANS_ID_BITS-1:0] commit_tran_id_i,
     // TO_BE_COMPLETED - ACC_DISPATCHER
     input logic stall_st_pending_i,
@@ -140,11 +140,11 @@ module ex_stage
     input cvxif_pkg::cvxif_resp_t cvxif_resp_i,
     // accelerate port result is valid - ACC_DISPATCHER
     input logic acc_valid_i,
-    // TO_BE_COMPLETED - CSR_REGFILE
+    // Enable virtual memory translation - CSR_REGFILE
     input logic enable_translation_i,
-    // TO_BE_COMPLETED - CSR_REGFILE
+    // Enable virtual memory translation for load/stores - CSR_REGFILE
     input logic en_ld_st_translation_i,
-    // TO_BE_COMPLETED - CONTROLLER
+    // Flush TLB - CONTROLLER
     input logic flush_tlb_i,
     // Privilege mode - CSR_REGFILE
     input riscv::priv_lvl_t priv_lvl_i,
@@ -162,18 +162,17 @@ module ex_stage
     input icache_arsp_t icache_areq_i,
     // icache translation request - CACHE
     output icache_areq_t icache_areq_o,
-    // TO_BE_COMPLETED - CACHE
-    // interface to dcache
+    // Data cache request ouput - CACHE
     input dcache_req_o_t [2:0] dcache_req_ports_i,
-    // TO_BE_COMPLETED - CACHE
+    // Data cache request input - CACHE
     output dcache_req_i_t [2:0] dcache_req_ports_o,
-    // TO_BE_COMPLETED - CACHE
+    // Write buffer is empty - CACHE
     input logic dcache_wbuffer_empty_i,
     // TO_BE_COMPLETED - CACHE
     input logic dcache_wbuffer_not_ni_i,
     // AMO request - CACHE
     output amo_req_t amo_req_o,
-    // AMO response from cache - CACHE
+    // AMO response - CACHE
     input amo_resp_t amo_resp_i,
     // To count the instruction TLB misses - PERF_COUNTERS
     output logic itlb_miss_o,

core/include/config_pkg.sv

@@ -46,15 +46,15 @@ package config_pkg;
     int unsigned                 AxiIdWidth;
     // AXI User width
     int unsigned                 AxiUserWidth;
-    // TO_BE_COMPLETED
+    // Load buffer entry buffer
     int unsigned                 NrLoadBufEntries;
-    // FPU is enabled
+    // Floating Point
     bit                          FpuEn;
-    // TO_BE_COMPLETED
+    // Non standard 16bits Floating Point
     bit                          XF16;
-    // TO_BE_COMPLETED
+    // Non standard 16bits Floating Point Alt
     bit                          XF16ALT;
-    // TO_BE_COMPLETED
+    // Non standard 8bits Floating Point
     bit                          XF8;
     // Atomic RISC-V extension
     bit                          RVA;
@@ -66,33 +66,33 @@ package config_pkg;
     bit                          RVC;
     // Zcb RISC-V extension
     bit                          RVZCB;
-    // TO_BE_COMPLETED
+    // Non standard Vector Floating Point
     bit                          XFVec;
     // CV-X-IF coprocessor interface is supported
     bit                          CvxifEn;
-    // Zicond RISC-V extension is enabled
+    // Zicond RISC-V extension
     bit                          ZiCondExtEn;
     // Single precision FP RISC-V extension
     bit                          RVF;
     // Double precision FP RISC-V extension
     bit                          RVD;
-    // Floating point is present
+    // Floating Point is present
     bit                          FpPresent;
-    // TO_BE_COMPLETED
+    // Non standard Floating is Point present
     bit                          NSX;
-    // TO_BE_COMPLETED
+    // Floating Point lenght
     int unsigned                 FLen;
-    // Vector floating point extension
+    // Vector Floating Point extension
     bit                          RVFVec;
-    // 16 bits vector floating point extension
+    // 16 bits vector Floating Point extension
     bit                          XF16Vec;
-    // TO_BE_COMPLETED
+    // 16 bits vector Floating Point Alt extension
     bit                          XF16ALTVec;
-    // 8 bits vector floating point extension
+    // 8 bits vector Floating Point extension
     bit                          XF8Vec;
     // TO_BE_COMPLETED
     int unsigned                 NrRgprPorts;
-    // TO_BE_COMPLETED
+    // Function Unit write back port number
     int unsigned                 NrWbPorts;
     // Accelerate Port coprocessor interface
     bit                          EnableAccelerator;
@@ -144,7 +144,7 @@ package config_pkg;
     logic [NrMaxRules-1:0][63:0] CachedRegionLength;
     // Maximum number of outstanding stores
     int unsigned                 MaxOutstandingStores;
-    // Debug mode
+    // Debug support
     bit                          DebugEn;
     // Non idem potency
     bit                          NonIdemPotenceEn;