% VHDL Analyzer - Generate VHDL structure diagrams % Angel Ezquerra
The VHDL analyzer is a small, python-based tool which can parse VHDL files and, using pydot (and its requirement, GraphViz) generates diagrams showing the structure of those VHDL files, including instances, processes and their state machines.
The VHDL Analyzer can be useful in several scenarios:
- If you need to quickly undersand some existing VHDL code base
- If you need to generate documentation for your existing VHDL files
- If you need to verify that the state machine you wrote in VHDL does what you think it does.
The tool is made of a single python script but it has some external dependencies (check the "Dependencies" section below for more details).
The script is a bit hacky (see the "Caveats" section below for more details). That being said, it has been tested with several pretty large VHDL code bases and it has worked pretty well.
The VHDL Analyzer script is command line based. It uses Python's built-in argparse module for its command line interface. This means that you can do:
python vhdl_analyzer.py -h
to get a detailed help message showing you the different arguments that you can use to control what the tool does.
You can ask the tool to analyze a single file, but you can also specify a folder or a set of folders to analyze, in which case the tool will look for .vhd files, recursively, on those folder(s) and its subfolders. You can also provide a ISE project file (.xise) as the tool input, in which case the tool will analyze the .vhd files referenced on that project file, and it will automatically detect which is the VHDL file containing the top entity of the project.
You can also specify the format of the saved diagrams (e.g. SVG, PNG, etc) plus other options to control how those diagrams should look, etc.
For other options please check the built-in help.
To use this script, you must have the following programs and packages installed:
- Python 2.7
- To generate the diagram files
- URL: http://www.graphviz.org
- Python GraphViz frontend
- URL: http://code.google.com/p/pydot
- pyparsing 1.5.7:
- Required by pydot (note that version 2.x is not Python 2.x compatible).
- URL: http://pyparsing.wikispaces.com
It is possible to generate a stand-alone vhdl_analizer executable whose only external dependency is GraphViz. To do so you must have py2exe installed in addition to the dependencies above.
To generate the executable simply run:
On Windows you can also just execute "gen_exe.bat", which runs the command above for you.
The setup.py script will also create a zip file containing the files generated by py2exe.
Caveats and limitations
The script is slightly hacky. I had a lot of new VHDL code to analyze and I needed something to help me with that task. I searched online and I did not find anything that fit my needs so I decided to make a tool of my own. While I always try to make my code as good as possible, my purpose was to make something that worked well enough to be able to understand the new code base that I recently inherited (i.e. I did not have the time to create a perfect tool).
In particular, there are several things that could be improved:
I did not use or write a proper, full VHDL parser and I did not use a generic parsing library (such as PyParsing or SimpleParse). Instead I wrote a small, regular expression based parser which understands just enough VHDL to generate useful diagrams. I did not have a lot of time to dedicate to writing the first version of this tool, and the simple regex parser I wrote works well and is able to parse all the VHDL code that I've thrown at it (when it did not work, I improved the parser). I'm sure there are some corner cases or non common VHDL constructs that would trip it up but for the usual, idiomatic VHDL it works pretty well in my experience. If this ever becomes a limitation we could improve the parser, perhaps using pyparsing or a similar library.
The parser generates a very ad-hoc, custom, data structure. The data structure is a mixture of OrderedDicts, lists and regular dictionaries. I should probably change it to use proper classes for entities, processes, etc. That being said, the advantage of using lists and dicts is that it was very easy to add new things as I went along. This was important given the time constraints that I had, but the result is not very pretty. You have been warned! :-)
This software is licensed under the terms of the Lesser General Public License, version 2.1 LGPL-2.1.