Project

General

Profile

Getting Started » History » Version 11

Sergey Smolov, 01/27/2020 05:47 PM

1 1 Sergey Smolov
h1. Getting Started
2
3
{{toc}}
4
5 3 Sergey Smolov
h2. Prerequisite
6 1 Sergey Smolov
7
Retrascope should be "installed":https://forge.ispras.ru/projects/retrascope/wiki/Installation_Guide.
8 3 Sergey Smolov
9
h2. Command Line Interface
10
11
As it is described in "Overview":https://forge.ispras.ru/projects/retrascope/wiki/Overview, Retrascope contains a number of data representations that are called *entities* and a number of active components that are called *engines*. When working with the tool through command line interface, _valuable_ engines and\or entities are to be specified. To describe the approach, let's look at the map of all engines and entities at Retrascope:
12
13 6 Sergey Smolov
*Figure 1* : Engines & entities dependency graph
14
!engines-entities.png(*Figure 1* : Engines & entities dependency graph)!
15 1 Sergey Smolov
16 6 Sergey Smolov
On the Fig. 1 engines are depicted as labeled edges, entities are depicted as labeled nodes. Entities that are represented by text files, are shown as grey rectangles. Entities, that are stored in memory, are shown as yellow circles. Edge and node labels store engine and entity _identifiers_ respectively. Edge directions mean input (source) and output (destination) entities for engines.
17 1 Sergey Smolov
18 6 Sergey Smolov
At simple case, it is enough for the tool running to pass the desired entity or engine identifier as command line parameter. However, as it can be seen from Fig. 1, some engines require two or more inputs. For such engines (like @smv-test-parser@, for example) _merge points_ that are depicted by white circle nodes are introduced. Having such merge points in Retrascope engines\entities dependency graph, means that it is not enough to specify only the destination engine or entity. Tool parameters should be selected with the aim to describe the concrete path at the dependency graph.
19
20 8 Sergey Smolov
For example, we would like to run the tool on VHDL module that is called @example.vhd@ with the aim to check properties that are extracted from it's internal EFSM model (@efsm-transition-property-extractor@) by a VHDL testbench. Here is the module code:
21 1 Sergey Smolov
<pre>
22 10 Sergey Smolov
entity example is
23
 port (input : in bit_vector(2 downto 1);
24
       output: out bit_vector(1 downto 0);
25
       clock: in bit);
26 8 Sergey Smolov
27 10 Sergey Smolov
end example;
28
29
architecture BEHAV of example is
30
31
 begin
32
   process(clock)
33
34
 begin
35
   if clock'event and clock='1' then
36
     if (input(2) = '1') then
37
       output <= "11";
38
     end if;
39
     if (input(1) = '0') then
40
       output <= "01";
41
     end if;
42
   end if;
43
 end process;
44
end BEHAV;
45 8 Sergey Smolov
</pre>
46 6 Sergey Smolov
47
On Windows, Retrascope should have at least the following arguments:
48 1 Sergey Smolov
<pre>
49 10 Sergey Smolov
> retrascope.bat example.vhd --module-name example --target vhdl-testbench --engine vhdl-parser;efsm-transition-property-extractor
50 1 Sergey Smolov
</pre>
51
On Linux-based OS:
52 8 Sergey Smolov
<pre>
53 10 Sergey Smolov
$ retrascope example.vhd --module-name example --target vhdl-testbench --engine vhdl-parser:efsm-transition-property-extractor
54 8 Sergey Smolov
</pre>
55
Next chapters of this guide describe main use cases of the Retrascope tool.
56
57
h2. Model visualization
58
59
Retrascope tool extracts the following categories of models from target HDL descriptions:
60
* Control Flow Graph (CFG)
61
* Guarded Actions Decision Diagram (GADD)
62 9 Sergey Smolov
* High-Level Decision Diagram (HLDD)
63
* Extended Finite State Machine (EFSM)
64 1 Sergey Smolov
65 9 Sergey Smolov
All the models tend to be equivalent to the target HDL module(s) and are stored in memory as Java objects. To get their graphical representation we use "GraphML":https://en.wikipedia.org/wiki/GraphML format - an XML-based format for graphs. To open GraphML files we'd recommend to use "yEd":https://www.yworks.com/products/yed editor. To run the tool for CFG model visualization, use the following parameters:
66
<pre>
67 10 Sergey Smolov
$ ./retrascope example.vhd --module-name example --engine cfg-graphml-printer --graphml example-cfg.graphml
68 9 Sergey Smolov
</pre>
69 11 Sergey Smolov
To convert the generated _example-cfg.graphml_ file into the PNG format, do the following:
70
# Run yEd editor
71
# From main menu select "File" -> "Open...", then select the _example-cfg.graphml_ file in your file system and press "Open"
72
# Select "Layout" -> "Hierarchical" then press "OK"
73
# Select "File" -> "Export..." and select PNG format
74
75
The result is on Figure 2.
76
77
78
79 9 Sergey Smolov
Parameters are similar for GADD model:
80 1 Sergey Smolov
<pre>
81 10 Sergey Smolov
$ ./retrascope example.vhd --module-name example --engine gadd-graphml-printer --graphml example-gadd.graphml
82 9 Sergey Smolov
</pre>
83
and for EFSM model:
84
<pre>
85 10 Sergey Smolov
$ ./retrascope example.vhd --module-name example --engine efsm-graphml-printer --graphml example-efsm.graphml
86 9 Sergey Smolov
</pre>
87
88
89 8 Sergey Smolov
90
To be continued...