26 files changed, 114 insertions, 5 deletions
diff --git a/rtl/include/consts.vh b/rtl/include/consts.vh
index 75ee0bf..c1cac89 100644
--- a/rtl/include/consts.vh
+++ b/rtl/include/consts.vh
@@ -1,33 +1,41 @@
+// source selection alu a_src mux 
 parameter ALU_A_SRC_PC      = 3'b000;
 parameter ALU_A_SRC_PC_BUF  = 3'b001;
 parameter ALU_A_SRC_RD1     = 3'b010;
 parameter ALU_A_SRC_RD1_BUF = 3'b011;
 parameter ALU_A_SRC_0       = 3'b100;
 
+// source selection alu b_src mux
 parameter ALU_B_SRC_RD2_BUF = 2'b00;
 parameter ALU_B_SRC_IMM     = 2'b01;
 parameter ALU_B_SRC_4       = 2'b10;
 
+// source selection result mux
 parameter RESULT_SRC_ALU_RESULT     = 2'b00;
 parameter RESULT_SRC_ALU_RESULT_BUF = 2'b01;
 parameter RESULT_SRC_DATA_BUF       = 2'b10;
 
+// source selection mem addr mux
 parameter MEM_ADDR_SRC_PC     = 1'b0;
 parameter MEM_ADDR_SRC_RESULT = 1'b1;
 
+// arithmetic op
 parameter ARITHMETIC_OP_ADD  = 2'b00;
 parameter ARITHMETIC_OP_SUB  = 2'b01;
 parameter ARITHMETIC_OP_SLT  = 2'b10;
 parameter ARITHMETIC_OP_SLTU = 2'b11;
 
+// logic op
 parameter LOGIC_OP_AND = 2'b00;
 parameter LOGIC_OP_OR  = 2'b01;
 parameter LOGIC_OP_XOR = 2'b10;
 
+// shift op
 parameter SHIFT_OP_SLL = 2'b00;
 parameter SHIFT_OP_SRL = 2'b01;
 parameter SHIFT_OP_SRA = 2'b11;
 
+// alu op
 parameter ALU_OP_ARITHMETIC = 2'b00;
 parameter ALU_OP_LOGIC      = 2'b01;
 parameter ALU_OP_SHIFT      = 2'b10;
@@ -43,6 +51,7 @@ parameter ALU_OP_SLL  = { ALU_OP_SHIFT, SHIFT_OP_SLL };
 parameter ALU_OP_SRL  = { ALU_OP_SHIFT, SHIFT_OP_SRL };
 parameter ALU_OP_SRA  = { ALU_OP_SHIFT, SHIFT_OP_SRA };
 
+// control unit fsm states
 parameter STATE_FETCH     = 4'h0;
 parameter STATE_DECODE    = 4'h1;
 parameter STATE_MEM_ADDR  = 4'h2;
@@ -58,6 +67,7 @@ parameter STATE_ALU_WB    = 4'hb;
 parameter STATE_AUIPC     = 4'hc;
 parameter STATE_BRANCH    = 4'hd;
 
+// instruction formats
 parameter INSTR_FORMAT_UNKNOWN = 3'b000;
 parameter INSTR_FORMAT_R       = 3'b001;
 parameter INSTR_FORMAT_I       = 3'b010;
@@ -66,6 +76,7 @@ parameter INSTR_FORMAT_B       = 3'b100;
 parameter INSTR_FORMAT_U       = 3'b101;
 parameter INSTR_FORMAT_J       = 3'b110;
 
+// instruction opcodes
 parameter OPCODE_LUI    = 7'b0110111;
 parameter OPCODE_AUIPC  = 7'b0010111;
 parameter OPCODE_JAL    = 7'b1101111;
@@ -78,6 +89,7 @@ parameter OPCODE_REG    = 7'b0110011;
 parameter OPCODE_SYNC   = 7'b0001111;
 parameter OPCODE_SYS    = 7'b1110011;
 
