You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/user/FlowVariables.md
+47-13Lines changed: 47 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,48 @@
1
-
# Environment Variables for the OpenROAD Flow Scripts
1
+
# Variables for the OpenROAD Flow Scripts
2
2
3
-
4
-
Environment variables are used in the OpenROAD flow to define various
3
+
Variables are used in the OpenROAD flow to define various
5
4
platform, design and tool specific variables to allow finer control and
6
-
user overrides at various flow stages. These are defined in the
7
-
`config.mk` file located in the platform and design specific directories.
5
+
user overrides at various flow stages.
6
+
7
+
These are normally defined in the `config.mk` file located in the platform and design-specific directories, but can also be defined on the command line or via environment variables. For example:
This works provided that `config.mk` has defined it as a default value using the `export PLACE_DENSITY?=0.4` syntax.
13
+
14
+
The actual value used is determined by the priority rules set by `make`:
15
+
16
+
1.**Makefile Definitions**: Variables defined in the `Makefile` or included files are used when they are defined using the no-override `=` operator, `export PLACE_DENSITY=0.4` syntax. The priority within the included files is the `DESIGN_CONFIG` file, then `Makefile` definitions and finally platform(PDK) defined variables.
17
+
2.**Command Line**: Variables defined on the command line take the highest priority in overriding defaults.
18
+
3.**Environment Variables**: Variables exported in the shell environment are used if not overridden by the command line.
19
+
4.**Default Values**: Variables defined with the `?=` operator in the `Makefile` are used only if the variable is not already defined elsewhere.
20
+
21
+
## Effects of variables
22
+
23
+
The variables for ORFS are not fully independent and can interact in complex ways. Small changes to a combination of variables can have large consequences, such as on macro placement, which can lead to vastly different quality of results.
24
+
25
+
Due to the large number of variables, some of which are continuous and require long runtimes, other discrete, it is not feasible to perform an exhaustive end-to-end search for the best combination of variables.
26
+
27
+
Instead, the following approaches are used to determine reasonable values, up to a point of diminishing returns:
28
+
29
+
-**Experience**: Leveraging domain expertise to set initial values.
30
+
-**AI**: Using machine learning techniques to explore variable combinations.
31
+
-**Parameter Sweeps**: Testing a smaller subset of variables to identify optimal ranges.
32
+
33
+
These values are then set in configuration files and kept under source control alongside the RTL input.
34
+
35
+
## Types of variables
36
+
37
+
Variables values are set in ORFS scripts or `config.mk` files and are kept in source control together with configuration files and RTL.
38
+
39
+
It is an ongoing effort to move variables upwards in the categories below.
|**Trivial**| Automatically determined by tool with near-optimal results. | None (unless debugging) | Buffer sizing, default layers |**High** – can be hidden | Best if invisible; surfaced only in debug or verbose mode. |
44
+
|**Easy**| Requires input, but easy to tune using reports or visuals. | Moderate – copy/edit from reports |`PLACE_DENSITY`|**Medium–High**| Smooth response curves, intuitive tuning. |
45
+
|**Complex**| Small changes in values may result in large effects. | High – requires multiple runs/sweeps |`CTS_DISTANCE_BUF`, small changes can have large effects on skew and quality of results. Small changes to independent inputs, such as RTL, can invalidate earlier "good values". |**Low–Medium**| Needs scripted sweeps and statistical evaluation. |
8
46
9
47
## Platform
10
48
@@ -20,7 +58,7 @@ variable. For OpenROAD Flow Scripts we have the following public platforms:
20
58
-`nangate45`
21
59
-`asap7`
22
60
23
-
## Platform Specific Environment Variables
61
+
## Platform Specific Variables
24
62
25
63
26
64
The table below lists the complete set of variables used in each of the
@@ -108,8 +146,8 @@ configuration file.
108
146
| <aname="GUI_TIMING"></a>GUI_TIMING| Load timing information when opening GUI. For large designs, this can be quite time consuming. Useful to disable when investigating non-timing aspects like floorplan, placement, routing, etc.| 1||
109
147
| <a name="HOLD_SLACK_MARGIN"></a>HOLD_SLACK_MARGIN| Specifies a time margin for the slack when fixing hold violations. This option allows you to overfix or underfix (negative value, terminate retiming before 0 or positive slack). 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 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.| 0| |
110
148
| <aname="IO_CONSTRAINTS"></a>IO_CONSTRAINTS| File path to the IO constraints .tcl file.|||
111
-
| <aname="IO_PLACER_H"></a>IO_PLACER_H|The metal layer on which to place the I/O pins horizontally (top and bottom of the die).|||
112
-
| <aname="IO_PLACER_V"></a>IO_PLACER_V|The metal layer on which to place the I/O pins vertically (sides of the die).|||
149
+
| <aname="IO_PLACER_H"></a>IO_PLACER_H|A list of metal layers on which the I/O pins are placed horizontally (top and bottom of the die).|||
150
+
| <aname="IO_PLACER_V"></a>IO_PLACER_V|A list of metal layers on which the I/O pins are placed vertically (sides of the die).|||
113
151
| <aname="IR_DROP_LAYER"></a>IR_DROP_LAYER| Default metal layer to report IR drop.|||
114
152
| <aname="KLAYOUT_TECH_FILE"></a>KLAYOUT_TECH_FILE| A mapping from LEF/DEF to GDS using the KLayout tool.|||
115
153
| <aname="LATCH_MAP_FILE"></a>LATCH_MAP_FILE| List of latches treated as a black box by Yosys.|||
@@ -128,7 +166,7 @@ configuration file.
128
166
| <aname="MIN_BUF_CELL_AND_PORTS"></a>MIN_BUF_CELL_AND_PORTS| Used to insert a buffer cell to pass through wires. Used in synthesis.|||
129
167
| <aname="MIN_ROUTING_LAYER"></a>MIN_ROUTING_LAYER| The lowest metal layer name to be used in routing.|||
130
168
| <aname="PDN_TCL"></a>PDN_TCL| File path which has a set of power grid policies used by pdn to be applied to the design, such as layers to use, stripe width and spacing to generate the actual metal straps.|||
131
-
| <aname="PLACE_DENSITY"></a>PLACE_DENSITY| The desired placement density of cells. It reflects how spreadthe cells would be on the core area. 1.0 = closely dense. 0.0 = widely spread.|||
169
+
| <aname="PLACE_DENSITY"></a>PLACE_DENSITY| The desired average placement density of cells: 1.0 = dense, 0.0 = widely spread. The intended effort is also communicated by this parameter. Use a low value for faster builds and higher value for better quality of results. If a too low value is used, the placer will not be able to place all cells and a recommended minimum placement density can be found in the logs. A too high value can lead to excessive runtimes, even timeouts and subtle failures in the flow after placement, such as in CTS or global routing when timing repair fails. The default is platform specific.|||
132
170
| <aname="PLACE_DENSITY_LB_ADDON"></a>PLACE_DENSITY_LB_ADDON| Check the lower boundary of the PLACE_DENSITY and add PLACE_DENSITY_LB_ADDON if it exists.|||
133
171
| <aname="PLACE_PINS_ARGS"></a>PLACE_PINS_ARGS| Arguments to place_pins|||
134
172
| <aname="PLACE_SITE"></a>PLACE_SITE| Placement site for core cells defined in the technology LEF file.|||
@@ -143,8 +181,6 @@ configuration file.
143
181
| <aname="REMOVE_CELLS_FOR_EQY"></a>REMOVE_CELLS_FOR_EQY| String patterns directly passed to write_verilog -remove_cells <> for equivalence checks.|||
144
182
| <aname="REPAIR_PDN_VIA_LAYER"></a>REPAIR_PDN_VIA_LAYER| Remove power grid vias which generate DRC violations after detailed routing.|||
145
183
| <aname="REPORT_CLOCK_SKEW"></a>REPORT_CLOCK_SKEW| Report clock skew as part of reporting metrics, starting at CTS, before which there is no clock skew. This metric can be quite time-consuming, so it can be useful to disable.| 1||
146
-
| <aname="RESYNTH_AREA_RECOVER"></a>RESYNTH_AREA_RECOVER| Enable re-synthesis for area reclaim.| 0||
147
-
| <aname="RESYNTH_TIMING_RECOVER"></a>RESYNTH_TIMING_RECOVER| Enable re-synthesis for timing optimization.| 0||
148
184
| <a name="ROUTING_LAYER_ADJUSTMENT"></a>ROUTING_LAYER_ADJUSTMENT| Adjusts routing layer capacities to manage congestion and improve detailed routing. High values ease detailed routing but risk excessive detours and long global routing times, while low values reduce global routing failure but can complicate detailed routing. The global routing running time normally reduces dramatically (entirely design specific, but going from hours to minutes has been observed) when the value is low (such as 0.10). Sometimes, global routing will succeed with lower values and fail with higher values. Exploring results with different values can help shed light on the problem. Start with a too low value, such as 0.10, and bisect to value that works by doing multiple global routing runs. As a last resort, `make global_route_issue` and using the tools/OpenROAD/etc/deltaDebug.py can be useful to debug global routing errors. If there is something specific that is impossible to route, such as a clock line over a macro, global routing will terminate with DRC errors routes that could have been routed were it not for the specific impossible routes. deltaDebug.py should weed out the possible routes and leave a minimal failing case that pinpoints the problem.| 0.5| |
149
185
| <aname="RTLMP_AREA_WT"></a>RTLMP_AREA_WT| Weight for the area of the current floorplan.| 0.1||
150
186
| <aname="RTLMP_ARGS"></a>RTLMP_ARGS| Overrides all other RTL macro placer arguments.|||
0 commit comments