retiming: add some more docs

Signed-off-by: Øyvind Harboe <[email protected]>

Author: oharboe

docs/user/FlowVariables.md

@@ -235,7 +235,7 @@ configuration file.
 | <a name="SYNTH_MEMORY_MAX_BITS"></a>SYNTH_MEMORY_MAX_BITS| Maximum number of bits for memory synthesis.| 4096|
 | <a name="SYNTH_MINIMUM_KEEP_SIZE"></a>SYNTH_MINIMUM_KEEP_SIZE| For hierarchical synthesis, we keep modules of larger area than given by this variable and flatten smaller modules. The area unit used is the size of a basic nand2 gate from the platform's standard cell library. The default value is platform specific.| 0|
 | <a name="SYNTH_NETLIST_FILES"></a>SYNTH_NETLIST_FILES| Skips synthesis and uses the supplied netlist files. If the netlist files contains duplicate modules, which can happen when using hierarchical synthesis on indvidual netlist files and combining here, subsequent modules are silently ignored and only the first module is used.| |
-| <a name="SYNTH_RETIME_MODULES"></a>SYNTH_RETIME_MODULES| List of modules to apply retiming to. These modules must not get dissolved and as such they should either be the top module or be included in SYNTH_KEEP_MODULES. This is an experimental option and may cause adverse effects.| |
+| <a name="SYNTH_RETIME_MODULES"></a>SYNTH_RETIME_MODULES| *This is an experimental option and may cause adverse effects.* *No effort has been made to check if the retimed RTL is logically equivalent to the non-retimed RTL.* List of modules to apply automatic retiming to. These modules must not get dissolved and as such they should either be the top module or be included in SYNTH_KEEP_MODULES. Architectural or manual retiming, as opposed to automatic retiming, is usually preferred, because LEC(Logic Equivalence Check) will not work together with automatic retiming. The main use-case for automatic retiming is to quickly identify if performance is left on the table and can be gained with architectural retiming. Architectural retiming also has the advantage that it can change the semantics of the RTL code limited only by not breaking the application, hence retiming can't estimate this performance potential. Architectural retiming can also consider placement and routing, whereas automatic retiming only considers information available at synthesis time. The current retiming will treat module ports like register endpoints/startpoints and the objective isn't informed by SDC, even the clock period is ignored.| |
 | <a name="SYNTH_WRAPPED_OPERATORS"></a>SYNTH_WRAPPED_OPERATORS| Synthesize multiple architectural options for each arithmetic operator in the design. These options are available for switching among in later stages of the flow.| |
 | <a name="TAPCELL_TCL"></a>TAPCELL_TCL| Path to Endcap and Welltie cells file.| |
 | <a name="TAP_CELL_NAME"></a>TAP_CELL_NAME| Name of the cell to use in tap cell insertion.| |

flow/scripts/variables.yaml

@@ -202,10 +202,29 @@ SYNTH_CANONICALIZE_TCL:
     - synth
 SYNTH_RETIME_MODULES:
   description: >
-    List of modules to apply retiming to. These modules must not get
+    *This is an experimental option and may cause adverse effects.*
+
+    *No effort has been made to check if the retimed RTL
+    is logically equivalent to the non-retimed RTL.*
+
+    List of modules to apply automatic retiming to. These modules must not get
     dissolved and as such they should either be the top module or be included
-    in SYNTH_KEEP_MODULES. This is an experimental option and may cause adverse
-    effects.
+    in SYNTH_KEEP_MODULES.
+
+    Architectural or manual retiming, as opposed to automatic retiming, is
+    usually preferred, because LEC(Logic Equivalence Check) will not work
+    together with automatic retiming.
+
+    The main use-case for automatic retiming is to quickly identify if
+    performance is left on the table and can be gained with architectural
+    retiming. Architectural retiming also has the advantage that it can change
+    the semantics of the RTL code limited only by not breaking the application,
+    hence retiming can't estimate this performance potential. Architectural retiming
+    can also consider placement and routing, whereas automatic retiming only
+    considers information available at synthesis time.
+
+    The current retiming will treat module ports like register endpoints/startpoints
+    and the objective isn't informed by SDC, even the clock period is ignored.
   stages:
     - synth
 LATCH_MAP_FILE: