XRUN Fast Recompilation Flow
Product Version 18.06
June 2018
Copyright Statement
© 2018 Cadence Design Systems, Inc. All rights reserved worldwide. Cadence and the Cadence logo are
registered trademarks of Cadence Design Systems, Inc. All others are the property of their respective
holders.
Learn more at Cadence Support Portal - https://support.cadence.com
© 2018 Cadence Design Systems, Inc. All rights reserved worldwide. Page 2
XRUN Fast Recompilation Flow
Contents
Purpose ....................................................................................................................... 4
Audience...................................................................................................................... 4
Terms .......................................................................................................................... 4
Overview...................................................................................................................... 5
Workdir ..................................................................................................................... 6
Pakfile ...................................................................................................................... 6
Library ...................................................................................................................... 6
Worklib ..................................................................................................................... 6
Requirements for using the Fast Recompilation Flow.................................................. 7
XRUN Default Recompilation Flow .............................................................................. 8
Issues....................................................................................................................... 9
Example1 : Issues in Default Recompilation Flow.................................................... 9
XRUN Fast Recompilation Flow ................................................................................ 10
Example 2: Fast Recompilation Flow ..................................................................... 10
Example 3: Single Command Fast Recompilation with Makelib ............................ 11
Example 4: MSIE with Fast Recompilation ............................................................ 12
Check only XRUN commands ................................................................................... 13
Example 5: ............................................................................................................. 13
Support ...................................................................................................................... 14
Feedback ................................................................................................................... 14
Appendix:...................................................................................................................... i
Source Files for Examples 1 and 2 ........................................................................... i
Source Files for Example 3 ....................................................................................... ii
Source Files for Example 4 ....................................................................................... ii
Learn more at Cadence Support Portal - https://support.cadence.com
© 2018 Cadence Design Systems, Inc. All rights reserved worldwide. Page 3
XRUN Fast Recompilation Flow
Purpose
This Application Note describes the XRUN fast recompilation flow, and shows how to
effectively use the flow with a few representative examples. It also lists the Xcelium
tools that are not currently supported in the flow. Throughout this document, the term
recompilation is used to refer to the recompilation of source files, the re-elaboration of
the snapshot, or both as applicable.
Audience
This document is intended for design and verification (D&V) engineers who intend to
avoid unnecessary recompilation and who want to minimize the dependency check time
during a rerun of the XRUN command.
Terms
VST1 Verilog Syntax Tree
AST Abstract Syntax Tree
1 In the rest of this document we’ll use the term VST to refer to both VST and AST
Learn more at Cadence Support Portal - https://support.cadence.com
© 2018 Cadence Design Systems, Inc. All rights reserved worldwide. Page 4
XRUN Fast Recompilation Flow
Overview
Figure 1 shows an example XRUN design and verification flow.
Figure 1 An example XRUN Design and Verification Flow
Learn more at Cadence Support Portal - https://support.cadence.com
© 2018 Cadence Design Systems, Inc. All rights reserved worldwide. Page 5
XRUN Fast Recompilation Flow
Workdir
The path to XRUN’s work directory (workdir) is as follows:
<xmlibdirpath>/<xmlibdirname>/<rundir>
The default workdir is:
<pwd>/xcelium.d/run.d
XRUN keeps many generated files under the workdir. These files are meant for XRUN
internal use only, such as dependency checks and core argument files required for
invoking other Xcelium tools.
Pakfile
Xcelium tools save compiled and elaborated data into a file with the .pak extension
under the work library.
Library
A library can be specified with a logical name and has an associated physical path. If
unspecified, XRUN infers the physical path of the library from its logical name as
<xmlibdirpath>/<xmlibdirname>/<logical_name>.
There are multiple ways to explicitly specify the mapping between the logical name and
physical path of a library, for instance:
• -reflib <libpath[:logical]>
• An entry in cds.lib
In general, a library contains the pakfile (compiled VSTs) that can be used in
elaborating a design snapshot (typically used and shared by multiple designs).
Worklib
The worklib is the default output library. The default worklib name is worklib. There
are multiple ways to explicitly specify the worklib, for instance:
• -work <worklib_name>
• The variable WORK in the hdl.var file
Learn more at Cadence Support Portal - https://support.cadence.com
© 2018 Cadence Design Systems, Inc. All rights reserved worldwide. Page 6
XRUN Fast Recompilation Flow
Requirements for using the Fast Recompilation Flow
The fast recompilation system works by maintaining the dependency list for a single
xrun command in the workdir. Only one dependency list can be maintained per
workdir. If multiple xrun commands are specified, all which affect a single workdir, the
generated dependency list reflects only the most recent command.
While xrun can print out the accumulated command history for a workdir, it can only
compare the current xrun command with the previous xrun command for a single
workdir. In contrast, worklibs are cumulative.
➢ Ensure a 1:1:1 relationship between XRUN commands, workdir and worklib.
Separating the workdir ensures that the dependency files don’t get
overwritten.
Separating the worklib results in a finer control for re-elaboration decisions
(for XRUN commands that refer to these worklibs).
Use one or both of the following options:
-xmlibdirname <dir>
Specifies the directory name in which to store the created library
-xmlibdirpath <path>
Specifies the relative path where the libraries should be created
➢ Be aware that a “WORK” definition in a common hdl.var file causes it to become
the default workdir for all commands that use that hdl.var file.
➢ Compile your library with the xrun command2 rather than bare xmvlog/xmvlog
commands for better re-elaboration decisions (for XRUN commands that refer to the
library).
➢ Mixing xrun commands with the -fast_recompilation option and xrun
commands without in same workdir is not allowed. For instance, the following is not
a valid specification:
2 XRUN creates a proxy timestamp file for pakfile (pakfile file’s timestamp might change when it is
referred whereas proxy file’s timestamp doesn’t change when it is referred).
Learn more at Cadence Support Portal - https://support.cadence.com
© 2018 Cadence Design Systems, Inc. All rights reserved worldwide. Page 7
XRUN Fast Recompilation Flow
xrun foo.v -fast_recompilation
xrun foo.v
➢ Divide:
Build (compile) libraries (with possible sharing by multiple design snapshots)
Build (compile and elaborate) design snapshot that refers to libraries
If the source file of a library (that is being used in building the snapshot)
changes but the library has not been rebuilt, decide carefully if you really want
to rebuild the library and re-elaborate the snapshot.
➢ Fast recompilation works with Multi-Snapshot Incremental Elaboration (MSIE).
➢ Fast recompilation is not supported with –jg, -jc, -hw or –mce options.
XRUN Default Recompilation Flow
XRUN invokes several Xcelium tools with applicable arguments and source files.
XRUN uses the following mechanism for dependency checks and recompilation3
decisions:
1. For each Xcelium tool that XRUN invokes it keeps a list of hard arguments in an
internal file under the workdir. Upon rerun, if XRUN finds that any arguments
differ from the contents of this file, then the corresponding Xcelium tool is re-
invoked.
2. The pakfile header contains a list of source files (direct & included) and their
timestamps. Source files of the referenced library design units get inherited. Note
that source files include HDL source as well as other files consumed during the
process (such as, xprop input files and so on).
Upon rerun, XRUN compares the saved timestamps of the source files with their
current disk timestamp. If any source file is found to be out of date, then XRUN
recompiles and re-elaborates everything.
3The term “recompilation” here is used to refer to recompilation of source files or re-elaboration of
snapshot or both as applicable.
Learn more at Cadence Support Portal - https://support.cadence.com
© 2018 Cadence Design Systems, Inc. All rights reserved worldwide. Page 8
XRUN Fast Recompilation Flow
Issues
The default dependency check process has the following issues:
1. Time stamp verification introduces a significant performance overhead, when
many source files are present.
2. A source file may have been compiled by a separate xrun command, causing an
unnecessary recompilation that does not even touch any change files.
3. Running successive xrun commands with different source files in the same
workdir overwrites the hard arguments dependency check files.
Example14 : Issues in Default Recompilation Flow
For the example flow shown in Figure 1, where design instantiates cell a1 from library
libA and b1 from library libB:
1. First run:
xrun -xmlibdirname xmlibA -compile -makelib libA a1.v
a2.v -endlib
xrun -xmlibdirname xmlibB -compile -makelib libB b1.v b2.v
-v93 -endlib
xrun des.v tb.v -v93 -reflib xmlibA/libA:libA -reflib
xmlibB/libB:libB
2. Modify a1.v timestamp:
touch a1.v
3. Rerun:
xrun des.v tb.v -v93 -reflib xmlibA/libA:libA -reflib
xmlibB/libB:libB
The rerun command recompiles des.v and tb.v, and re-elaborate the snapshot since
libA source file a1.v was modified, even though nothing was changed for the
command being rerun. The default dependency check does a full and slow dependency
check.
4 Source files for this example are listed in the appendix
Learn more at Cadence Support Portal - https://support.cadence.com
© 2018 Cadence Design Systems, Inc. All rights reserved worldwide. Page 9
XRUN Fast Recompilation Flow
XRUN Fast Recompilation Flow
XRUN fast recompilation is enabled by the following option:
-fast_recompilation Enable fast recompilation
XRUN fast recompilation flow works as follows to overcome the issues in the default
recompilation flow:
1. A dependency check file of source files and their timestamps, is generated.
Upon rerun XRUN (instead of the list of sources in pakfile header) compares the
saved timestamps of the source files in dependency check files (instead of the
list of sources in pakfile header) with their current disk timestamp. If any source
file is found out of date, then XRUN re-compiles and re-elaborates.
Unlike default recompilation flow, XRUN does not check the source files of the
libraries that were referenced.
2. XRUN creates a dependency check file that contains a list of pakfiles5 and
source files (files that elaboration directly depends upon, not compile sources)
referenced during elaboration along with their timestamps.
Upon rerun, XRUN compares the saved timestamps of the elaborator
dependencies to the references in the dependency check file. If any pakfile or
source file is found out of date, then XRUN re-invokes the elaborator.
Example 2: Fast Recompilation Flow
Run the steps listed in Example1 with the -fast_recompilation option added to
each of the steps. The rerun doesn’t do unnecessary recompilation and re-elaboration
when -fast_recompilation is specified.
5 Instead of using the actual pakfile timestamp a proxy file (pakvst.ts) timestamp is used that changes
only when pakfile VSTs change. Note that pakfile contents (other than VSTs) might change when it is
referred.
Learn more at Cadence Support Portal - https://support.cadence.com
© 2018 Cadence Design Systems, Inc. All rights reserved worldwide. Page 10
XRUN Fast Recompilation Flow
Example 36: Single Command Fast Recompilation with Makelib
Consider the following command sequence:
1. First run:
xrun tb.v -compile -uptodate_messages -makelib DUT
dut.v -endlib -fast_recompilation –timedetail –clean
...
2. Modify dut.v timestamp:
touch dut.v
3. Rerun:
xrun tb.v -compile -uptodate_messages -makelib DUT dut.v
-endlib -fast_recompilation -timedetail
xrun: 18.06-a001:(c) Copyright 1995-2018 Cadence Design
Systems
xrun: *N,FST_TS_CHECK: appnote_example_3/dut.v is out of
date.
Expected: Thu Jun 14 14:04:24 2018
Actual: Thu Jun 14 14:04:44 2018.
xrun: *N,FST_EXEC_RERUN: makelib DUT_0_0 will be rerun.
xrun: timedetail: xrun incremental elapsed wall time 0.8s
xrun: timedetail: xmvlog elapsed wall time 0.1s
xrun: *N,FST_TS_CHECK:
appnote_example_3/xcelium.d/DUT/pakvst.ts is out of date.
Expected: Thu Jun 14 14:04:29 2018
Actual: Thu Jun 14 14:04:53 2018.
xrun: *N,FST_EXEC_RERUN: xmelab will be rerun.
xrun: timedetail: xrun incremental elapsed wall time 0.0s
...
Note that rerun recompiles only the modified file dut.v (instead of recompiling everything
in the default flow).
6 Source files for this example are listed in the appendix
Learn more at Cadence Support Portal - https://support.cadence.com
© 2018 Cadence Design Systems, Inc. All rights reserved worldwide. Page 11
XRUN Fast Recompilation Flow
Example 47: MSIE with Fast Recompilation
1. First run:
cp inc1.sv inc.sv
xrun -makelib plib l.sv b.sv dut.sv tb.sv
-endlib -makeprim tb -endprim -top tb -top incr
inc.sv -uptodate_messages -fast_recompilation
...
2. Change inc.sv:
cp inc2.sv inc.sv
3. Rerun:
xrun -makelib plib l.sv b.sv dut.sv tb.sv -endlib -makeprim
tb -endprim -top tb -top incr inc.sv -uptodate_messages
-fast_recompilation
xrun: 18.06-a001:(c) Copyright 1995-2018 Cadence Design
Systems
xrun: *N,FST_TS_CHECK: appnote_example_4/inc.sv is out of
date.
Expected: Thu Jun 14 16:04:32 2018
Actual: Thu Jun 14 16:08:57 2018.
xrun: *N,FST_EXEC_RERUN: xmvlog will be rerun.
file: inc.sv
package worklib.incr:sv
errors: 0, warnings: 0
Loading primary snapshot worklib.tb:sv ....................
Done
...
Note that fast recompilation compiles only the changed file incr.sv which is a huge
saving over the default recompilation.
7 Source files for this example are listed in the appendix
Learn more at Cadence Support Portal - https://support.cadence.com
© 2018 Cadence Design Systems, Inc. All rights reserved worldwide. Page 12
XRUN Fast Recompilation Flow
Check only XRUN commands
The following check-only options work in both the default and fast recompilation flows,
and use the old/default dependency check mechanisms:
➢ You can check if a snapshot is up to date with respect to its elaboration
dependencies and compilation source files, without running a full XRUN command:
xrun -check_snap_dep
By default, this checks the snapshot defined by the SNAPSHOT variable in:
<xmlibdirpath>/<xmlibdirname>/hdl.var
➢ You may check if a library is up to date with respect to its sources:
xrun -check_vst_dep
By default, this checks the libraries defined in:
<xmlibdirpath>/<xmlibdirname>/cds.lib
Example 5:
Run the steps in Example1 and then run the following checks:
xrun -check_snap_dep
xrun -check_vst_dep
Learn more at Cadence Support Portal - https://support.cadence.com
© 2018 Cadence Design Systems, Inc. All rights reserved worldwide. Page 13
XRUN Fast Recompilation Flow
Support
Cadence Support Portal provides access to support resources, including an extensive
knowledge base, access to software updates for Cadence products, and the ability to
interact with Cadence Customer Support. Visit https://support.cadence.com.
Feedback
Email comments, questions, and suggestions to [email protected].
Learn more at Cadence Support Portal - https://support.cadence.com
© 2018 Cadence Design Systems, Inc. All rights reserved worldwide. Page 14
XRUN Fast Recompilation Flow
Appendix:
Source Files for Examples 1 and 2
a1.v
module a1();
initial $display("libA:a1");
endmodule
a2.v
module a2();
initial $display("libA:a2");
endmodule
b1.v
module b1();
initial $display("libB:b1");
endmodule
b2.v
module b2();
initial $display("libB:b2");
endmodule
des.v
module des();
a1 a1_inst();
b1 b1_inst();
initial $display("des modified");
endmodule
tb.v
Learn more at Cadence Support Portal - https://support.cadence.com
© 2018 Cadence Design Systems, Inc. All rights reserved worldwide. Page i
XRUN Fast Recompilation Flow
module tb();
des des_i();
endmodule // tb
Source Files for Example 3
dut.v
module dut();
initial $display("DUT");
endmodule
tb.v
module tb();
dut I1();
endmodule
Source Files for Example 4
l.sv
package lowpkg;
reg a;
endpackage
b.sv
package bigpkg;
import lowpkg::*;
endpackage
u.sv
package uppkg;
Learn more at Cadence Support Portal - https://support.cadence.com
© 2018 Cadence Design Systems, Inc. All rights reserved worldwide. Page ii
XRUN Fast Recompilation Flow
import bigpkg::*;
endpackage
dut.sv
module dut();
endmodule
tb.sv
module tb();
import bigpkg::*;
dut dut();
endmodule
inc1.sv
package incr;
import lowpkg::*;
int om;
endpackage
inc2.sv
package incr;
import lowpkg::*;
int om2;
endpackage
Learn more at Cadence Support Portal - https://support.cadence.com
© 2018 Cadence Design Systems, Inc. All rights reserved worldwide. Page iii
