Retrascope

h1. Command Line Options

{{toc}}

One way to use the "HDL Retrascope":http://forge.ispras.ru/projects/retrascope is it''s command line options. Here is an output of the tool that it run with "--help" option:

<pre>

usage: [options] files

 -e,--engine <arg>   Set a subset of engines

 -h,--help           Show this message

 -l,--log <arg>      Set a log file

 -t,--target <arg>   Set a target entity

</pre>

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.

Options can be put into command line in an arbitrary order. 

h2. Source files

This option keeps paths to files that contain source code of hardware modules.

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. 

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.

For Verilog - similar to VHDL.

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.

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.

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:

<pre>

--target cfg /path/to/file/file.v

</pre>

where "cfg" encodes Controlf Flow Graph model as target.

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:

<pre>

--target cfg --toplevel toplevel_name /path/to/file/file.vhd

</pre>

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):

<pre>

entity hello_world is

end;

architecture hello_world_arc of hello_world is

begin

  stimulus : process

  begin

    assert false report "Hello World"

    severity note;

  end process stimulus;

end hello_world_arc;

</pre>

we need to run "HDL Retrascope":http://forge.ispras.ru/projects/retrascope with the following parameters:

<pre>

--target cfg --toplevel hello_world /path/to/file/hello.vhd

</pre>

h2. Targets

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.

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".

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 graphical format (see http://graphml.graphdrawing.org/), the "HDL Retrascope":http://forge.ispras.ru/projects/retrascope should be run with the following options (for Verilog design called example.v):

<pre>

--target efsm-graphml example.v

</pre>

Here is a list of all target options of "HDL Retrascope":http://forge.ispras.ru/projects/retrascope:

|*Name*|*Description*|

|cfg|Control flow graph model|

|cfg-graphml|Control flow graph model that is saved in the GraphML file|

|cfginterface|Interface (input and output signals) of control flow graph model|

|cgaa|Clocked guarded atomic actions model|

|cgaa-graphml|Clocked guarded atomic actions model that is saved in the GraphML file|

|efsm|Extended finite state machine model|

|efsm-graphml|Extended finite state machine model that is saved in the GraphML file|

|efsm-conflicts|Collection of read & write conflicts that are extracted from extended finite state machine model|

h2. Engines

h2. Logging