Adjust docs for retiming option

Use some of Øyvind's phrasing and add more text.

Signed-off-by: Martin Povišer <[email protected]>

Author: povik

docs/user/FlowVariables.md

@@ -239,7 +239,7 @@ configuration file.
 | <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_OPT_HIER"></a>SYNTH_OPT_HIER| Optimize constants across hierarchical boundaries.| |
-| <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. The main use case is to quickly identify if performance can be improved by manually retiming the input RTL. Retiming will treat module ports like register endpoints/startpoints. The objective function of retiming isn't informed by SDC, even the clock period is ignored. As such, retiming will optimize for best delay at potentially high register number cost. Automatic retiming can produce suboptimal results as its timing model is crude and it doesn't find the optimal distribution of registers on long pipelines. See OR discussion #8080.| |
 | <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,23 @@ 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.
+
+    The main use case is to quickly identify if performance can be improved by
+    manually retiming the input RTL.
+
+    Retiming will treat module ports like register endpoints/startpoints.
+    The objective function of retiming isn't informed by SDC, even the clock
+    period is ignored. As such, retiming will optimize for best delay
+    at potentially high register number cost. Automatic retiming can produce
+    suboptimal results as its timing model is crude and it doesn't find the
+    optimal distribution of registers on long pipelines. See OR discussion #8080.
   stages:
     - synth
 LATCH_MAP_FILE: