Commented nets in design

Author: axlan

src/ip/tis100_1.0/hdl/tis100_v1_0_S00_AXI.v

@@ -501,6 +501,7 @@
 	begin
 	      // Address decoding for reading registers
 	      case ( axi_araddr[ADDR_LSB+OPT_MEM_ADDR_BITS:ADDR_LSB] )
+		    // sign extend result from dut
 	        4'h0   : reg_data_out <= { {C_S_AXI_DATA_WIDTH-11{last_read[10]}}, last_read};
 	        4'h1   : reg_data_out <= slv_reg1;
 	        4'h2   : reg_data_out <= slv_reg2;
@@ -545,16 +546,20 @@
 	begin
 		if ( S_AXI_ARESETN == 1'b0 )
 		begin
+			// be ready to read first value available from dut
 			down_out_ready <= 1'b1;
 			up_in_valid <= 1'b0;
 			last_read <= 11'd0;
 		end 
 		else
 		begin
+			// write data received in slv_reg0 over AXI to the up_in_data port of dut
 			if (slv_reg_rden && axi_araddr[ADDR_LSB+OPT_MEM_ADDR_BITS:ADDR_LSB] == 4'h0)
 	        begin
 			    down_out_ready <= 1'b1;
 			end
+			// make next data output from down_out_data from dut available to a
+				// slv_reg0 AXI read
 			if (slv_reg_wren && axi_awaddr[ADDR_LSB+OPT_MEM_ADDR_BITS:ADDR_LSB] == 4'h0)
 	        begin
 				up_in_valid <= 1'b1;

src/ip/tis100_1.0/src/alu.v

@@ -1,13 +1,20 @@
 `timescale 1ns / 1ps
 
+// Module to perform arithmatic operations
+
 module alu(
+        // Code to control the operation the ALU should perform. See my_params.vh
         input [1:0] instr,
+        // The current value of the acc register
         input signed [10:0] acc,
+        // The value to add/sub from the acc register
         input signed [10:0] src,
+        // Result from the ALU operation
         output signed [10:0] out
     );
     `include "my_params.vh"
 
+    // Saturate a 12 bit signed integer so it saturates at +-999
     function [10:0] saturate;
         input signed [11:0] in;
         localparam MIN_VAL = -11'sd999;

src/ip/tis100_1.0/src/dir_manager.v

@@ -1,12 +1,21 @@
 `timescale 1ns / 1ps
 
+// Module to control comunication with adjacent nodes
+
 module dir_manager(
+        // synchronize with posedge of clk
         input clk,
+        // active high reset
         input reset,
+        // source port for current operation
         input [2:0] src,
+        // destination port for current operation
         input [2:0] dst,
+        // data incoming from node to the left
         input signed [10:0] left_in_data,
+        // is that incoming data valid
         input left_in_valid,
+        // will this node be able to read the data this cycle
         output left_in_ready,
         input signed [10:0] right_in_data,
         input right_in_valid,
@@ -17,8 +26,11 @@ module dir_manager(
         input signed [10:0] down_in_data,
         input down_in_valid,
         output down_in_ready,
+        // data to send from this node to the node to the left
         output signed [10:0] left_out_data,
+        // is the output data valid this cycle
         output left_out_valid,
+        // will the other node read the data this cycle
         input left_out_ready,
         output signed [10:0] right_out_data,
         output right_out_valid,
@@ -29,15 +41,23 @@ module dir_manager(
         output signed [10:0] down_out_data,
         output down_out_valid,
         input down_out_ready,
+        // clk_en goes low if this node needs to stall to wait for another node
+            // to read or write data
         output clk_en,
+        // data read from another node as a source for an operation
         output signed [10:0] dir_src_data,
+        // data to write to another as the destination of an operation
         input signed [10:0] dir_dst_data
     );
     `include "my_params.vh"
 
+    // idle, or waiting to source data from another node
     localparam STATE_SRC = 1'd0;
+    // waiting to write data to another node
     localparam STATE_DST = 1'd1;
 
+    // does the targert source or destination port require communicating with
+    // another node?
     function is_dir_target;
     input [2:0] target;
     begin
@@ -46,19 +66,28 @@ module dir_manager(
     end
     endfunction
 
+    // the state of internode communication
     reg state;
 
+    // does the current operation require input from another node
     wire perform_in;
+    // does the current operation require output to another node
     wire perform_out;
+    // register source data in case it needs to be buffered for a move operation
+        // between direction ports (ie. MOV UP DOWN)
     reg signed [10:0] dir_src_data_reg;
+    // use dir_src_data_reg instead of input dir_dst_data if performing move
+        // between direction ports (ie. MOV UP DOWN)
     wire signed [10:0] dir_dst_data_internal;
+    // the result choosing the source input from the different directions
     wire signed [10:0] dir_src_data_internal;
-
+    // when reading from another node, which direction should be selected
     wire [2:0] src_sel;
+    // is this module looking for an input from another node this cycle
     wire src_waiting;
-
+    // does the current read operation need to wait for another node
     wire stall_read;
-
+    // is the correct adjacent node ready to receive this node's write data
     wire dst_available;
 
     assign clk_en = (!stall_read && state == STATE_SRC && !perform_out) || (state == STATE_DST && dst_available);

src/ip/tis100_1.0/src/instr_rom.v

@@ -1,42 +1,39 @@
 `timescale 1ns / 1ps
-//////////////////////////////////////////////////////////////////////////////////
-// Company: 
-// Engineer: 
-// 
-// Create Date: 02/11/2020 05:35:21 PM
-// Design Name: 
-// Module Name: InstrRom
-// Project Name: 
-// Target Devices: 
-// Tool Versions: 
-// Description: 
-// 
-// Dependencies: 
-// 
-// Revision:
-// Revision 0.01 - File Created
-// Additional Comments:
-// 
-//////////////////////////////////////////////////////////////////////////////////
+
+// module to read instructions from rom and control program counter jumps
+
 module instr_rom(
+        // synchronize with posedge of clk
         input clk,
+        // only update values when clk_en is high
         input clk_en,
+        // active high reset
         input reset,
+        // code for whether to perform a jump
         input [3:0] instr,
+        // current ACC register value
         input signed [10:0] acc,
+        // address to jump to if jump is performed
         input signed [10:0] jmp_off,
+        // instruction at current program counter
         output [20:0] opcode
     );
     `include "my_params.vh"
+    // memory file to initialize ROM with
     parameter MEM_INIT_FILE = "";
+    // number of valid instructions in ROM
     parameter NUM_ENTRIES = 5'd10;
 
+    // memory for storing instructinos
     reg [20:0] ram[31:0];
 
+    // program counter pointing to current instruction
     reg [4:0] pc;
+    // does the current operation code for a jump
     wire jmp_en;
-    
+    // address to jump to if jump is to be performed
     wire signed [11:0] pc_jmp;
+    // sign extended pc to avoid signed arithmetic issue
     wire signed [5:0] pc_ext;
 
     assign jmp_en = (instr == OP_JMP) ||

src/ip/tis100_1.0/src/op_decode.v

@@ -1,14 +1,25 @@
 `timescale 1ns / 1ps
 
+// Module for decoding binary instructions
+
 module op_decode(
+        // binary instruction loaded from memory
         input [20:0] op_code,
+        // the source port to load from (only used for some instructions)
         output [2:0] src,
+        // the constant value store in the instruction (only used for some instructions)
         output signed [10:0] const,
+        // the destination port to write to (only used for some instructions)
         output [2:0] dst,
+        // code to control program counter with jump operations
         output [3:0] pc_instr,
+        // code to select arithmatic opterations
         output [1:0] alu_instr,
+        // code to control writing to ACC and BAK registers
         output [1:0] registers_instr,
+        // code to control routing input values
         output [1:0] in_mux_sel,
+        // code to control routing output values
         output out_mux_sel
     );
     `include "my_params.vh"

src/ip/tis100_1.0/src/registers.v

@@ -1,11 +1,19 @@
 `timescale 1ns / 1ps
 
+// Module to control storing values to BAK and ACC registers
+
 module registers(
+        // synchronize with posedge of clk
         input clk,
+        // only update values when clk_en is high
         input clk_en,
+        // active high reset
         input reset,
+        // code to control what operation to perform. See my_params.vh
         input [1:0] instr,
+        // new value to store in ACC during write operation
         input signed [10:0] val_in,
+        // current value of ACC register
         output reg signed [10:0] acc
     );
     `include "my_params.vh"

src/ip/tis100_1.0/src/t21_node.v

@@ -1,30 +1,17 @@
 `timescale 1ns / 1ps
-//////////////////////////////////////////////////////////////////////////////////
-// Company: 
-// Engineer: 
-// 
-// Create Date: 02/11/2020 05:34:23 PM
-// Design Name: 
-// Module Name: T21Node
-// Project Name: 
-// Target Devices: 
-// Tool Versions: 
-// Description: 
-// 
-// Dependencies: 
-// 
-// Revision:
-// Revision 0.01 - File Created
-// Additional Comments:
-// 
-//////////////////////////////////////////////////////////////////////////////////
 
+// TIS100 T21 processing node
 
 module t21_node(
+        // synchronize with posedge of clk
         input clk,
+        // active high reset
         input reset,
+        // data incoming from node to the left
         input signed [10:0] left_in_data,
+        // is that incoming data valid
         input left_in_valid,
+        // will this node be able to read the data this cycle
         output signed left_in_ready,
         input signed [10:0] right_in_data,
         input right_in_valid,
@@ -35,8 +22,11 @@ module t21_node(
         input signed [10:0] down_in_data,
         input down_in_valid,
         output signed down_in_ready,
+        // data to send from this node to the node to the left
         output signed [10:0] left_out_data,
+        // is the output data valid this cycle
         output left_out_valid,
+        // will the other node read the data this cycle
         input signed left_out_ready,
         output signed [10:0] right_out_data,
         output right_out_valid,
@@ -52,23 +42,33 @@ module t21_node(
     parameter MEM_INIT_FILE = "test_mult.mem";
     parameter NUM_ENTRIES = 5'd8;
 
+    // clk_en goes low to stall if dir_manager_0 needs to wait for an adjacent
+        // node
     wire clk_en;
 
+    // current instruction to decode
     wire [20:0] op_code;
-
+    // code to control jumps
     wire [3:0] pc_instr;
+    // which source and destination port does the current operation use
     wire [2:0] src, dst;
+    // what arithmatic operation should be performed
     wire [1:0] alu_instr;
+    // how should the BAK and ACC registers be updated
     wire [1:0] registers_instr;
+    // controls source mux
     wire [1:0] in_mux_sel;
+    // controls destination mux
     wire out_mux_sel;
+    // constant value loaded from current instruction
     wire signed [10:0] const;
 
     wire signed [10:0] acc_reg, alu_output;
-
+    // data from selected source (ACC, direction port, or constant)
     wire signed [10:0] src_input;
+    // data to write to move destination (ALU output, or src_input)
     wire signed [10:0] dst_output;
-
+    // data read from direction source port
     wire signed [10:0] dir_output;
 
     dir_manager dir_manager_0(