Command Line Options¶

• Table of contents
• Command Line Options
  • Source files
  • Targets
  • Engines
  • Logging

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

usage: [options] files
 --engine <arg>   Set a subset of engines
 --help           Show this message
 --log <arg>      Set a log file
 --target <arg>   Set a target entity

This output shows four main categories of HDL Retrascope command line options: source files, engines, logging mode and targets.
Options can be put into command line in an arbitrary order.

Source files¶

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

The HDL 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 will be able to elaborate your design:-) Otherwise an exception will occur.
It is possible to run the HDL 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 with the following parameters:

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

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

To transform VHDL design into Control Flow Graph model you need to run HDL Retrascope with the following parameters:

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

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

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;

we need to run HDL Retrascope with the following parameters:

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

Targets¶

From the tool point of view, the HDL 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 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, the HDL Retrascope should be run with the following options (for Verilog design called example.v):

--target efsm-graphml example.v

Here is the list of all target options of HDL 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

Engines¶

As it is described above, the HDL Retrascope consists of components called "engines" for source files & models elaboration. The HDL 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.
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".
Here is the list of all engines of HDL Retrascope:

Name	Description
verilog-parser	Parser of hardware modules descriptions written in Verilog
vhdl-parser	Parser of hardware modules descriptions written in VHDL
cfg-graphml-printer	Printer of control flow graph model into GraphML format
cfg-cgaa-transformer	Transformer of control flow graph model into clocked guarded actions model
cfg-cfginterface-extractor	Extractor of interface signals of control flow graph model
cgaa-graphml-printer	Printer of clocked guarded atomic actions model into GraphML format
cgaa-efsm-transformer	Transformer of control flow graph model into extended finite state machine model
efsm-graphml-printer	Printer of extended finite state machine model into GraphML format
efsm-fate-test-generator	The FATE test generator from extended finite state machine model
efsm-test-generator	Generator of tests from extended finite state machine model
test-xml-printer	Printer of tests into XML format
xml-test-parser	Parser of XML format files keeping the tests

Some options are common for all the tool engines. Here they are:

Option name	Description	Acceptable value
printer-style	Set a printer style	VERILOG/VHDL

Some engines have individual command line options. Here is the list of all engine-specific options:

Engine name	Option	Description	Acceptable value
verilog-parser	include-path	Path to find included files	Any existing file system path
vhdl-parser	toplevel	Toplevel VHDL modules names	Name of toplevel module for the processed VHDL module(s)
cfg-graphml-printer	cfg-graphml	Output GraphML file name	Any string name for file that is acceptable by OS
cgaa-graphml-printer	cgaa-graphml	Output GraphML file name	Any string name for file that is acceptable by OS
efsm-graphml-printer	efsm-graphml	Output GraphML file name	Any string name for file that is acceptable by OS
efsm-fate-test-generator	sequence-length	Amount of vectors in one randomly generated sequence	??
efsm-fate-test-generator	sequences-number	Amount of sequences in a randomly generated fragment of a test	??
efsm-test-generator	loop-limit	Loop iteration limit	??
test-xml-printer	file-name	Output XML file name	Any string name for file that is acceptable by OS

Logging¶

By default, HDL Retrascope prints it''s output to the standard error stream. It is also possible to redirect the tool output to the specified by using --log option.