First working version of regex_coprocessor with multiple basic blocks.

Fix problem with elapsed clock cycles.
 	The problem arises from the fact that AXI_top once the coprocessor accept the string goes into STATUS_ACCEPTED from which it was possible to receive a new START.
	If the latency introduced by the AXI interface was so high that it's not possible to overwrite the command START, with a command NOP, before the regex_coprocessor has finished is duty, the AXI_top FSM may interpret command_START in the register as a new request of performing a new regular expression matching. To avoid that STATUS_ACCEPTED and STATUS_REJECTED have a different behaviour w.r.t. STATUS_IDLE and it is no longer possible to send CMD_START as soon as the regex_coprocessor work is over. For this reason a new command(CMD_RESTART) that moves from those states, to IDLE has been introduced.
Add an overall description at the beginning of most complex modules in the design, and in some cases even illustration to better clarify component connections.
Enhance readability of re2_driver introducing enums to carry constants and method wrapper to simplify the code.
Add support in re2_driver for the new command
Add support in re2_driver to reuse previously compiled regular expressions.

Author: DanieleParravicini

rtl_src/AXI_package.sv

@@ -1,5 +1,6 @@
 `timescale 1ns/1ps
-
+//contains signals used to interface regex_coprocessor
+//and software.
 package AXI_package;
 localparam REG_WIDTH                = 32;
 parameter  CMD_NOP                  = 'h0000_0000 ;
@@ -8,6 +9,7 @@ parameter  CMD_READ                 = 'h0000_0002 ;
 parameter  CMD_START                = 'h0000_0003 ;
 parameter  CMD_RESET                = 'h0000_0004 ;
 parameter  CMD_READ_ELAPSED_CLOCK   = 'h0000_0005 ;
+parameter  CMD_RESTART              = 'h0000_0006 ;
 
 
 parameter  STATUS_IDLE              = 'h0000_0000 ;

rtl_src/AXI_top.sv

@@ -2,9 +2,13 @@
 
 import AXI_package::*;
 
+//component intended to decouple the regex_coprocessor and the AXI interface.
+//It contains the memory of the regex_coprocessor so that is possible to show outside the contetn of the memory
+//It implements some commands that are intended to drive the regex_coprocessor and other component from software. 
+
 module AXI_top(
     input  logic                               clk,
-    input  logic                             reset, //reset has to be implemented using cmd_register?
+    input  logic                             reset,
     input  logic [REG_WIDTH-1:0]  data_in_register,
     input  logic [REG_WIDTH-1:0]  address_register,
 //  input  logic [REG_WIDTH-1:0] start_pc_register,
@@ -88,7 +92,7 @@ begin
     start_cc_pointer                   = { (BRAM_ADDR_WIDTH){1'b0} }; 
 
     case(status_register)
-    STATUS_IDLE, STATUS_ACCEPTED, STATUS_REJECTED:
+    STATUS_IDLE:
     begin   
         if(cmd_register == CMD_WRITE) // to write the content of memory write in seuqence addr_0, cmd_write, data_0, 
         begin      // addr_1, data_1, ..., cmd_nop.
@@ -114,7 +118,8 @@ begin
             bram_addr           = memory_addr_from_coprocessor;
             bram_valid_in       = memory_addr_from_coprocessor_valid;
             memory_addr_from_coprocessor_ready = 1'b1;
-            
+            elapsed_cc_next     = {(REG_WIDTH){1'b0}};
+
             if( start_valid )
             begin
                 status_register_next = STATUS_RUNNING;
@@ -125,6 +130,34 @@ begin
             data_o_register     = elapsed_cc;
         end
 
+    end
+    STATUS_ACCEPTED, STATUS_REJECTED:
+    begin   
+        if(cmd_register == CMD_WRITE) // to write the content of memory write in seuqence addr_0, cmd_write, data_0, 
+        begin      // addr_1, data_1, ..., cmd_nop.
+            
+            bram_addr           = address_register[0+:BRAM_ADDR_WIDTH]; //use low
+            bram_in             = { ^(data_in_register[31:24]),data_in_register[31:24], ^(data_in_register[23:16]), data_in_register[23:16], ^(data_in_register[15:8]), data_in_register[15:8],  ^(data_in_register[7:0]), data_in_register[7:0] };
+            bram_valid_in       = 1'b1;
+            bram_we             = { (BRAM_WE_WIDTH) {1'b1} };
+            data_o_register     = bram_o_register;
+        end
+        else if(cmd_register == CMD_READ)
+        begin      
+            bram_addr           = address_register[0+:BRAM_ADDR_WIDTH]; //use low
+            bram_valid_in       = 1'b1;
+            memory_addr_from_coprocessor_ready = 1'b0;
+            data_o_register     = bram_o_register;
+        end
+        else if(cmd_register == CMD_RESTART)
+        begin
+            status_register_next = STATUS_IDLE;
+        end
+        else if(cmd_register == CMD_READ_ELAPSED_CLOCK)
+        begin
+            data_o_register     = elapsed_cc;
+        end
+        
     end
     STATUS_RUNNING:
     begin 
@@ -180,7 +213,6 @@ regex_coprocessor_single_bb #(
     .memory_data        (bram_payload),
     .memory_valid       (memory_addr_from_coprocessor_valid ),
     .start_ready        (start_ready),
-    //.start_pc           (start_pc),
     .start_cc_pointer   (start_cc_pointer),
     .start_valid        (start_valid),
     .finish             (finish),
@@ -195,7 +227,7 @@ regex_coprocessor_n_bb #(
     .MEMORY_ADDR_WIDTH      (BRAM_ADDR_WIDTH  ), 
     .LATENCY_COUNT_WIDTH    (7),
     .FIFO_COUNT_WIDTH       (6),
-    .BB_N                   (1)
+    .BB_N                   (5)
 )a_regex_coprocessor (
     .clk                (clk),
     .reset              (reset_master),

rtl_src/basic_block.sv

@@ -1,4 +1,40 @@
 `timescale 1ns/1ps
