Skip to content

Commit 5434a5e

Browse files
oharboeclaude
andcommitted
SYNTH_VERILOG_SURGERY: surgery at home, a script edits copies of the sources
Surgery at home: SYNTH_VERILOG_SURGERY names a script that copies VERILOG_FILES and edits the copies before synthesis reads them. A hack, documented as one: nothing checks what it changed. Good for simple RTL, especially generated RTL (firtool, sv2v), whose text is regular enough to edit reliably. Unsuitable for idiomatic SystemVerilog code bases with include files, macros, packages, `bind` and other advanced language features, where an edit to the text cannot see what the code means. It runs where the RTL is read (synth_verilog_files in util.tcl, called by read_design_sources and by the SYNTH_USE_SYN frontend), with SYNTH_VERILOG_SURGERY_ARGS, then `--out-dir $(OBJECTS_DIR)/surgery --` and the VERILOG_FILES (by PYTHON_EXE when it ends in .py). It writes one copy per source under the same file name, and synthesis reads the copies. They are kept for inspection but are no make target and no build output: the Makefile and variables.mk are unchanged. A failing script, or a copy it did not write, stops synthesis. Why: the RTL keeps changing (a regenerated Chisel core, a bumped upstream), so a fix is an operation redone on every version rather than an edited copy that goes stale. In make it adds a step before synthesis without editing the Makefile, and a script may be reusable across designs. Its first use is making seams: logic with no module of its own moved into one, so a generated netlist can replace that module, and test inputs tied off. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Øyvind Harboe <oyvind.harboe@zylin.com>
1 parent 9b26ff8 commit 5434a5e

6 files changed

Lines changed: 90 additions & 5 deletions

File tree

