HierarchySurfer2

HS2 is a Perl (v5.x!) script that analyzes a set of Verilog or VHDL source files in order to derive their hierarchy. After the source files are parsed and the hierarchy is determined, various tool scripts are generated as well as a report on the hierarchy. Also, a detailed report file is generated to give you more information about the designs that HS2 found. The current version is v2.26.1 released on 9/12/0.
 
This is the page to:

• Learn about the latest release of HS2.
• Review the HS2 documentation
• Report a problem, ask a question, beg for an enhancement

Here is an executive summary of what is new in this release:

• Updated the copyright and usage information. Please see the comments for details
• Added the '-C' switch to turn on Cyclone files once again.

• Surfing large gate level netlists takes a loooong time

• Putting port information into the unit report files

What is HierarchySurfer2

Why use HierarchySurfer2

How to use HierarchySurfer2

The defaults are:

Here is an example of looking in two directories for two different file extensions:

HS2 -d ~erik/source/vhdl /home/carlw/testcases -e vhd hdl

Of course, the Perl interpreter must be installed on your UNIX system. HS2 will only run under Perl5. You can get Perl from one of the Perl homepages, like this one http://perl.com/perl/index.html

Switches and such

• -l VHDL | Verilog.  This tells HS2 what type of source code to expect.  The default is VHDL.
• -c list of one or more library cell files.  These files contain library cell names that HS2 should ignore whilst parsing.  There can be one or more files, and the cells names should be space seperated.
• -d list of directories. This is a list of space separated directories in which to search for files
• -e one of more file extentions. This is a space separated list of file extentions to look for
• -h  For the most up to date info, then exit. 'Nuff said
• -w In VHDL mode, this causes HS2 to write explicit configurations for all the entity/arch pair that it finds. This is useful when there are more than one. You can turn this switch one and surf the code, then remove the configuration files you don't want to keep and surf again.
• -t top_entity_name. This tell HS2 to treat this entity or module as the top of the food chain. HS won't try to derive any other 'top' designs. This is useful if you know the top and don't want anything else played with! -v This turns on the verbose mode. In this mode, HS2 will tell you everything that it is doing and what it finds of interest.
• -v.  This turns on the verbose mode.  HS2 will then tell you everything that it is surfing and finding.  For large source sets, this output can be pretty large and boring.
• -x files to exclude This is a list of space separated files that should be excluded from parsing. Note, if the files are in the current working directory, you must include the ./ to the path like this -x ./erik.vhd
• -s elaborate every single entity/arch. This is off by default. The synthesis scripts will elaborate the top level design
• -z  This switch tells HS2 to print its numeric version then die.  This is used by DS2 to make sure the versions of SHF are in synch.

Scripts and Outputs

In VHDL mode, each top level design gets the following scripts:

• A dc_shell analyze/elaborate script
• A ha_shell analyze/elaborate script
• An RTLA setup script
• A VSS vhdlan script
• A vhdlan Makefile
• Cyclone cyan and cylab scripts, turn on the "-C" command line option to get these
• A csh clean up script
• A unit report file
• A SHF file.  This is Tcl data structure for use with DesignSurfer2.

In Verilog mode, each top level design gets:

• A unit report file
• A SHF file.  This is Tcl data structure for use with DesignSurfer2.
• A dc_shell read script
• An RTL Analyzer setup script
• A csh clean up script

Runtime Outputs

1. Set up and check for files to parse
2. Parse the files
3. Merge design unit information
4. Build the hierarchy (s)
5. Output the scripts and reports

VHDL Configuration Handling

HS2 will only "succeed" and produce scripts if every entity in all the source files has one and only one valid configuration. This occurs in the following cases:

1. A single explicit configuration and any number of implicit configurations.

2. A single implicit configuration and no explicit configurations.

Any other case is not "clean" so HS2 can't determine the hierarchy automatically. If this happens, HS2 will spit out the offending entitys and any files that contain configurations.

One common occurance is many implicit configurations. If this happens, re-run HS2 with the "-w" switch and it will write an explicit configuration file for every implicit one. Then you can delete all the one that you don't want and run HS once more to build the hierarchy.

A common technique when there are more than one explicit configurations is to move all but the desired file to another extension, like "erik.vhd.other". In this way, HS2 won't find and parse that file.

Like the rest of our synthesis tools, configurations are only supported for one level of entity/architecture mapping.

Hierarchy VHDL Error Reporting

"An entity can only appear once in a set of source files, and each entity can have only one valid configuration"

HS2 also attempts to detect when components are "missing". This could mean that you did not include all the source files in the surf path. It could also mean that the component is contained in a package that HS2 did not surf. These are only warnings, not errors, so scripts are produced.

VHDL Restrictions

• "begin" keywords in entities will cause problems.
• Each entity can only have one valid configuration

Common Questions and Answers:

a) Quite simple really, after all the entities or modules are read into the system. The information for each design unit is "merged" together. Now the design unit knows what its children are, but not who its parents are. So, for each given design unit, HS2 looks to see if it is a child of another design.  If it is not, then it is a top level design.

2) How can HS2 know what the difference between my testbench and the top of my design?

A) It can't! HS2 does not care if the code in the files is or is not synthesizable, it just determines the hierarchy for that code. The recommended way to work around this is to run HS2 once on your complete set of files. Look for the entity name or design file that is your top, then re-run HS2 with the "-t" followed by that top entity name.

3) How come HierarchySurfer does not support Verilog.

A) It does, use the -l Verilog switch.

4) What limits are there on my coding style?

A) HS2 was designed to have no limits, but it is a pretty hacked together set of parsers. We don't need a tool getting of the way of designers. If you find some code that is not parsed correctly, please email it to me (erik)

5) When ha_shell elaborates the top level design, it pulls in some previous db files in my search_path, how can I stop this?

A) This is a bug with ha_shell that will be fixed sometime. For now, you have to not let ha_shell see those db files. You can do that by: 1) removing the files, or 2) removing their location from your search_path variable.

6) Does HS2 produce make files?

A) For VHDL simulation analyze, it does. The makefile produced is a very programmable description of how to build a simulation model. Try it, you might likeit!