+//wraps 
+//1.a regex_cpu and 
+//2.two fifos to save instructions in the form of their program counters 
+//  for current and next character.
+//                                                                                                    
+//                                                                            /-<memory_data          
+//                                                                          /--->memory_addr          
+//                                   +------------------------------------------>memory_valid         
+//+----------------------------------|------------------------+             \---<memory_ready         
+//|                     Basic block  |                        |                                       
+//|                                  |                        |                                       
+//|                                  |                        |                                       
+//|                          +-------|------+                 |                                       
+//|                          | Regex_cpu    |                 |             /--->output_pc_valid      
+//|                  +-----> |              ------>----------------------------->output_pc_and current
+//|                  |       |              |                 |             \---<output_pc_ready      
+//|                  |       +--------------+                 |                                       
+//|                  |                             input_pc_and_current[0]                            
+//|                  |   +------------------+     +-----+     |                                       
+//|                  +----  curr_char_fifo  <-----|--+  |     |                                       
+//|                      +------------------+  |demux|  |     |             /---<input_pc_valid       
+//|                      +------------------+  |     <--------------------------<input_pc_and_current 
+//| 0<--data_out_ready---|  next_char_fifo  <--------+  +----------------------->input_pc_ready       
+//|                      +------------------+           |     |                                       
+//|                                                     |     |                                       
+//|                            even_in_ready            |     |                                       
+//|                            and ---------------------+     |                                       
+//|                            odd_in_ready                   |                                       
+//|                                                           |                                       
+//+-----------------------------------------------------------+                                       
+//note that:                                                                                                    
+//- curr_char_fifo and next_char_fifo are implemented by 2 fifos(called odd/even)
+//  in which inputs/outputs are muxed/demuxed via cur_is_even_character (input)                                                                                                      
+//  not represented for sake of drawing simplicity                                                                                                  
+                                                                                                                                                             
+
 module basic_block #(
     parameter  PC_WIDTH            = 8 ,
     parameter  LATENCY_COUNT_WIDTH = 8 ,
@@ -30,9 +66,10 @@ module basic_block #(
     input   logic[LATENCY_COUNT_WIDTH-1:0]  output_pc_latency
 
 );
+    //output latency is unused by basic block.
     wire [LATENCY_COUNT_WIDTH-1:0] output_pc_latency_unused;
     assign output_pc_latency_unused = output_pc_latency;
-    
+    //sub signals of input_pc_and_current, output_pc_and_current
     logic [PC_WIDTH-1:0]        output_pc, input_pc;
     logic                       input_pc_is_directed_to_current, output_pc_is_directed_to_current;
 
@@ -75,9 +112,6 @@ module basic_block #(
     logic [FIFO_COUNT_WIDTH-1:0]fifo_next_char_data_count    ;
 
     //FIFO even instantiation 