‎docs/user/FlowVariables.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -313,6 +313,8 @@ configuration file.
313313
| <a name="SYNTH_SKIP_KEEP"></a>SYNTH_SKIP_KEEP| Only meaningful together with SYNTH_CHECKPOINT. When set, signals that the supplied checkpoint is still canonical RTLIL (coarse synth and `keep_hierarchy` have not been run yet), so synth.tcl runs the full coarse+fine synthesis flattened. When unset and SYNTH_CHECKPOINT is used, synth.tcl assumes the checkpoint already has coarse synth + `keep_hierarchy` done and resumes from `coarse:fine`.| 0|
314314
| <a name="SYNTH_SLANG_ARGS"></a>SYNTH_SLANG_ARGS| Additional arguments passed to the slang frontend during synthesis.| |
315315
| <a name="SYNTH_USE_SYN"></a>SYNTH_USE_SYN| If set to 1, run synthesis using the "syn" tool built into OpenROAD (the synth_syn.tcl flow) instead of the default Yosys-based flow. Defaults to 0 (Yosys flow).| 0|
316+
| <a name="SYNTH_VERILOG_SURGERY"></a>SYNTH_VERILOG_SURGERY| Surgery at home: a script that copies VERILOG_FILES and edits the copies before synthesis reads them. A hack; you asked for it, you deserve the results. Good for simple RTL, especially generated RTL (firtool, sv2v), whose text is regular enough to edit reliably. Unsuitable for idiomatic SystemVerilog code bases with include files, macros, packages, `bind` and other advanced language features, where an edit to the text cannot see what the code means. As the RTL is read (canonicalization, memory extraction, and the SYNTH_USE_SYN frontend), it runs with SYNTH_VERILOG_SURGERY_ARGS, then `--out-dir $(OBJECTS_DIR)/surgery --` and the VERILOG_FILES (by PYTHON_EXE when it ends in .py), and writes one copy per source under the same file name; synthesis reads the copies. They are kept for inspection but are no make target or build output. Input file names must be unique. Nothing checks what the script changed: write it to fail loudly when it cannot recognise its input. Its use so far is making seams: logic with no module of its own (a register file, say) moved into one so a generated netlist can replace that module, and test inputs tied off. Why: the RTL keeps changing (a regenerated Chisel core, a bumped upstream), so a fix is made as an operation that is redone on every version rather than as an edited copy that goes stale. In a build system such as Bazel, a step of one's own before synthesis is easy and this matters less; in make it is a way to add a step without hacking the Makefile, and a surgery script may turn out to be reusable across designs.| |
317+
| <a name="SYNTH_VERILOG_SURGERY_ARGS"></a>SYNTH_VERILOG_SURGERY_ARGS| Arguments to SYNTH_VERILOG_SURGERY, before the ones the flow adds.| |
316318
| <a name="SYNTH_WRAPPED_ADDERS"></a>SYNTH_WRAPPED_ADDERS| Specify the adder modules that can be used for synthesis, separated by commas. The default adder module is determined by the first element of this variable.| |
317319
| <a name="SYNTH_WRAPPED_MULTIPLIERS"></a>SYNTH_WRAPPED_MULTIPLIERS| Specify the multiplier modules that can be used for synthesis, separated by commas. The default multiplier module is determined by the first element of this variable.| |
318320
| <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.| 0|
@@ -379,6 +381,8 @@ configuration file.
379381
- [SYNTH_SKIP_KEEP](#SYNTH_SKIP_KEEP)
380382
- [SYNTH_SLANG_ARGS](#SYNTH_SLANG_ARGS)
381383
- [SYNTH_USE_SYN](#SYNTH_USE_SYN)
384+
- [SYNTH_VERILOG_SURGERY](#SYNTH_VERILOG_SURGERY)
385+
- [SYNTH_VERILOG_SURGERY_ARGS](#SYNTH_VERILOG_SURGERY_ARGS)
382386
- [SYNTH_WRAPPED_ADDERS](#SYNTH_WRAPPED_ADDERS)
383387
- [SYNTH_WRAPPED_MULTIPLIERS](#SYNTH_WRAPPED_MULTIPLIERS)
384388
- [TIEHI_CELL_AND_PORT](#TIEHI_CELL_AND_PORT)

‎flow/scripts/synth_preamble.tcl‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,7 @@ proc read_design_sources { } {
8282
{*}$vIdirsArgs {*}[env_var_or_empty VERILOG_DEFINES]]
8383

8484
# slang requires all files at once
85-
lappend slang_args {*}$::env(VERILOG_FILES)
85+
lappend slang_args {*}[synth_verilog_files]
8686

8787
# Add clock gate cell definition, if available
8888
if { [env_var_exists_and_non_empty CLKGATE_MAP_FILE] } {
@@ -133,7 +133,7 @@ proc read_design_sources { } {
133133
if { [env_var_exists_and_non_empty VERILOG_DEFINES] } {
134134
verific -vlog-define {*}$::env(VERILOG_DEFINES)
135135
}
136-
verific -sv2012 {*}$::env(VERILOG_FILES)
136+
verific -sv2012 {*}[synth_verilog_files]
137137
verific -import -no-split-complex-ports $::env(DESIGN_NAME)
138138

139139
dict for {key value} [env_var_or_empty VERILOG_TOP_PARAMS] {
@@ -152,7 +152,7 @@ proc read_design_sources { } {
152152
if { [env_var_exists_and_non_empty VERILOG_DEFINES] } {
153153
verilog_defaults -add {*}$::env(VERILOG_DEFINES)
154154
}
155-
foreach file $::env(VERILOG_FILES) {
155+
foreach file [synth_verilog_files] {
156156
read_verilog -defer -sv {*}$vIdirsArgs $file
157157
}
158158
# Read platform specific mapfile for OPENROAD_CLKGATE cells

‎flow/scripts/synth_syn.tcl‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,8 @@ set elaborate_args [list \
3030
-D SYNTHESIS --compat=vcs --ignore-assertions --no-implicit-memories --top $::env(DESIGN_NAME) \
3131
{*}$vIdirsArgs {*}[env_var_or_empty VERILOG_DEFINES]]
3232

33-
lappend elaborate_args {*}$::env(VERILOG_FILES)
33+
set verilog_files [synth_verilog_files]
34+
lappend elaborate_args {*}$verilog_files
3435

3536
# Apply top-level parameters
3637
dict for {key value} [env_var_or_empty VERILOG_TOP_PARAMS] {
@@ -50,7 +51,7 @@ lappend elaborate_args {*}$::env(SYNTH_SLANG_ARGS)
5051

5152
# If the sources are solely .v files, enable Verilog compatibility
5253
set has_non_v_files false
53-
foreach fn $::env(VERILOG_FILES) {
54+
foreach fn $verilog_files {
5455
if { [file extension [string trim $fn]] != ".v" } {
5556
set has_non_v_files true
5657
}

‎flow/scripts/util.tcl‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -336,3 +336,38 @@ proc source_step_tcl { hook_type step_name } {
336336
set env_var "${hook_type}_${step_name}_TCL"
337337
source_env_var_if_exists $env_var
338338
}
339+
340+
# The Verilog files synthesis reads: VERILOG_FILES or, with
341+
# SYNTH_VERILOG_SURGERY (a hack), the copies its script writes. The script
342+
# runs here, as the RTL is read, into $(OBJECTS_DIR)/surgery: one copy per
343+
# source under the same file name, kept for inspection. They are no make
344+
# target and no build output.
345+
proc synth_verilog_files { } {
346+
if { ![env_var_exists_and_non_empty SYNTH_VERILOG_SURGERY] } {
347+
return $::env(VERILOG_FILES)
348+
}
349+
set names [lmap f $::env(VERILOG_FILES) { file tail $f }]
350+
if { [llength [lsort -unique $names]] != [llength $names] } {
351+
error "SYNTH_VERILOG_SURGERY: VERILOG_FILES has two files of one name;\
352+
the copies are named after the originals"
353+
}
354+
set dir [file join $::env(OBJECTS_DIR) surgery]
355+
file delete -force $dir
356+
file mkdir $dir
357+
set cmd {}
358+
if { [file extension [lindex $::env(SYNTH_VERILOG_SURGERY) 0]] eq ".py" } {
359+
lappend cmd $::env(PYTHON_EXE)
360+
}
361+
lappend cmd {*}$::env(SYNTH_VERILOG_SURGERY) \
362+
{*}[env_var_or_empty SYNTH_VERILOG_SURGERY_ARGS] \
363+
--out-dir $dir -- {*}$::env(VERILOG_FILES)
364+
puts "SYNTH_VERILOG_SURGERY: [join $cmd]"
365+
exec {*}$cmd >@ stdout 2>@ stderr
366+
set copies [lmap name $names { file join $dir $name }]
367+
foreach copy $copies {
368+
if { ![file exists $copy] } {
369+
error "SYNTH_VERILOG_SURGERY wrote no $copy"
370+
}
371+
}
372+
return $copies
373+
}

‎flow/scripts/variables.json‎

Lines changed: 12 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎flow/scripts/variables.yaml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -211,6 +211,39 @@ ADDITIONAL_MEMORIES:
211211
docs/user/AutoMemories.md.
212212
stages:
213213
- synth
214+
SYNTH_VERILOG_SURGERY:
215+
description: >
216+
Surgery at home: a script that copies VERILOG_FILES and edits the
217+
copies before synthesis reads them. A hack; you asked for it, you
218+
deserve the results. Good for simple RTL, especially generated RTL
219+
(firtool, sv2v), whose text is regular enough to edit reliably.
220+
Unsuitable for idiomatic SystemVerilog code bases with include files,
221+
macros, packages, `bind` and other advanced language features, where
222+
an edit to the text cannot see what the code means. As the RTL is
223+
read (canonicalization, memory extraction, and the SYNTH_USE_SYN
224+
frontend), it runs with SYNTH_VERILOG_SURGERY_ARGS, then `--out-dir
225+
$(OBJECTS_DIR)/surgery --` and the VERILOG_FILES (by PYTHON_EXE when
226+
it ends in .py), and writes one copy per source under the same file
227+
name; synthesis reads the copies. They are kept for inspection but are
228+
no make target or build output. Input file names must be unique.
229+
Nothing checks what the script changed: write it to fail loudly when
230+
it cannot recognise its input. Its use so far is making seams: logic
231+
with no module of its own (a register file, say) moved into one so a
232+
generated netlist can replace that module, and test inputs tied off.
233+
Why: the RTL keeps changing (a regenerated Chisel core, a bumped
234+
upstream), so a fix is made as an operation that is redone on every
235+
version rather than as an edited copy that goes stale. In a build
236+
system such as Bazel, a step of one's own before synthesis is easy and
237+
this matters less; in make it is a way to add a step without hacking
238+
the Makefile, and a surgery script may turn out to be reusable across
239+
designs.
240+
stages:
241+
- synth
242+
SYNTH_VERILOG_SURGERY_ARGS:
243+
description: >
244+
Arguments to SYNTH_VERILOG_SURGERY, before the ones the flow adds.
245+
stages:
246+
- synth
214247
SYNTH_MEMORY_MAX_BITS:
215248
description: >
216249
Maximum number of bits for memory synthesis.

0 commit comments

Comments
 (0)