port_builder generates the table of ports (openhwgroup#1805)

core/cva6.sv

@@ -115,24 +115,31 @@ module cva6
     parameter type cvxif_req_t = cvxif_pkg::cvxif_req_t,
     parameter type cvxif_resp_t = cvxif_pkg::cvxif_resp_t
 ) (
+    // Subsystem Clock - SUBSYSTEM
     input logic clk_i,
+    // Asynchronous reset active low - SUBSYSTEM
     input logic rst_ni,
-    // Core ID, Cluster ID and boot address are considered more or less static
-    input logic [riscv::VLEN-1:0] boot_addr_i,  // reset boot address
-    input  logic [riscv::XLEN-1:0]       hart_id_i,    // hart id in a multicore environment (reflected in a CSR)
-    // Interrupt inputs
-    input logic [1:0] irq_i,  // level sensitive IR lines, mip & sip (async)
-    input logic ipi_i,  // inter-processor interrupts (async)
-    // Timer facilities
-    input logic time_irq_i,  // timer interrupt in (async)
-    input logic debug_req_i,  // debug request (async)
-    // RISC-V formal interface port (`rvfi`):
-    // Can be left open when formal tracing is not needed.
+    // Reset boot address - SUBSYSTEM
+    input logic [riscv::VLEN-1:0] boot_addr_i,
+    // Hard ID reflected as CSR - SUBSYSTEM
+    input logic [riscv::XLEN-1:0] hart_id_i,
+    // Level sensitive (async) interrupts - SUBSYSTEM
+    input logic [1:0] irq_i,
+    // Inter-processor (async) interrupt - SUBSYSTEM
+    input logic ipi_i,
+    // Timer (async) interrupt - SUBSYSTEM
+    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
     output rvfi_probes_t rvfi_probes_o,
+    // CVXIF request - SUBSYSTEM
     output cvxif_req_t cvxif_req_o,
+    // CVXIF response - SUBSYSTEM
     input cvxif_resp_t cvxif_resp_i,
-    // memory side
+    // noc request, can be AXI or OpenPiton - SUBSYSTEM
     output noc_req_t noc_req_o,
+    // noc response, can be AXI or OpenPiton - SUBSYSTEM
     input noc_resp_t noc_resp_i
 );
 

core/frontend/bht.sv

@@ -22,13 +22,19 @@ module bht #(
     parameter config_pkg::cva6_cfg_t CVA6Cfg = config_pkg::cva6_cfg_empty,
     parameter int unsigned NR_ENTRIES = 1024
 ) (
-    input  logic                                                          clk_i,
-    input  logic                                                          rst_ni,
-    input  logic                                                          flush_i,
-    input  logic                                                          debug_mode_i,
-    input  logic                        [                riscv::VLEN-1:0] vpc_i,
-    input  ariane_pkg::bht_update_t                                       bht_update_i,
-    // we potentially need INSTR_PER_FETCH predictions/cycle
+    // Subsystem Clock - SUBSYSTEM
+    input logic clk_i,
+    // Asynchronous reset active low - SUBSYSTEM
+    input logic rst_ni,
+    // Fetch flush request - CONTROLLER
+    input logic flush_i,
+    // Debug mode state - CSR
+    input logic debug_mode_i,
+    // Virtual PC - CACHE
+    input logic [riscv::VLEN-1:0] vpc_i,
+    // Update bht with resolved address - EXECUTE
+    input ariane_pkg::bht_update_t bht_update_i,
+    // Prediction from bht - FRONTEND
     output ariane_pkg::bht_prediction_t [ariane_pkg::INSTR_PER_FETCH-1:0] bht_prediction_o
 );
   // the last bit is always zero, we don't need it for indexing

core/frontend/btb.sv

@@ -29,14 +29,20 @@ module btb #(
     parameter config_pkg::cva6_cfg_t CVA6Cfg = config_pkg::cva6_cfg_empty,
     parameter int NR_ENTRIES = 8
 ) (
-    input logic clk_i,        // Clock
-    input logic rst_ni,       // Asynchronous reset active low
-    input logic flush_i,      // flush the btb
+    // Subsystem Clock - SUBSYSTEM
+    input logic clk_i,
+    // Asynchronous reset active low - SUBSYSTEM
+    input logic rst_ni,
+    // Fetch flush request - CONTROLLER
+    input logic flush_i,
+    // Debug mode state - CSR
     input logic debug_mode_i,
-
-    input logic [riscv::VLEN-1:0] vpc_i,  // virtual PC from IF stage
-    input ariane_pkg::btb_update_t btb_update_i,  // update btb with this information
-    output ariane_pkg::btb_prediction_t [ariane_pkg::INSTR_PER_FETCH-1:0] btb_prediction_o // prediction from btb
+    // Virtual PC - CACHE
+    input logic [riscv::VLEN-1:0] vpc_i,
+    // Update BTB with resolved address - EXECUTE
+    input ariane_pkg::btb_update_t btb_update_i,
+    // BTB Prediction - FRONTEND
+    output ariane_pkg::btb_prediction_t [ariane_pkg::INSTR_PER_FETCH-1:0] btb_prediction_o
 );
   // the last bit is always zero, we don't need it for indexing
   localparam OFFSET = CVA6Cfg.RVC == 1'b1 ? 1 : 2;