-    assign fifo_even_data_in_ready  = ~ fifo_even_data_in_not_ready ;
-    assign fifo_even_data_out_valid = ~ fifo_even_data_out_not_valid;
-    
     fifo #(
         .DWIDTH(PC_WIDTH),
         .COUNT_WIDTH(FIFO_COUNT_WIDTH)
@@ -89,13 +123,14 @@ module basic_block #(
         .wr_en       (fifo_even_data_in_valid     ), //equivalent to data_in_valid
         .rd_en       (fifo_even_data_out_ready    ), //equivalent to data_out_ready
         .dout        (fifo_even_data_out          ), 
-        .data_count  (fifo_even_data_count        ),
-        .empty       (fifo_even_data_out_not_valid) //equivalent to not data_out_valid
+        .empty       (fifo_even_data_out_not_valid), //equivalent to not data_out_valid
+        .data_count  (fifo_even_data_count        )
     );
+    //conclusion fifo even instatiation convert negated not_ready/not_valid signals to "standard" ready/valid interface.
+    assign fifo_even_data_in_ready  = ~ fifo_even_data_in_not_ready ;
+    assign fifo_even_data_out_valid = ~ fifo_even_data_out_not_valid;
+
     //FIFO odd instantiation 
-    assign fifo_odd_data_in_ready  = ~ fifo_odd_data_in_not_ready ;
-    assign fifo_odd_data_out_valid = ~ fifo_odd_data_out_not_valid;
-    
     fifo #(
         .DWIDTH(PC_WIDTH),
         .COUNT_WIDTH(FIFO_COUNT_WIDTH)
@@ -110,12 +145,15 @@ module basic_block #(
         .data_count  (fifo_odd_data_count        ),
         .empty       (fifo_odd_data_out_not_valid) //equivalent to not data_out_valid
     );
