[pattgen,rtl] Add documentation comments to rtl/pattgen_chan.sv

Signed-off-by: Harry Callahan <[email protected]>

hw/ip/pattgen/rtl/pattgen_chan.sv

@@ -80,9 +80,11 @@ module pattgen_chan
     end
   end
 
-  // disable the clock if the previous pattern is complete
+  // Hold the prediv counter and internal clock (PCL) once the previous pattern is complete
   assign clk_en = ~complete_q;
 
+  // Predivision Counter -> Create an internal pulse (prediv_clk_rollover) which advances the
+  // pattern generation state at the input clk frequency scaled down by the predivider.
   assign prediv_clk_rollover = (clk_cnt_q == prediv_q);
   assign clk_cnt_d = (!enable) ? 32'h0:
                      prediv_clk_rollover ? 32'h0 : // Rollover
@@ -96,6 +98,11 @@ module pattgen_chan
     end
   end
 
+  // Generate an internal pattern clock (PCL)
+  // - PCL toggles each time the predivider counter (clk_cnt_q) wraps.
+  // - The internal PCL is zero at the start of the pattern and for the first period, only toggling
+  //   at the end of the first period.
+  // - The internal PCL is inverted at the output flop if configured to do so by the polarity.
   assign pcl_int_d = (!enable) ? 1'h0 :
                      prediv_clk_rollover ? ~pcl_int_q : // Rollover
                      pcl_int_q;
@@ -108,8 +115,10 @@ module pattgen_chan
     end
   end
 
-  // Only update just before the falling edge of pcl_int
-  // Exception: allow reset to zero whenever not enabled
+  // Increment through bits of the pattern register, wrapping when the configured length is
+  // reached. The index then muxes the current bit to the output with 'data_q[bit_cnt_q]'.
+  // - Only update just before the falling edge of pcl_int
+  // - Reset to zero immediately and do not increment when enable is inactive.
   assign bit_cnt_en = (pcl_int_q & prediv_clk_rollover) | (~enable);
   assign bit_cnt_d  = (!enable) ? 6'h0 :
                       (bit_cnt_q == len_q) ? 6'h0 : // Rollover
@@ -123,8 +132,11 @@ module pattgen_chan
     end
   end
 
-  // Only update just bit_cnt_q rolls over to zero.
-  // Exception: allow reset to zero whenever not enabled
+  // Increment a counter for the number of times the pattern data is repeated within a single
+  // activation. When the configured reps count is reached, the END state for this activation is
+  // reached by signalling completion, and the counter resets.
+  // - Increment as bit_cnt_q rolls over to zero.
+  // - Reset to zero immediately and do not increment when enable is inactive.
   assign rep_cnt_en = (bit_cnt_en & (bit_cnt_q == len_q)) | (~enable);
   assign rep_cnt_d  = (!enable) ? 10'h0 :
                       (rep_cnt_q == reps_q) ? 10'h0 : // Rollover
@@ -138,8 +150,9 @@ module pattgen_chan
     end
   end
 
-  // flip the complete bit to 1 whenever the rep_cnt is about to roll over to zero.
-  // Also clear to zero whenever not enabled.
+  // Set the completion signal (complete_q) when rep_cnt reaches the configured limit and rolls
+  // over to zero.
+  // Clear / reset to zero when enable goes inactive.
   assign complete_en = (rep_cnt_en & (rep_cnt_q == reps_q)) | (~enable);
   assign complete_d  = (!enable) ? 1'h0 : 1'h1;
 
@@ -153,12 +166,18 @@ module pattgen_chan
     end
   end
 
+  // Trigger the event-type interrupt upon completion of the pattern.
   assign event_done_o = complete_q & ~complete_q2;
 
+  // Track the state of the pattern generation with the 'active' signal (IDLE/END=0:ACTIVE=1)
+  // _Transitions_
+  // IDLE   -> (enable -> 1)     -> ACTIVE
+  // ACTIVE -> (complete_q -> 1) -> END
+  // ACTIVE -> (enable -> 0)     -> IDLE
+  // END    -> (enable -> 0)     -> IDLE
   assign active_d = complete_q ? 1'b0 : // clearing on completion takes precedence
                     enable     ? 1'b1 : // set to active when enabled (and not complete)
                     active_q;           // otherwise hold
-
   assign active = enable ? active_d : active_q;
 
   always_ff @(posedge clk_i or negedge rst_ni) begin