Add Doxygen-style module descriptions

We leave the existing longer headers in place for author information.

rtl/ibex_alu.sv

@@ -22,6 +22,9 @@
 
 import ibex_defines::*;
 
+/**
+ * Arithmetic logic unit
+ */
 module ibex_alu
 (
   input  logic [ALU_OP_WIDTH-1:0]  operator_i,

rtl/ibex_compressed_decoder.sv

@@ -16,9 +16,14 @@
 //                                                                            //
 ////////////////////////////////////////////////////////////////////////////////
 
-
 import ibex_defines::*;
 
+/**
+ * Compressed instruction decoder
+ *
+ * Decodes RISC-V compressed instructions into their RV32 equivalent.
+ * This module is fully combinatorial.
+ */
 module ibex_compressed_decoder
 (
   input  logic [31:0] instr_i,

rtl/ibex_controller.sv

@@ -24,7 +24,9 @@
 
 import ibex_defines::*;
 
-
+/**
+ * Main CPU controller of the processor
+ */
 module ibex_controller
 #(
   parameter REG_ADDR_WIDTH      = 5

rtl/ibex_core.sv

@@ -25,6 +25,9 @@
 
 import ibex_defines::*;
 
+/**
+ * Top level module of the ibex RISC-V core
+ */
 module ibex_core
 #(
   parameter N_EXT_PERF_COUNTERS = 0,

rtl/ibex_cs_registers.sv

@@ -29,6 +29,12 @@ import ibex_defines::*;
  `endif
 `endif
 
+/**
+ * Control and Status Registers
+ *
+ * Control and Status Registers (CSRs) loosely following the RiscV draft
+ * priviledged instruction set spec (v1.9)
+ */
 module ibex_cs_registers
 #(
   parameter N_EXT_CNT    = 0

rtl/ibex_decoder.sv

@@ -25,6 +25,9 @@
 
 import ibex_defines::*;
 
+/**
+ * Instruction decoder
+ */
 module ibex_decoder
 #(
   parameter RV32M      = 1

rtl/ibex_ex_block.sv

@@ -25,6 +25,11 @@
 
 import ibex_defines::*;
 
+/**
+ * Execution stage
+ *
+ * Execution block: Hosts ALU and MUL/DIV unit
+ */
 module ibex_ex_block
 #(
   parameter RV32M      = 1

rtl/ibex_fetch_fifo.sv

@@ -15,9 +15,13 @@
 
 `include "ibex_config.sv"
 
-// input port: send address one cycle before the data
-// clear_i clears the FIFO for the following cycle. in_addr_i can be sent in
-// this cycle already
+/**
+ * Fetch Fifo for 32 bit memory interface
+ *
+ * input port: send address one cycle before the data
+ * clear_i clears the FIFO for the following cycle. in_addr_i can be sent in
+ * this cycle already.
+ */
 module ibex_fetch_fifo
 (
     input  logic        clk,

rtl/ibex_id_stage.sv

@@ -31,7 +31,12 @@ import ibex_defines::*;
 `define REG_S2 24:20
 `define REG_D  11:07
 
-
+/**
+ * Instruction Decode Stage
+ *
+ * Decode stage of the core. It decodes the instructions and hosts the register
+ * file.
+ */
 module ibex_id_stage
 #(
   parameter RV32M      = 1,

rtl/ibex_if_stage.sv

@@ -24,6 +24,12 @@
 
 import ibex_defines::*;
 
+/**
+ * Instruction Fetch Stage
+ *
+ * Instruction fetch unit: Selection of the next PC, and buffering (sampling) of
+ * the read instruction.
+ */
 module ibex_if_stage
 (
       input  logic        clk,

rtl/ibex_int_controller.sv

@@ -18,6 +18,9 @@
 
 import ibex_defines::*;
 
+/**
+ * Interrupt Controller
+ */
 module ibex_int_controller
 (
   input  logic        clk,

rtl/ibex_load_store_unit.sv

@@ -22,6 +22,12 @@
 
 `include "ibex_config.sv"
 
+/**
+ * Load Store Unit
+ *
+ * Load Store Unit, used to eliminate multiple access during processor stalls,
+ * and to align bytes and halfwords.
+ */
 module ibex_load_store_unit
 (
     input  logic         clk,

rtl/ibex_multdiv_fast.sv

@@ -20,6 +20,11 @@ import ibex_defines::*;
 `define OP_L 15:0
 `define OP_H 31:16
 
+/**
+ * Fast Multiplier and Division
+ *
+ * 16x16 kernel multiplier and Long Division
+ */
 module ibex_multdiv_fast
 (
   input  logic        clk,

rtl/ibex_multdiv_slow.sv

@@ -17,7 +17,11 @@
 
 import ibex_defines::*;
 
-
+/**
+ * Slow Multiplier and Division
+ *
+ * Baugh-Wooley multiplier and Long Division
+ */
 module ibex_multdiv_slow
 (
   input  logic        clk,

rtl/ibex_prefetch_buffer.sv

@@ -15,6 +15,12 @@
 //                                                                            //
 ////////////////////////////////////////////////////////////////////////////////
 
+/**
+ * Prefetcher Buffer for 32 bit memory interface
+ *
+ * Prefetch Buffer that caches instructions. This cuts overly long critical
+ * paths to the instruction cache.
+ */
 module ibex_prefetch_buffer
 (
   input  logic        clk,

rtl/ibex_register_file.sv

@@ -22,6 +22,13 @@
 
 `include "ibex_config.sv"
 
+/**
+ * RISC-V register file
+ *
+ * Register file with 31 or 15x 32 bit wide registers. Register 0 is fixed to 0.
+ * This register file is based on latches and is thus smaller than the flip-flop
+ * based RF.
+ */
 module ibex_register_file
 #(
   parameter RV32E         = 0,

rtl/ibex_register_file_ff.sv

@@ -21,6 +21,12 @@
 
 `include "ibex_config.sv"
 
+/**
+ * RISC-V register file
+ *
+ * Register file with 31 or 15x 32 bit wide registers. Register 0 is fixed to 0.
+ * This register file is based on flip flops.
+ */
 module ibex_register_file
 #(
   parameter RV32E         = 0,

rtl/ibex_tracer.sv

@@ -32,7 +32,9 @@ import ibex_tracer_defines::*;
 `define REG_S3 29:25
 `define REG_D  11:07
 
-
+/**
+ * Traces the executed instructions
+ */
 module ibex_tracer
 #(
     parameter REG_ADDR_WIDTH      = 5

rtl/include/ibex_config.sv

@@ -17,6 +17,7 @@
 // Description:    Configure optional simulation modules                      //
 //                                                                            //
 ////////////////////////////////////////////////////////////////////////////////
+// Configure optional simulation modules
 
 // no traces for synthesis, they are not synthesizable
 `ifndef SYNTHESIS

rtl/include/ibex_defines.sv

@@ -18,6 +18,9 @@
 //                                                                            //
 ////////////////////////////////////////////////////////////////////////////////
 
+/**
+ * Defines for various constants used by the processor core
+ */
 package ibex_defines;
 
 ////////////////////////////////////////////////