+    //conclusion fifo odd instatiation convert negated not_ready/not_valid signals to "standard" ready/valid interface.
+    assign fifo_odd_data_in_ready  = ~ fifo_odd_data_in_not_ready ;
+    assign fifo_odd_data_out_valid = ~ fifo_odd_data_out_not_valid;
 
     //select fifo current and fifo next according to cur_is_even_character signal
     always_comb begin : selector_fifo_current_fifo_next
 
         if ( cur_is_even_character == 1'b1  )
-        begin
+        begin //even is current and odd is next_char
             fifo_cur_char_data_in_ready   =  fifo_even_data_in_ready      ;
             fifo_even_data_in             =  fifo_cur_char_data_in        ;
             fifo_even_data_in_valid       =  fifo_cur_char_data_in_valid  ; 
@@ -133,7 +171,7 @@ module basic_block #(
             fifo_next_char_data_count     =  fifo_odd_data_count          ;
         end
         else
-        begin
+        begin //odd is current and even is next_char
             fifo_cur_char_data_in_ready   =  fifo_odd_data_in_ready       ;
             fifo_odd_data_in              =  fifo_cur_char_data_in        ;
             fifo_odd_data_in_valid        =  fifo_cur_char_data_in_valid  ; 
@@ -152,45 +190,50 @@ module basic_block #(
         end                        
     end
 
-    // make so that pc referring to next char are not consumed. 
+    // make so that content of fifo_next_char is not consumed. 
     assign fifo_next_char_data_out_ready = 1'b0;
 
-    //ouput pc is redirected toward output after having concatenated 
+    //output_pc is redirected toward output after having concatenated with output_pc_is_directed_to_current
     assign output_pc_and_current = {output_pc, output_pc_is_directed_to_current};
-    //input pc and current is splitted in input_pc and input_pc_is_directed_to_current
+    //input_pc_and_current is splitted in input_pc and input_pc_is_directed_to_current
     assign input_pc_is_directed_to_current = input_pc_and_current[0];
     assign input_pc                        = input_pc_and_current[1+:PC_WIDTH] ;
 
-    //demux 
+    //demux to drive input_pc_and_current toward correct fifo.
+    //to avoid a combinational loop (switches can decide to move data toward one or the other output port depending on output ready, but in principle output ready depends also on targeted fifo which is specified in data). 
+    //conservative(certain instruction which in principle could have been stored are refused) but correct
+    assign input_pc_ready         = fifo_cur_char_data_in_ready && fifo_next_char_data_in_ready;
     always_comb begin : demux_for_pc_in 
         fifo_cur_char_data_in  = { PC_WIDTH{1'b0} };
         fifo_next_char_data_in = { PC_WIDTH{1'b0} };
-        //to avoid a combinational loop 
-        input_pc_ready         = fifo_cur_char_data_in_ready && fifo_next_char_data_in_ready;
+        
         if(input_pc_is_directed_to_current)
         begin
             fifo_cur_char_data_in       = input_pc ;
-            fifo_cur_char_data_in_valid = input_pc_valid ;
+            fifo_cur_char_data_in_valid = input_pc_valid && input_pc_ready; //since for outside bb input is ready if both fifo_cur_char and fifo_next_char are ready, their valid has to take into account that to avoid that fifo_latches it  
 
             fifo_next_char_data_in_valid= 1'b0;
         end
         else
         begin
             fifo_next_char_data_in       = input_pc ;
-            fifo_next_char_data_in_valid = input_pc_valid ;
+            fifo_next_char_data_in_valid = input_pc_valid && input_pc_ready; //since for outside bb input is ready if both fifo_cur_char and fifo_next_char are ready, their valid has to take into account that to avoid that fifo_latches it  
 
             fifo_cur_char_data_in_valid  = 1'b0;
         end
     end
 
-    //compute the approximate latency seen outside
+    //compute the approximate latency seen outside thought of max between odd and even but lead to high fanout-> setup violation
+    //opted for a simpler computation: consider only fifo_cur_char length.
     //always_comb begin : latency_computation
     //    if( fifo_odd_data_count > fifo_even_data_count)  input_pc_latency = fifo_odd_data_count  + 1; 
     //    else                                             input_pc_latency = fifo_even_data_count + 1;      
     //end
     assign input_pc_latency = fifo_cur_char_data_count + 1 ;
-    //running if regex_cpu has taken some instruction and the data_out_ready=0
-    //        or some instructions are saved in curr character fifo
+    
+    
+    //running if regex_cpu has taken some instruction and hence the data_out_ready=0
+    //        or some instructions are saved in curr character fifo and hence fifo_cur_char_data_out_valid=1
     always_comb begin : running_definition
         running = fifo_cur_char_data_out_valid || ~fifo_cur_char_data_out_ready;
     end

rtl_src/fifo.sv

@@ -1,7 +1,9 @@
 `timescale 1ns/1ps
-
+//This module implements a parametric queue
+//It provides also an output which signals how many values have been 
+//stored inside the queue. 
 module fifo #(
-    parameter DWIDTH         = 16,
+    parameter DWIDTH          = 16,
     parameter COUNT_WIDTH     = 5
 )(
   input  logic                  clk,
@@ -16,9 +18,9 @@ module fifo #(
 );
 
 logic [COUNT_WIDTH-1:0] head; 
-logic [COUNT_WIDTH  :0] head_incremented;
+logic [COUNT_WIDTH-1:0] head_incremented;
 logic [COUNT_WIDTH-1:0] tail;
-logic [COUNT_WIDTH  :0] tail_incremented;
+logic [COUNT_WIDTH-1:0] tail_incremented;
 logic [DWIDTH-1:0]      content [(1<<COUNT_WIDTH)-1:0];
 
 always_ff @( posedge clk ) begin 
@@ -33,7 +35,7 @@ always_ff @( posedge clk ) begin
         if(wr_en == 1'b1 && full == 1'b0 )
         begin
             content[tail] <= din; 
-            tail          <= tail_incremented[0+:COUNT_WIDTH];
+            tail          <= tail_incremented;
         end 
         else
         begin
@@ -43,7 +45,7 @@ always_ff @( posedge clk ) begin
         if(rd_en == 1'b1 && empty == 1'b0 )
         begin
             //content[head] <= { DWIDTH {1'b0} }; 
-            head          <= head_incremented[0+:COUNT_WIDTH];
+            head          <= head_incremented;
         end 
         else
         begin
@@ -61,11 +63,11 @@ always_comb begin
     //for fall through
     dout = content[head];
     //empty
-    if( head == tail ) empty = 1'b1;
-    else               empty = 1'b0;
+    if( head == tail )            empty = 1'b1;
+    else                          empty = 1'b0;
     //full
-    if( head == tail_incremented[0+:COUNT_WIDTH]) full = 1'b1;
-    else                                          full = 1'b0;
+    if( head == tail_incremented) full = 1'b1;
+    else                          full = 1'b0;
 
 end