Merge pull request #2615 from Pinata-Consulting/variables-setup-hold-slack-docs

Variables setup hold slack docs

Author: maliberty

flow/scripts/variables.yaml

@@ -211,8 +211,8 @@ FLOORPLAN_DEF:
 REMOVE_ABC_BUFFERS:
   description: >
     Remove abc buffers from the netlist. If timing repair in floorplanning is
-    taking too long, use a SETUP_HOLD_MARGIN to terminate timing repair early
-    instead of using REMOVE_ABC_BUFFERS or set SKIP_LAST_GAST=1.
+    taking too long, use a SETUP/HOLD_SLACK_MARGIN to terminate timing repair early
+    instead of using REMOVE_ABC_BUFFERS or set SKIP_LAST_GASP=1.
   stages:
     - floorplan
   deprecated: 1
@@ -384,16 +384,45 @@ HOLD_SLACK_MARGIN:
     This option allows you to overfix or underfix(negative value, terminate
     retiming before 0 or positive slack).
 
-    Use min of HOLD_SLACK_MARGIN and 0(default hold slack margin) in floorplan.
+    floorplan.tcl uses min of HOLD_SLACK_MARGIN and 0(default hold slack margin).
 
     This avoids overrepair in floorplan for hold by default, but allows skipping
     hold repair using a negative HOLD_SLACK_MARGIN.
 
     Exiting timing repair early is useful in exploration where
-
-    the .sdc has a fixed clock period at designs target clock period and where
+    the .sdc has a fixed clock period at the design's target clock period and where
     HOLD/SETUP_SLACK_MARGIN is used to avoid overrepair(extremely long running
     times) when exploring different parameter settings.
+
+    When an ideal clock is used, that is before CTS,
+    a clock insertion delay of 0 is used in timing paths. This creates
+    a mismatch between macros that have a .lib file from after CTS, when
+    the clock is propagated. To mitigate this, OpenSTA will use subtract
+    the clock insertion delay of macros when calculating timing with ideal
+    clock. Provided that min_clock_tree_path
+    and max_clock_tree_path are in the .lib file, which is the case for
+    macros built with OpenROAD. This is less accurate than if OpenROAD had
+    created a placeholder clock tree for timing estimation purposes
+    prior to CTS.
+
+    There will inevitably be inaccuracies in the timing calculation prior
+    to CTS. Use a slack margin that is low enough, even negative, to
+    avoid overrepair. Inaccuracies in the timing prior to CTS can also
+    lead to underrepair, but there no obvious and simple way to avoid
+    underrapir in these cases.
+
+    Overrepair can lead to excessive runtimes in repair or too much buffering
+    being added, which can present itself as congestion of hold cells or
+    buffer cells.
+
+    Another use of SETUP/HOLD_SLACK_MARGIN is design parameter exploration
+    when trying to find the minimum clock period for a design.
+
+    The SDC_FILE for a design can be quite complicated and instead of
+    modifying the clock period in the SDC_FILE, which can be non-trivial,
+    the clock period can be fixed at the target frequency and the
+    SETUP/HOLD_SLACK_MARGIN can be swept to find a plausible
+    current minimum clock period.
   stages:
     - cts
     - floorplan
@@ -404,6 +433,8 @@ SETUP_SLACK_MARGIN:
     Specifies a time margin for the slack when fixing setup violations.
     This option allows you to overfix or underfix(negative value, terminate
     retiming before 0 or positive slack).
+
+    See HOLD_SLACK_MARGIN for more details.
   stages:
     - cts
     - floorplan