core/frontend/frontend.sv

@@ -20,33 +20,46 @@ module frontend
 #(
     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 logic flush_i,  // flush request for PCGEN
-    input logic flush_bp_i,  // flush branch prediction
-    input logic halt_i,  // halt commit stage
+    // Subsystem Clock - SUBSYSTEM
+    input logic clk_i,
+    // Asynchronous reset active low - SUBSYSTEM
+    input logic rst_ni,
+    // Fetch flush request - CONTROLLER
+    input logic flush_i,
+    // flush branch prediction - zero
+    input logic flush_bp_i,
+    // halt commit stage - CONTROLLER
+    input logic halt_i,
+    // Debug mode state - CSR
     input logic debug_mode_i,
-    // global input
+    // Next PC when reset - SUBSYSTEM
     input logic [riscv::VLEN-1:0] boot_addr_i,
-    // Set a new PC
-    // mispredict
-    input  bp_resolve_t        resolved_branch_i,  // from controller signaling a branch_predict -> update BTB
-    // from commit, when flushing the whole pipeline
-    input logic set_pc_commit_i,  // Take the PC from commit stage
-    input logic [riscv::VLEN-1:0] pc_commit_i,  // PC of instruction in commit stage
-    // CSR input
-    input logic [riscv::VLEN-1:0] epc_i,  // exception PC which we need to return to
-    input logic eret_i,  // return from exception
-    input logic [riscv::VLEN-1:0] trap_vector_base_i,  // base of trap vector
-    input logic ex_valid_i,  // exception is valid - from commit
-    input logic set_debug_pc_i,  // jump to debug address
-    // Instruction Fetch
+    // mispredict event and next PC - EXECUTE
+    input bp_resolve_t resolved_branch_i,
+    // Set the PC coming from COMMIT as next PC - CONTROLLER
+    input logic set_pc_commit_i,
+    // Next PC when flushing pipeline - COMMIT
+    input logic [riscv::VLEN-1:0] pc_commit_i,
+    // Next PC when returning from exception - CSR
+    input logic [riscv::VLEN-1:0] epc_i,
+    // Return from exception event - CSR
+    input logic eret_i,
+    // Next PC when jumping into exception - CSR
+    input logic [riscv::VLEN-1:0] trap_vector_base_i,
+    // Exception event - COMMIT
+    input logic ex_valid_i,
+    // Debug event - CSR
+    input logic set_debug_pc_i,
+    // Handshake between CACHE and FRONTEND (fetch) - CACHES
     output icache_dreq_t icache_dreq_o,
+    // Handshake between CACHE and FRONTEND (fetch) - CACHES
     input icache_drsp_t icache_dreq_i,
-    // instruction output port -> to processor back-end
-    output fetch_entry_t       fetch_entry_o,       // fetch entry containing all relevant data for the ID stage
-    output logic fetch_entry_valid_o,  // instruction in IF is valid
-    input logic fetch_entry_ready_i  // ID acknowledged this instruction
+    // Handshake's data between fetch and decode - DECODE
+    output fetch_entry_t fetch_entry_o,
+    // Handshake's valid between fetch and decode - DECODE
+    output logic fetch_entry_valid_o,
+    // Handshake's ready between fetch and decode - DECODE
+    input logic fetch_entry_ready_i
 );
   // Instruction Cache Registers, from I$
   logic                            [                FETCH_WIDTH-1:0] icache_data_q;

core/frontend/instr_queue.sv

@@ -48,26 +48,39 @@ module instr_queue
 #(
     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,
+    // Fetch flush request - CONTROLLER
     input logic flush_i,
+    // Instruction - instr_realign
     input logic [ariane_pkg::INSTR_PER_FETCH-1:0][31:0] instr_i,
+    // Instruction address - instr_realign
     input logic [ariane_pkg::INSTR_PER_FETCH-1:0][riscv::VLEN-1:0] addr_i,
+    // Instruction is valid - instr_realign
     input logic [ariane_pkg::INSTR_PER_FETCH-1:0] valid_i,
+    // Handshake’s ready with CACHE - CACHE
     output logic ready_o,
+    // Indicates instructions consummed, or popped by DECODE - FRONTEND
     output logic [ariane_pkg::INSTR_PER_FETCH-1:0] consumed_o,
-    // we've encountered an exception, at this point the only possible exceptions are page-table faults
+    // Exception (which is page-table fault) - CACHE
     input ariane_pkg::frontend_exception_t exception_i,
+    // Exception address - CACHE
     input logic [riscv::VLEN-1:0] exception_addr_i,
-    // branch predict
+    // Branch predict - FRONTEND
     input logic [riscv::VLEN-1:0] predict_address_i,
+    // Instruction predict address - FRONTEND
     input ariane_pkg::cf_t [ariane_pkg::INSTR_PER_FETCH-1:0] cf_type_i,
