FEATURE: Add read_vcd -begin_time/-end_time activity windowing (#466)

* Add read_vcd -begin_time/-end_time activity windowing.

Limit VCD transition and duty counting to an optional time window so
activity annotation can ignore regions outside the interval of interest.

Co-authored-by: Cursor <[email protected]>

* Format VcdCount::setFilter parameters one per line.

Co-authored-by: Cursor <[email protected]>

* Address VCD begin/end review: VcdTime, sentinel, rename.

Use VcdTime and vcd_null_time instead of int64_t/-1, rename
VcdCount filter bounds to begin/end_time, rename the regression to
vcd_begin_end_time, and document read_vcd -begin_time/-end_time in
ChangeLog.txt.

Co-authored-by: Cursor <[email protected]>

---------

Co-authored-by: Cursor <[email protected]>
Co-authored-by: James Cherry <[email protected]>

test/regression_vars.tcl

@@ -169,6 +169,7 @@ record_public_tests {
   report_json2
   suppress_msg
   user_properties
+  vcd_begin_end_time
   verilog_attribute
   verilog_well_supplies
   verilog_specify

test/vcd_begin_end_time.ok

@@ -0,0 +1,60 @@
+Annotated 2 pin activities.
+Pin Name Activity Duty Cycle
+--------------------------------------------------------
+u_inv/Y 0.0666665 0.667
+u_inv/A 0.0666665 0.333
+
+Annotated 2 pin activities.
+Pin Name Activity Duty Cycle
+--------------------------------------------------------
+u_inv/Y 0.1 1.000
+u_inv/A 0.1 0.000
+
+Annotated 2 pin activities.
+Pin Name Activity Duty Cycle
+--------------------------------------------------------
+u_inv/Y 0.2 0.000
+u_inv/A 0.2 1.000
+
+Annotated 2 pin activities.
+Pin Name Activity Duty Cycle
+--------------------------------------------------------
+u_inv/Y 0.1 1.000
+u_inv/A 0.1 0.000
+
+Annotated 2 pin activities.
+Pin Name Activity Duty Cycle
+--------------------------------------------------------
+u_inv/Y 0.25 0.500
+u_inv/A 0.25 0.500
+
+Annotated 2 pin activities.
+Pin Name Activity Duty Cycle
+--------------------------------------------------------
+u_inv/Y 0.125 0.750
+u_inv/A 0.125 0.250
+
+Annotated 2 pin activities.
+Pin Name Activity Duty Cycle
+--------------------------------------------------------
+u_inv/Y 0.125 0.250
+u_inv/A 0.125 0.750
+
+Annotated 2 pin activities.
+Pin Name Activity Duty Cycle
+--------------------------------------------------------
+u_inv/Y 0.25 0.500
+u_inv/A 0.25 0.500
+
+Annotated 2 pin activities.
+Pin Name Activity Duty Cycle
+--------------------------------------------------------
+u_inv/Y 0.125 0.250
+u_inv/A 0.125 0.750
+
+Annotated 2 pin activities.
+Pin Name Activity Duty Cycle
+--------------------------------------------------------
+u_inv/Y 0.125 0.750
+u_inv/A 0.125 0.250
+

test/vcd_begin_end_time.tcl

@@ -0,0 +1,70 @@
+# Report pin activities
+proc report_activities { } {
+  set pins [get_pins -hierarchical *]
+  set clk_freq [expr 1.0 / (10 * 1e-12)]
+  puts "Pin Name Activity Duty Cycle"
+  puts "--------------------------------------------------------"
+  foreach pin $pins {
+    set prop [get_property $pin activity]
+    set transitions_per_sec [lindex $prop 0]
+    set duty [lindex $prop 1]
+    set activity [expr double($transitions_per_sec) / [expr $clk_freq * 2]]
+    puts "[get_full_name $pin] $activity $duty"
+  }
+  puts ""
+}
+
+# Setup
+read_liberty asap7_invbuf.lib.gz
+read_verilog vcd_begin_end_time.v
+link_design top
+
+# Define clock period in ps
+create_clock -name vclk -period 10
+
+# Full VCD reading works (normal behavior)
+# VCD changes at time 50 and 100 (inverter)
+sta::clear_power
+read_vcd vcd_begin_end_time.vcd -scope top
+report_activities
+
+# Read VCD from start to first transition point
+sta::clear_power
+read_vcd vcd_begin_end_time.vcd -scope top -end_time 50
+report_activities
+
+# Read VCD from first transition point to second transition point
+sta::clear_power
+read_vcd vcd_begin_end_time.vcd -scope top -begin_time 50 -end_time 100
+report_activities
+
+# Read VCD from second transition point to end
+sta::clear_power
+read_vcd vcd_begin_end_time.vcd -scope top -begin_time 100
+report_activities
+
+# Read VCD around the first transition point
+sta::clear_power
+read_vcd vcd_begin_end_time.vcd -scope top -begin_time 40 -end_time 60
+report_activities
+
+sta::clear_power
+read_vcd vcd_begin_end_time.vcd -scope top -begin_time 20 -end_time 60
+report_activities
+
+sta::clear_power
+read_vcd vcd_begin_end_time.vcd -scope top -begin_time 40 -end_time 80
+report_activities
+
+# Read VCD around the second transition point (should mirror the first)
+sta::clear_power
+read_vcd vcd_begin_end_time.vcd -scope top -begin_time 90 -end_time 110
+report_activities
+
+sta::clear_power
+read_vcd vcd_begin_end_time.vcd -scope top -begin_time 70 -end_time 110
+report_activities
+
+sta::clear_power
+read_vcd vcd_begin_end_time.vcd -scope top -begin_time 90 -end_time 130
+report_activities

test/vcd_begin_end_time.v

@@ -0,0 +1,14 @@
+`timescale 1ps/1ps
+
+module top (
+    input  wire A,
+    input  wire clk,
+    output wire Y
+);
+
+    INVx2_ASAP7_75t_R u_inv (
+        .A(A),
+        .Y(Y)
+    );
+
+endmodule

test/vcd_begin_end_time.vcd

@@ -0,0 +1,26 @@
+$date
+   Mon Mar 16 2026
+$end
+$version
+   VCD Test File
+$end
+$timescale
+   1ps
+$end
+$scope module top $end
+$var wire 1 ! A $end
+$var wire 1 " Y $end
+$upscope $end
+$enddefinitions $end
+#0
+$dumpvars
+0!
+1"
+$end
+#50
+1!
+0"
+#100
+0!
+1"
+#150