Project

General

Profile

Command Line Options » History » Version 25

Igor Melnichenko, 06/17/2015 03:46 PM

1 1 Sergey Smolov
h1. Command Line Options
2
3 2 Sergey Smolov
{{toc}}
4
5 23 Sergey Smolov
The tool can be run by using either scripts (@retrascope.sh@ for Unix-like OS, @retrascope.bat@ for Window-like OS) or "HDL Retrascope IDE":http://forge.ispras.ru/projects/retrascope-ide plugin for "Eclipse":http://eclipse.org.
6 1 Sergey Smolov
7 23 Sergey Smolov
In this document the command line interface for "HDL Retrascope":http://forge.ispras.ru/projects/retrascope is described.
8
9
By default, the tool is run with "--help" option. Here is an output of the tool that is run with "--help" option:
10 1 Sergey Smolov
11
<pre>
12
usage: [options] files
13 19 Igor Melnichenko
 --engine <arg>     Set a subset of engines
14
 --help             Show this message
15
 --log <arg>        Set a log file
16
 --log-level <arg>  Set a log level
17
 --target <arg>     Set a target entity
18 1 Sergey Smolov
</pre>
19
20
This output shows four main categories of "HDL Retrascope":http://forge.ispras.ru/projects/retrascope command line options: source files, engines, logging mode and targets.
21
Options can be put into command line in an arbitrary order. 
22
23 16 Sergey Smolov
Options can have multi-values i.e. sequences of values, separated by system-dependent symbols. For example, for running the tool on multiple Verilog files (@file1.v@, @file2.v@, @file3.v@) on *nix OS, do the following:
24
25
<pre>
26
--target cfg file1.v:file2.v:file3.v
27
</pre>
28
29
while on Windows:
30
31
<pre>
32
--target cfg file1.v;file2.v;file3.v
33
</pre>
34
35
36 1 Sergey Smolov
h2. Source files
37
38
This option keeps paths to files that contain source code of hardware modules.
39
40
The "HDL Retrascope":http://forge.ispras.ru/projects/retrascope can elaborate hardware descriptions written in synthesizable subsets of VHDL and Verilog. For current version of the tool it is possible to elaborate the source code when it satisfies some limitations. 
41
42
For VHDL - no loop-cycles, no other modules'' instantiations, no wait-constructions, no function calls, no ''Z'' or ''X'' values, code size is less than 1 KLOC.
43
For Verilog - similar to VHDL.
44
45
If these limitations are satisfied there is a high probability that "HDL Retrascope":http://forge.ispras.ru/projects/retrascope will be able to elaborate your design:-) Otherwise an exception will occur.
46
It is possible to run the "HDL Retrascope":http://forge.ispras.ru/projects/retrascope both on several VHDL and Verilog designs. In such case a composite inner representation based on Control FLow Graph model will be constructed.
47
48
To transform Verilog design into Control Flow Graph model you need to run "HDL Retrascope":http://forge.ispras.ru/projects/retrascope with the following parameters:
49
50
<pre>
51
--target cfg /path/to/file/file.v
52
</pre>
53
54
where "cfg" encodes Controlf Flow Graph model as target.
55
56
To transform VHDL design into Control Flow Graph model you need to run "HDL Retrascope":http://forge.ispras.ru/projects/retrascope with the following parameters:
57
58
<pre>
59
--target cfg --toplevel toplevel_name /path/to/file/file.vhd
60
</pre>
61
62 3 Sergey Smolov
where "toplevel" is an option that is obligatory for all VHDL designs that are being elaborated. The toplevel option value is a string name of the top-level module of the specified VHDL file. For example, to elaborate the following VHDL design (that is saved in the hello.vhd file):
63
64
<pre>
65
entity hello_world is
66
end;
67
 
68
architecture hello_world_arc of hello_world is
69
begin
70
  stimulus : process
71
  begin
72 4 Sergey Smolov
    assert false report "Hello World"
73 3 Sergey Smolov
    severity note;
74
  end process stimulus;