+// instruction funct3
 parameter FUNCT3_LS_B  = 3'b000;
 parameter FUNCT3_LS_H  = 3'b001;
 parameter FUNCT3_LS_W  = 3'b010;
@@ -100,14 +112,17 @@ parameter FUNCT3_BRANCH_BGE  = 3'b101;
 parameter FUNCT3_BRANCH_BLTU = 3'b110;
 parameter FUNCT3_BRANCH_BGEU = 3'b111;
 
+// instruction funct7
 parameter FUNCT7_ALU_ADD = 7'b0000000;
 parameter FUNCT7_ALU_SUB = 7'b0100000;
 parameter FUNCT7_ALU_SRL = 7'b0000000;
 parameter FUNCT7_ALU_SRA = 7'b0100000;
 
+// alu control
 parameter ALU_CTRL_OP  = 1'b0;
 parameter ALU_CTRL_ADD = 1'b1;
 
+// control unit control signal values
 parameter MEM_WE_ENABLE     = 1'b1;
 parameter MEM_WE_DISABLE    = 1'b0;
 parameter RF_WE_ENABLE      = 1'b1;
@@ -119,6 +134,7 @@ parameter PC_UPDATE_DISABLE = 1'b0;
 parameter BRANCH_ENABLE     = 1'b1;
 parameter BRANCH_DISABLE    = 1'b0;
 
+// memory layout
 parameter IO_BEGIN  = 32'h0000_0000;
 parameter IO_END    = 32'h0000_FFFF;
 parameter ROM_BEGIN = 32'h0001_0000;
@@ -126,4 +142,5 @@ parameter ROM_END   = 32'h000F_FFFF;
 parameter RAM_BEGIN = 32'h0010_0000;
 parameter RAM_END   = 32'hFF0F_FFFF;
 
+// entry point
 parameter PC_INITIAL = 32'h0001_0000;
