comments

25 files changed, 97 insertions, 5 deletions

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,