f2dot

f2dot stands for ForSyDe-to-DOT graph. It plots any (currently) ForSyDe-SystemC generated XML intermediate representation into  DOT graphs, or any visual representation for them.

Installation

The tool has been developed in  Python and it is distributed as either a   distutils installer or as a pre-built binary file.

To install the tool, you can follow the instructions on any of the following sections.

Pre-built binary releases

A set of pre-built binary distributions for different OS can be found in the download page. They are self-sufficient, since they include both interpreter and dependencies.

To install a binary release, just unpack the file f2dot from the folder associated with your OS into a local directory, and run it from command line.

Building your own binary

If your OS is not specified among the pre-built distributions, or would like to build it on your own, the tool comes with a   distutils installer.

The source files can be acquired from:

As a prerequisite, a Python interpreter is needed (>=2.7) and the Graphviz tool chain (libgraphviz-dev).

As administrator

To install f2dot, you need to run the command as su:

python setup.py install

  distutils should take care of the dependencies and install them in their default (system) paths. For example, on a Linux machine having Python 2.7, the runner will be installed in /usr/local/bin/ and the packages in /usr/local/lib/python2.7/dist-packages/.

If   distutils links everything properly, the f2dot program can be run from the system path using

f2dot

As local user

To build f2dot you need to run the command

python setup.py bdist

which will create the build folder, which contains a libraries subfolder (lib.[...]) and a scripts subfolder (scripts-[...]). The runner binary is found in the scripts folder, and it can be run once the libraries path is added to the PYTHONPATH environment variable.

The command to run the program is

./[path/to/your/]f2dot

Using the source scripts

If you would like to use the source scripts directly, instead of building a binary distribution, the installer provides this option as well. In this case, the user needs to take care of all the dependencies herself.

As in the previous section, the source installer can be acquired from:

To be able to run these scripts, one needs to fulfil the following conditions:

  1. have a Python interpreter (>=2.7)
  2. install the  Graphviz development libraries. On a Debian distribution of Linux, one can install it with the command:
    sudo apt-get install libgraphviz-dev
    
  3. have installed the  pygraphviz Python API library. Using the pip package manager, one can install pygraphviz using the command:
    pip install pygraphviz
    
    or, using a Debian package manager, an alternative way would be:
    sudo apt-get install python-pygraphviz
    

The installation is done by running the following command from the destination directory:

python [path/to/]setup.py scripts

The program may be run as a Python script using the command

python [path/to/scripts/]f2dot.py

(Optional) Visualizer tool

To visualize the graphs as dot files, one needs to have a DOT file reader installed. One such reader is  XDot. Otherwise, the output can be specified to another format, like pdf or png.

Usage

The user has multiple possibilities to customize the output graph either through command-line argument or a config file.

The basic usage of the program is

f2dot <module>.xml

where <module> is the process which will appear as the top-level process network in the output graph. Notice that the ForSyDe intermediate representation regards all composite processes as process networks on their own, thus any valid ForSyDe-XML generated file can be a top module. Also, take note that the tool assumes that all the XML files representing the child processes are in the same folder, as they were generated by the Introspection.

If no config file was mentioned (with argument -c), the component looks inside the input folder for the default one. If it didn't find it, it generates a default config file there. The config files can be modified for custom output. The user is encouraged to read the documentation generated for each option.

For a list with all the command-line arguments, one needs to run the program followed by -h.

  • as standalone binary release:
    f2dot -h
    
  • as script file:
    python f2dot -h
    

Tutorial

In this tutorial, a few features of f2dot will be presented. All examples will work on the toySDF example presented in the Synchronous Dataflow Tutorial. As suggested in the tool's help document, the output is controlled by the options in the config file. Some command line arguments override these options, for user convenience.

Running the f2dot tool on toySDF's top.xml with the default options, outputs the following graph:

f2dot top.xml

f2dot output for toySDF model, plotted with default options

Altering the direction or detail level, we get the following graphs:

f2dot output for toySDF model, Top-Bottom orientation f2dot output for toySDF model, Top-Bottom orientation, 1 level of detail
f2dot top.xml --dir=TB f2dot top.xml --dir=TB --level=1

The config file has numerous other options for customizing the output. Since they are all documented, we shall only focus on the most important ones: the information tags. They define what information should appear as labels on the different elements of the output graph.

These tags are   XPath 1.0 queries wrapped inside a minimal custom grammar for defining label layout. This grammar is defined as:

LABEL = R LABEL = an INFO_TAG may/may not contain Row information
R = R R R = {D} (any number of) Rows consist of Data surrounded by curly brackets {}
D = D && D D = query Data on the same Row is separated by && and consists of XPath queries

Since an XPath query returns a list of informations, through this grammar f2dot takes care of merging and zipping data in a relevant manner for the user. For example, assuming that queryX returns a list dataX = [dataX[0], dataX[1], ...], the following INFO_TAG

{query1} {query2 && query3 && query4} 

will enable f2dot to arrange the lable as:

data1[0]
data1[1]
...
data2[0] data3[0] data4[0]
data2[1] data3[1] data4[1]
... ... ...

A good tutorial for XPath syntax may be found   here. Based on that, the following query

./process_constructor/argument[@name='_func']/../argument/@name | ./process_constructor[@name='delay']/@moc

can be translated to return all the values of the attribute name of the nodes tagged argument which are children of node process_constructor IF the node process_constructor has at least one child node argument having an attribute name with the value _func | ALSO, return all the values of the attribute moc of the nodes tagged process_constructor IF this node has least one attribute name with the value delay.

Putting this new knowledge in practice, we can play around with what information we want extracted from the ForSyDe-XML files and plotted as node labels in the output graph. For example, if we alter the f2dot.config file with the following INFO_TAGS

DIRECTION=TB
LEAF_INFO_TAGS={ ./@name } {./process_constructor/argument[@name='_func']/../argument/@name | ./process_constructor[@name='delay']/@moc && ./process_constructor/argument[@name='_func']/../argument/@value}
COMPOSITE_INFO_TAGS={./@name } {  name(./@component_name) && ./@component_name }
LEAF_PORT_INFO_TAGS= {./@name && ./@type }
COMPOSITE_PORT_INFO_TAGS={./@name }{ ./@direction }
SIGNAL_INFO_TAGS={./@moc }

we get the annotated graph:

f2dot output for toySDF model, annotated after changing the config options

Development

The API documentation can be generated using the doxyfile in the source root folder:

doxygen dox

All packages and their purposes are documented. A new parser will be written as a new package in the src folder, which imports everything from parsermethods (and utils, for convenience). The parser methods shall reside in a class which will be initialized with a settings object. The driver (f2cc.py) shall both initialize and call these methods.

Tickets & News

Attachments

  • top_TB.png Download (38.2 KB) - added by ugeorge 3 years ago. f2dot output for toySDF model, Top-Bottom orientation
  • top_TB_L1.png Download (22.3 KB) - added by ugeorge 3 years ago. f2dot output for toySDF model, Top-Bottom orientation, 1 level of detail
  • top_default.png Download (31.9 KB) - added by ugeorge 3 years ago. f2dot output for toySDF model, plotted with default options
  • top_labeled.png Download (67.6 KB) - added by ugeorge 3 years ago. f2dot output for toySDF model, annotated after changing the config options