-    // replay instruction because one of the FIFO was already full
+    // Replay instruction because one of the FIFO was  full - FRONTEND
     output logic replay_o,
-    output logic [riscv::VLEN-1:0] replay_addr_o,  // address at which to replay this instruction
-    // to processor backend
+    // Address at which to replay the fetch - FRONTEND
+    output logic [riscv::VLEN-1:0] replay_addr_o,
+    // Handshake’s data with DECODE - DECODE
     output ariane_pkg::fetch_entry_t fetch_entry_o,
+    // Handshake’s valid with DECODE - DECODE
     output logic fetch_entry_valid_o,
+    // Handshake’s ready with DECODE - DECODE
     input logic fetch_entry_ready_i
 );
 

core/frontend/instr_scan.sv

@@ -18,19 +18,33 @@
 module instr_scan #(
     parameter config_pkg::cva6_cfg_t CVA6Cfg = config_pkg::cva6_cfg_empty
 ) (
-    input  logic [           31:0] instr_i,       // expect aligned instruction, compressed or not
-    output logic                   rvi_return_o,
-    output logic                   rvi_call_o,
-    output logic                   rvi_branch_o,
-    output logic                   rvi_jalr_o,
-    output logic                   rvi_jump_o,
+    // Instruction to be predecoded - instr_realign
+    input logic [31:0] instr_i,
+    // Return instruction - FRONTEND
+    output logic rvi_return_o,
+    // JAL instruction - FRONTEND
+    output logic rvi_call_o,
+    // Branch instruction - FRONTEND
+    output logic rvi_branch_o,
+    // JALR instruction - FRONTEND
+    output logic rvi_jalr_o,
+    // Unconditional jump instruction - FRONTEND
+    output logic rvi_jump_o,
+    // Instruction immediat - FRONTEND
     output logic [riscv::VLEN-1:0] rvi_imm_o,
-    output logic                   rvc_branch_o,
-    output logic                   rvc_jump_o,
-    output logic                   rvc_jr_o,
-    output logic                   rvc_return_o,
-    output logic                   rvc_jalr_o,
-    output logic                   rvc_call_o,
+    // Branch compressed instruction - FRONTEND
+    output logic rvc_branch_o,
+    // Unconditional jump compressed instruction - FRONTEND
+    output logic rvc_jump_o,
+    // JR compressed instruction - FRONTEND
+    output logic rvc_jr_o,
+    // Return compressed instruction - FRONTEND
+    output logic rvc_return_o,
+    // JALR compressed instruction - FRONTEND
+    output logic rvc_jalr_o,
+    // JAL compressed instruction - FRONTEND
+    output logic rvc_call_o,
+    // Instruction compressed immediat - FRONTEND
     output logic [riscv::VLEN-1:0] rvc_imm_o
 );
   logic is_rvc;

core/frontend/ras.sv

@@ -18,13 +18,20 @@ module ras #(
     parameter config_pkg::cva6_cfg_t CVA6Cfg = config_pkg::cva6_cfg_empty,
     parameter int unsigned DEPTH = 2
 ) (
-    input  logic                               clk_i,
-    input  logic                               rst_ni,
-    input  logic                               flush_i,
-    input  logic                               push_i,
-    input  logic                               pop_i,
-    input  logic             [riscv::VLEN-1:0] data_i,
-    output ariane_pkg::ras_t                   data_o
+    // Subsystem Clock - SUBSYSTEM
+    input logic clk_i,
+    // Asynchronous reset active low - SUBSYSTEM
+    input logic rst_ni,
+    // Fetch flush request - CONTROLLER
+    input logic flush_i,
+    // Push address in RAS - FRONTEND
+    input logic push_i,
+    // Pop address from RAS - FRONTEND
+    input logic pop_i,
+    // Data to be pushed - FRONTEND
+    input logic [riscv::VLEN-1:0] data_i,
+    // Popped data - FRONTEND
+    output ariane_pkg::ras_t data_o
 );
 
   ariane_pkg::ras_t [DEPTH-1:0] stack_d, stack_q;

core/instr_realign.sv

@@ -25,15 +25,25 @@ module instr_realign
 #(
     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,
+    // Fetch flush request - CONTROLLER
     input logic flush_i,
+    // 32-bit block is valid - CACHE
     input logic valid_i,
-    output logic serving_unaligned_o,  // we have an unaligned instruction in [0]
+    // Instruction is unaligned - FRONTEND
+    output logic serving_unaligned_o,
+    // 32-bit block address - CACHE
     input logic [riscv::VLEN-1:0] address_i,
+    // 32-bit block - CACHE
     input logic [FETCH_WIDTH-1:0] data_i,
+    // instruction is valid - FRONTEND
     output logic [INSTR_PER_FETCH-1:0] valid_o,
+    // Instruction address - FRONTEND
     output logic [INSTR_PER_FETCH-1:0][riscv::VLEN-1:0] addr_o,
+    // Instruction - instr_scan, instr_queue
     output logic [INSTR_PER_FETCH-1:0][31:0] instr_o
 );
   // as a maximum we support a fetch width of 64-bit, hence there can be 4 compressed instructions