75
end hello_world_arc;
76
</pre>
77
78
we need to run "HDL Retrascope":http://forge.ispras.ru/projects/retrascope with the following parameters:
79
80
<pre>
81
--target cfg --toplevel hello_world /path/to/file/hello.vhd
82
</pre>
83 2 Sergey Smolov
84
h2. Targets
85
86 5 Sergey Smolov
From the tool point of view, the "HDL Retrascope":http://forge.ispras.ru/projects/retrascope operates with entities. One kind of these entities called "source files" was described in the previous section and for it''s elaboration the default tool components (called HDL parsers) are used.
87
88
Other entities may be treated as equivalent transformations of source code, or as data that can be extracted from source code (for example, like knowledge about module interfaces) or constructed (like module-level tests). Every entity which representation is included into "HDL Retrascope":http://forge.ispras.ru/projects/retrascope is stronlge connected with the tool component called "engine".
89
90 7 Sergey Smolov
To select the entity the user wants to get as result, the "target" option is needed to be initialized. For example, to get the EFSM (Extended Finite State Machine) that is stored into "GraphML":http://graphml.graphdrawing.org graphical format, the "HDL Retrascope":http://forge.ispras.ru/projects/retrascope should be run with the following options (for Verilog design called example.v):
91 5 Sergey Smolov
92
<pre>
93
--target efsm-graphml example.v
94
</pre>
95
96 8 Sergey Smolov
Here is the list of all target options of "HDL Retrascope":http://forge.ispras.ru/projects/retrascope:
97 6 Sergey Smolov
|*Name*|*Description*|
98
|cfg|Control flow graph model|
99 8 Sergey Smolov
|cfg-graphml|Control flow graph model that is saved in the "GraphML":http://graphml.graphdrawing.org file|
100 6 Sergey Smolov
|cfginterface|Interface (input and output signals) of control flow graph model|
101
|cgaa|Clocked guarded atomic actions model|
102 8 Sergey Smolov
|cgaa-graphml|Clocked guarded atomic actions model that is saved in the "GraphML":http://graphml.graphdrawing.org file|
103 6 Sergey Smolov
|efsm|Extended finite state machine model|
104 8 Sergey Smolov
|efsm-graphml|Extended finite state machine model that is saved in the "GraphML":http://graphml.graphdrawing.org file|
105 25 Igor Melnichenko
|vhdl-testbench|VHDL testbench|
106 1 Sergey Smolov
107
h2. Engines
108
109 8 Sergey Smolov
As it is described above, the "HDL Retrascope":http://forge.ispras.ru/projects/retrascope consists of components called "engines" for source files & models elaboration. The "HDL Retrascope":http://forge.ispras.ru/projects/retrascope tool takes the target and constructs a sequence of engines called "toolchain" that reaches the specified target as a result. If the specified target is unreachable, the tool returns an error message.
110
When the specified target can be reached by several toolchains, the user can select the desired one by selecting engines with special option called "engine".
111
Here is the list of all engines of "HDL Retrascope":http://forge.ispras.ru/projects/retrascope:
112
|*Name*|*Description*|
113
|verilog-parser|Parser of hardware modules descriptions written in Verilog|
114
|vhdl-parser|Parser of hardware modules descriptions written in VHDL|
115
|cfg-graphml-printer|Printer of control flow graph model into "GraphML":http://graphml.graphdrawing.org format|
116
|cfg-cgaa-transformer|Transformer of control flow graph model into clocked guarded actions model|
117
|cfg-cfginterface-extractor|Extractor of interface signals of control flow graph model|
118
|cgaa-graphml-printer|Printer of clocked guarded atomic actions model into "GraphML":http://graphml.graphdrawing.org format|
119
|cgaa-efsm-transformer|Transformer of control flow graph model into extended finite state machine model|
120
|efsm-graphml-printer|Printer of extended finite state machine model into "GraphML":http://graphml.graphdrawing.org format|
121
|efsm-fate-test-generator|The "FATE":http://link.springer.com/article/10.1007%2Fs10836-011-5209-8 test generator from extended finite state machine model|
122 1 Sergey Smolov
|efsm-test-generator| Generator of tests from extended finite state machine model|
123
|test-xml-printer|Printer of tests into XML format|
124
|xml-test-parser|Parser of XML format files keeping the tests|
125 25 Igor Melnichenko
|test-vhdl-testbench-printer|Creates a VHDL testbenches on the basis of an HDL source code and generated tests|
126 8 Sergey Smolov
127 14 Sergey Smolov
Some options are common for all the tool engines. Here they are:
128
|*Option name*|*Description*|*Acceptable value*|
129
|printer-style|Set a printer style|VERILOG/VHDL|
130 11 Sergey Smolov
131 14 Sergey Smolov
Some engines have individual command line options. Here is the list of all engine-specific options:
132
133 15 Sergey Smolov
|*Engine name*|*Option*|*Description*|*Acceptable value*|*Default value*|
134
|verilog-parser|include-path|Path to find included files|Any existing file system path|empty|
135
|vhdl-parser|toplevel|Toplevel VHDL modules names|Name of toplevel module for the processed VHDL module(s)|empty|
136
|cfg-graphml-printer|cfg-graphml|Output GraphML file name|Any string name for file that is acceptable by OS|cfg-model.graphml|
137 20 Sergey Smolov
|cgaa-graphml-printer|cfg-graphml|Output GraphML file name|Any string name for file that is acceptable by OS|cgaa-model.graphml|
138 15 Sergey Smolov
|efsm-graphml-printer|efsm-graphml|Output GraphML file name|Any string name for file that is acceptable by OS|efsm-model.graphml|
139 18 Igor Melnichenko
|efsm-fate-test-generator|sequence-length|Amount of vectors in one randomly generated sequence|Any integer (including zero)|a total amount of states|
140
|efsm-fate-test-generator|sequences-number|Amount of sequences in a randomly generated fragment of a test|Any integer (including zero)|A ratio of a total amount of transitions to a total amount of states (rounded to an integer)|
141 21 Igor Melnichenko
|efsm-fate-test-generator|loop-limit|Loop iteration limit|Any integer which is greater than zero|1|
142 1 Sergey Smolov
|efsm-test-generator|loop-limit|Loop iteration limit|Any integer which is greater than zero|1|
143
|test-xml-printer|file-name|Output XML file name|Any string name for file that is acceptable by OS|test.xml|
144 25 Igor Melnichenko
|test-vhdl-testbench-printer|testbench-directory|A directory where testbenches are saved|Either a relative or an absolute path to a directory. The %%MODULE_NAME%% placeholder is replaced by a processed design''s name|testbenches/%MODULE_NAME%|
145 15 Sergey Smolov
146 2 Sergey Smolov
h2. Logging
147
148 19 Igor Melnichenko
By default, "HDL Retrascope":http://forge.ispras.ru/projects/retrascope prints it''s output to the standard error stream. It is also possible to redirect the tool output to the specified file by using <code>--log</code> option.
149
The default logging level is <code>INFO</code>. It is possible to change it by means of the <code>--log-level</code> option. The acceptable values are <code>ERROR</code>, <code>WARNING</code>, <code>INFO</code>, <code>DEBUG</code>.
150 24 Sergey Smolov
151
h2. SMT solver debug mode
152
153
By default, "Fortress":http://http://forge.ispras.ru/projects/solver-api do not store the *.smt2 files through which it communicates with SMT solver. It can be enabled by setting <code>--solver-debug</code> option.