comments

29 files changed, 268 insertions, 130 deletions

diff --git a/README.md b/README.md
index e708037..34c5ab7 100644
--- a/README.md
+++ b/README.md
@@ -92,6 +92,7 @@ riscv_cpu
 * [Computer Organization and Design by David Patterson](https://shop.elsevier.com/books/computer-organization-and-design-risc-v-edition/patterson/978-0-12-820331-6)
 * [Operating Systems: Three Easy Pieces by Remzi and Andrea Arpaci-Dusseau](https://pages.cs.wisc.edu/~remzi/OSTEP/)
 * [Example RISCV Cores](https://github.com/yunchenlo/awesome-RISCV-Cores)
+* [godbolt (compiler explorer)](https://godbolt.org)
 
 ## Design
 
diff --git a/debug/cpu.gtkw b/debug/cpu.gtkw
index 2b6da52..08e251b 100644
--- a/debug/cpu.gtkw
+++ b/debug/cpu.gtkw
@@ -1,163 +1,191 @@
 [*]
 [*] GTKWave Analyzer v3.4.0 (w)1999-2022 BSI
-[*] Wed May 15 13:30:34 2024
+[*] Tue May 21 13:54:43 2024
 [*]
 [dumpfile] "/Users/flavian/Documents/hobbies/electronics/projects/riscv_cpu/build/waveform_cpu.vcd"
-[dumpfile_mtime] "Wed May 15 07:27:23 2024"
-[dumpfile_size] 6990688
+[dumpfile_mtime] "Tue May 21 13:32:51 2024"
+[dumpfile_size] 9041510
 [savefile] "/Users/flavian/Documents/hobbies/electronics/projects/riscv_cpu/debug/cpu.gtkw"
-[timestart] 2404400
-[size] 760 916
-[pos] -1 -1
-*-15.000000 2445000 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1
-[treeopen] testbench_register_file.
-[treeopen] testbench_register_file.cpu.
-[treeopen] testbench_register_file.cpu.control_unit.
-[sst_width] 39
-[signals_width] 202
-[sst_expanded] 0
+[timestart] 0
+[size] 1512 945
+[pos] -1 -2
+*-15.000000 34400 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1
+[treeopen] testbench_cpu.
+[treeopen] testbench_cpu.cpu.
+[sst_width] 253
+[signals_width] 289
+[sst_expanded] 1
 [sst_vpaned_height] 278
-@28
-testbench_register_file.clk
-testbench_register_file.rst
 @24
-testbench_register_file.clk_cycle_count[31:0]
-@200
--
-@22
-[color] 2
-testbench_register_file.cpu.control_unit.state[3:0]
-@28
-testbench_register_file.cpu.instr_we
-@23
-testbench_register_file.cpu.instr[31:0]
+[color] 6
+testbench_cpu.clk_cycle_count[31:0]
 @28
-testbench_register_file.cpu.control_unit.opcode[6:0]
-testbench_register_file.cpu.control_unit.funct3[2:0]
-@22
-testbench_register_file.cpu.control_unit.funct7[6:0]
+[color] 6
+testbench_cpu.clk
+[color] 6
+testbench_cpu.rst
 @200
 -
 @22
-testbench_register_file.cpu.imm[31:0]
+[color] 1
+testbench_cpu.cpu.control_unit.state[3:0]
 @200
 -
+-PC
 @22
-testbench_register_file.cpu.pc[31:0]
-testbench_register_file.cpu.pc_buf[31:0]
+[color] 4
+testbench_cpu.cpu.pc[31:0]
+[color] 2
+testbench_cpu.cpu.pc_buf[31:0]
 @28
-testbench_register_file.cpu.pc_we
+[color] 5
+testbench_cpu.cpu.pc_we
 @200
 -
+-Instruction
 @22
-testbench_register_file.cpu.mem_addr[31:0]
-testbench_register_file.cpu.mem_rd[31:0]
-testbench_register_file.cpu.rd2_buf[31:0]
+[color] 7
+testbench_cpu.cpu.instr[31:0]
 @28
-testbench_register_file.cpu.mem_we
-@22
-testbench_register_file.cpu.data_buf[31:0]
-@200
--
+[color] 4
+testbench_cpu.cpu.control_unit.opcode[6:0]
+[color] 4
+testbench_cpu.cpu.control_unit.funct3[2:0]
+[color] 4
+testbench_cpu.cpu.control_unit.funct7[6:0]
 @22
-[color] 5
-testbench_register_file.cpu.alu_a[31:0]
-[color] 5
-testbench_register_file.cpu.alu_b[31:0]
+[color] 4
+testbench_cpu.cpu.imm[31:0]
 @28
 [color] 5
-testbench_register_file.cpu.alu_b_src[1:0]
+testbench_cpu.cpu.instr_we
+@200
+-
+-Memory
 @22
-[color] 5
-testbench_register_file.cpu.alu_op[3:0]
+[color] 3
+testbench_cpu.cpu.mem_addr[31:0]
+[color] 4
+testbench_cpu.cpu.mem_rd[31:0]
+[color] 2
+testbench_cpu.cpu.data_buf[31:0]
+[color] 4
++{testbench_cpu.cpu.mem_wd[31:0]} testbench_cpu.cpu.rd2_buf[31:0]
 @28
-testbench_register_file.cpu.control_unit.alu_ctrl
-testbench_register_file.cpu.alu_zero
-@22
 [color] 5
-testbench_register_file.cpu.alu_result[31:0]
+testbench_cpu.cpu.mem_we
 @200
 -
+-ALU
 @22
-testbench_register_file.cpu.result[31:0]
+[color] 4
+testbench_cpu.cpu.alu_a[31:0]
+[color] 4
+testbench_cpu.cpu.alu_b[31:0]
+[color] 4
+testbench_cpu.cpu.alu_result[31:0]
+[color] 2
+testbench_cpu.cpu.alu_result_buf[31:0]
+@28
+[color] 5
+testbench_cpu.cpu.alu_op[3:0]
 @200
 -
+-Register File
 @22
 [color] 3
-testbench_register_file.cpu.register_file.ra1[4:0]
+testbench_cpu.cpu.ra1[4:0]
 [color] 3
-testbench_register_file.cpu.register_file.ra2[4:0]
+testbench_cpu.cpu.ra2[4:0]
 [color] 3
-testbench_register_file.cpu.register_file.wa3[4:0]
+testbench_cpu.cpu.wa3[4:0]
+[color] 4
+testbench_cpu.cpu.rd1[31:0]
+[color] 2
+testbench_cpu.cpu.rd1_buf[31:0]
+[color] 4
+testbench_cpu.cpu.rd2[31:0]
+[color] 2
+testbench_cpu.cpu.rd2_buf[31:0]
+[color] 4
+testbench_cpu.cpu.result[31:0]
 @28
-[color] 3
-testbench_register_file.cpu.rf_we
+[color] 5
+testbench_cpu.cpu.rf_we
 @200
 -
 @22
-[color] 3
-testbench_register_file.cpu.register_file.reg_x0_zero[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x1_ra[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x2_sp[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x3_gp[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x4_tp[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x5_t0[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x6_t1[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x7_t2[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x8_s0_fp[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x9_s1[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x10_a0[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x11_a1[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x12_a2[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x13_a3[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x14_a4[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x15_a5[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x16_a6[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x17_a7[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x18_s2[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x19_s3[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x20_s4[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x21_s5[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x22_s6[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x23_s7[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x24_s8[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x25_s9[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x26_s10[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x27_s11[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x28_t3[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x29_t4[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x30_t5[31:0]
-[color] 3
-testbench_register_file.cpu.register_file.reg_x31_t6[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x0_zero[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x1_ra[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x2_sp[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x3_gp[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x4_tp[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x5_t0[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x6_t1[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x7_t2[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x8_s0_fp[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x9_s1[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x10_a0[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x11_a1[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x12_a2[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x13_a3[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x14_a4[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x15_a5[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x16_a6[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x17_a7[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x18_s2[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x19_s3[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x20_s4[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x21_s5[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x22_s6[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x23_s7[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x24_s8[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x25_s9[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x26_s10[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x27_s11[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x28_t3[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x29_t4[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x30_t5[31:0]
+[color] 6
+testbench_cpu.cpu.register_file.reg_x31_t6[31:0]
+@200
+-
+-IO
+@23
+[color] 4
+testbench_cpu.cpu.io_in[31:0]
+[color] 4
+testbench_cpu.cpu.io_out[31:0]
 [pattern_trace] 1
 [pattern_trace] 0
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,
diff --git a/sim/testbenches/src/testbench_cpu.v b/sim/testbenches/src/testbench_cpu.v
index ba40dc2..7c7ec67 100644
--- a/sim/testbenches/src/testbench_cpu.v
+++ b/sim/testbenches/src/testbench_cpu.v
@@ -1,6 +1,6 @@
 `timescale 1ns / 1ps
 
-module testbench_register_file();
+module testbench_cpu();
 
 reg clk;
 reg rst;
@@ -41,7 +41,7 @@ end
   
 initial begin
   $dumpfile(waveform_filename);
-  $dumpvars(0,testbench_register_file);
+  $dumpvars(0,testbench_cpu);
 end