diff --git a/rtl/src/alu.v b/rtl/src/alu.v
index 8a265ee..2e927ca 100644
--- a/rtl/src/alu.v
+++ b/rtl/src/alu.v
@@ -1,3 +1,7 @@
+// alu:
+// Computes result based on operands a, b and the provided operation.
+// The signal zero is high if result is zero.
+
 module alu (
   input [31:0] a, 
   input [31:0] b,
diff --git a/rtl/src/alu_a_src_mux.v b/rtl/src/alu_a_src_mux.v
index fef701b..4c68d8d 100644
--- a/rtl/src/alu_a_src_mux.v
+++ b/rtl/src/alu_a_src_mux.v
@@ -1,3 +1,6 @@
+// alu src_a mux:
+// Selects source for alu input a.
+
 module alu_a_src_mux (
   input [31:0] src_pc, 
   input [31:0] src_pc_buf,
diff --git a/rtl/src/alu_b_src_mux.v b/rtl/src/alu_b_src_mux.v
index 5932f9e..5f188bc 100644
--- a/rtl/src/alu_b_src_mux.v
+++ b/rtl/src/alu_b_src_mux.v
@@ -1,3 +1,6 @@
+// alu src_b mux:
+// Selects source for alu input b.
+
 module alu_b_src_mux (
   input [31:0] src_rd2_buf,
   input [31:0] src_imm,
diff --git a/rtl/src/alu_op_decode.v b/rtl/src/alu_op_decode.v
index 4523255..0e985eb 100644
--- a/rtl/src/alu_op_decode.v
+++ b/rtl/src/alu_op_decode.v
@@ -1,3 +1,9 @@
+// alu op decode:
+// Decodes instruction to corresponding alu_op if alu_ctrl is set to ALU_CTRL_OP
+// otherwise, if it is ALU_CTRL_ADD, then its sets alu_op to ALU_OP_ADD.
+// This is used if the cpu needs to add two values for example to calculate
+// the next address of the pc.
+
 module alu_op_decode (
   input [6:0] opcode,
   input [2:0] funct3,
@@ -13,7 +19,7 @@ module alu_op_decode (
 always @ (*) begin
   if (alu_ctrl == ALU_CTRL_ADD) begin
     alu_op = ALU_OP_ADD;
-  end else if (opcode == OPCODE_REG || opcode == OPCODE_IMM) begin
+  end else if (opcode == OPCODE_REG || opcode == OPCODE_IMM) begin // instruction is of r-type or i-type
     case (funct3)
       FUNCT3_ALU_ADD_SUB: alu_op = (opcode == OPCODE_REG && funct7 == FUNCT7_ALU_SUB) ? ALU_OP_SUB : ALU_OP_ADD;
       FUNCT3_ALU_SLL:     alu_op = ALU_OP_SLL;
@@ -25,12 +31,15 @@ always @ (*) begin
       FUNCT3_ALU_AND:     alu_op = ALU_OP_AND;
       default:            alu_op = ALU_OP_ADD;
     endcase
-  end else if (opcode == OPCODE_BRANCH) begin
+  end else if (opcode == OPCODE_BRANCH) begin // instruction is of b-type
     case (funct3)
+      // compare equality
       FUNCT3_BRANCH_BEQ:  alu_op = ALU_OP_SUB;
       FUNCT3_BRANCH_BNE:  alu_op = ALU_OP_SUB;
+      // compare signed
       FUNCT3_BRANCH_BLT:  alu_op = ALU_OP_SLT;
       FUNCT3_BRANCH_BGE:  alu_op = ALU_OP_SLT;
+      // compare unsigned
       FUNCT3_BRANCH_BLTU: alu_op = ALU_OP_SLTU;
       FUNCT3_BRANCH_BGEU: alu_op = ALU_OP_SLTU;
       default:            alu_op = ALU_OP_ADD;
diff --git a/rtl/src/alu_result_reg.v b/rtl/src/alu_result_reg.v
index cece9e4..377760a 100644
--- a/rtl/src/alu_result_reg.v
+++ b/rtl/src/alu_result_reg.v
@@ -1,3 +1,7 @@
+// alu result reg:
+// Stores alu_result for one more clock cycle.
+// This is used for example on load/store, alu wb, etc.
+
 module alu_result_reg (
   input clk, 
   input rstn,
diff --git a/rtl/src/arithmetic_unit.v b/rtl/src/arithmetic_unit.v
index 1a2282b..e987dbd 100644
--- a/rtl/src/arithmetic_unit.v
+++ b/rtl/src/arithmetic_unit.v
@@ -1,3 +1,6 @@
+// arithmetic unit:
+// Arithmetic part of the alu.
+
 module arithmetic_unit (
   input [31:0] a, 
   input [31:0] b,
diff --git a/rtl/src/clock_divider.v b/rtl/src/clock_divider.v
index a63e943..e673a43 100644
--- a/rtl/src/clock_divider.v
+++ b/rtl/src/clock_divider.v
@@ -1,3 +1,7 @@
+// clock divider:
+// This is used to scale the input clock signal by a certain amount, which then feeds into the cpu,
+// to decrease its frequency, useful for debugging for example.
+
 module clock_divider #( 
   parameter N = 2
 )(
diff --git a/rtl/src/control_unit.v b/rtl/src/control_unit.v
index 28f37d9..f259506 100644
--- a/rtl/src/control_unit.v
+++ b/rtl/src/control_unit.v
@@ -1,3 +1,7 @@
+// control unit:
+// This is a fsm that controls various signals of the cpu and
+// manages its state.
+
 module control_unit (
  input clk, 
  input rstn,
@@ -41,10 +45,11 @@ assign ra1 = instr[19:15];
 assign ra2 = instr[24:20];
 assign wa3 = instr[11:7];
 
+// controls if pc gets updated
+// funct3[0] is 0 for BEQ, BLT, BLTU and 1 for BNE, BGE, BGEU
+// funct3[2] is 0 for BEQ, BNE       and 1 for BLT, BLTU, BGE, BGEU
 assign pc_we = ((alu_zero ^ funct3[0] ^ funct3[2]) & branch) | pc_update;
 
-reg [3:0] state, next_state;
-
 alu_op_decode alu_op_decode (
   .opcode(opcode),
   .alu_ctrl(alu_ctrl),
@@ -70,11 +75,15 @@ always @ (*) begin
   endcase
 end
 
+// state register
+reg [3:0] state, next_state;
+
 always @ (posedge clk or negedge rstn) begin
   if (!rstn) state <= STATE_FETCH;
   else state <= next_state;
 end
 
+// next state logic
 always @ (*) begin
   case(state)
     STATE_FETCH:     next_state = STATE_DECODE;
@@ -111,7 +120,7 @@ always @ (*) begin
 end
 
 
-
+// output/control logic
 always @ (*) begin
   mem_addr_src = MEM_ADDR_SRC_RESULT;
   alu_a_src    = ALU_A_SRC_RD1_BUF;
diff --git a/rtl/src/cpu.v b/rtl/src/cpu.v
index a3b94ff..64e3d49 100644
--- a/rtl/src/cpu.v
+++ b/rtl/src/cpu.v
@@ -1,3 +1,6 @@
+// cpu:
+// Connects the various bit and pieces together.
+
 module cpu (
   input clk,
   input rstn,
diff --git a/rtl/src/data_reg.v b/rtl/src/data_reg.v
index 473d50a..1b21a4e 100644
--- a/rtl/src/data_reg.v
+++ b/rtl/src/data_reg.v
@@ -1,3 +1,6 @@
+// data reg:
+// Stores output of memory unit for one more cycle.
+
 module data_reg (
   input clk,
   input rstn,
diff --git a/rtl/src/immediate_extend.v b/rtl/src/immediate_extend.v
index 14a9a33..2b38081 100644
--- a/rtl/src/immediate_extend.v
+++ b/rtl/src/immediate_extend.v
@@ -1,3 +1,6 @@
+// immediate extend:
+// Extracts immediate value from various instruction formats.
+
 module immediate_extend (
   input [31:0] instr,
   input [2:0] imm_src,
diff --git a/rtl/src/instruction_reg.v b/rtl/src/instruction_reg.v
index d98ab6d..d2146b4 100644
--- a/rtl/src/instruction_reg.v
+++ b/rtl/src/instruction_reg.v
@@ -1,3 +1,6 @@
+// instruction reg:
+// Stores current instruction (and pc) until next one gets fetched.
+
 module instruction_reg (
   input clk, 
   input rstn, 
diff --git a/rtl/src/io.v b/rtl/src/io.v
index f53062b..7d6cd4f 100644
--- a/rtl/src/io.v
+++ b/rtl/src/io.v
@@ -1,3 +1,6 @@
+// io:
+// Input and output register, connected to pins of fpga.
+
 module io (
   input clk,
   input rstn,
diff --git a/rtl/src/logic_unit.v b/rtl/src/logic_unit.v
index 8d8b31d..fad0287 100644
--- a/rtl/src/logic_unit.v
+++ b/rtl/src/logic_unit.v
@@ -1,3 +1,6 @@
+// logic unit:
+// Logic part of alu.
+
 module logic_unit (
   input [31:0] a, 
   input [31:0] b,
diff --git a/rtl/src/mem_addr_src_mux.v b/rtl/src/mem_addr_src_mux.v
index 1f34fe1..4ab4509 100644
--- a/rtl/src/mem_addr_src_mux.v
+++ b/rtl/src/mem_addr_src_mux.v
@@ -1,3 +1,6 @@
+// mem addr mux:
+// Selects source mem addr.
+
 module mem_addr_src_mux (
   input [31:0] src_pc, 
   input [31:0] src_result,
diff --git a/rtl/src/memory_interface.v b/rtl/src/memory_interface.v
index 09f05cb..01dfa39 100644
--- a/rtl/src/memory_interface.v
+++ b/rtl/src/memory_interface.v
@@ -1,3 +1,6 @@
+// memory interface:
+// Connects rom, ram and io to memory bus.
+
 module memory_interface (
   input clk,
   input rstn,
diff --git a/rtl/src/pc_reg.v b/rtl/src/pc_reg.v
index d8dfbec..af6f1ea 100644
--- a/rtl/src/pc_reg.v
+++ b/rtl/src/pc_reg.v
@@ -1,3 +1,6 @@
+// pc reg:
+// Stores current pc.
+
 module pc_reg (
   input clk, 
   input rstn,
diff --git a/rtl/src/ram.v b/rtl/src/ram.v
index 541096e..7595e89 100644
--- a/rtl/src/ram.v
+++ b/rtl/src/ram.v
@@ -1,3 +1,6 @@
+// ram:
+// Contains data section of program and is used for stack/heap, etc.
+
 module ram #(
   parameter N = 32, 
   parameter SIZE = 1024
diff --git a/rtl/src/register_file.v b/rtl/src/register_file.v
index dda44e8..ad3f5fe 100644
--- a/rtl/src/register_file.v
+++ b/rtl/src/register_file.v
@@ -1,3 +1,6 @@
+// register file:
+// Registers of the cpu.
+
 module register_file (
   input clk, 
   input rstn, 
diff --git a/rtl/src/register_file_reg.v b/rtl/src/register_file_reg.v
index b1bd4fc..049f53c 100644
--- a/rtl/src/register_file_reg.v
+++ b/rtl/src/register_file_reg.v
@@ -1,3 +1,6 @@
+// register file reg:
+// Stores outputs of register file for one more clock cycle.
+
 module register_file_reg (
   input clk, 
   input rstn,
diff --git a/rtl/src/reset_synchronizer.v b/rtl/src/reset_synchronizer.v
index dc7a80a..3d68bf7 100644
--- a/rtl/src/reset_synchronizer.v
+++ b/rtl/src/reset_synchronizer.v
@@ -1,3 +1,8 @@
+// reset synchronizer:
+// Is used too ensure that the deassertion of the reset signal 
+// is synchronized with the clock. If the reset signal is deasserted 
+// asynchronously with respect to the clock, it can cause metastability issues.
+
 module reset_synchronizer (
     input clk,
     input rstn_async,
diff --git a/rtl/src/result_mux.v b/rtl/src/result_mux.v
index 3c94617..5cbacb0 100644
--- a/rtl/src/result_mux.v
+++ b/rtl/src/result_mux.v
@@ -1,3 +1,6 @@
+// result mux:
+// Selects source for result.
+
 module result_mux (
   input [31:0] src_alu_result,
   input [31:0] src_alu_result_buf,
diff --git a/rtl/src/rom.v b/rtl/src/rom.v
index 29de1da..f32b9a0 100644
--- a/rtl/src/rom.v
+++ b/rtl/src/rom.v
@@ -1,3 +1,6 @@
+// rom:
+// Contains instructions of program.
+
 module rom #(
   parameter N = 32, 
   parameter SIZE = 1024,
diff --git a/rtl/src/shift_unit.v b/rtl/src/shift_unit.v
index ea83e4a..7dbe4a2 100644
--- a/rtl/src/shift_unit.v
+++ b/rtl/src/shift_unit.v
@@ -1,3 +1,6 @@
+// shift unit:
+// Shift part of alu.
+
 module shift_unit (
   input signed [31:0] a,
   input  [4:0] b,
diff --git a/rtl/src/top.v b/rtl/src/top.v
index b10fbca..d21f807 100644
--- a/rtl/src/top.v
+++ b/rtl/src/top.v
@@ -1,3 +1,6 @@
+// top:
+// Top module, maps signals to fpga.
+
 module top (
 	input clk,
 	input key,