↑↑ Home ↑ Hardware  

VHDocL - a VHDL documentation utility

Overview -- Features -- Example output -- Installation -- VHDocL and doxygen -- VHDocL and vhdldoc -- Further work -- Manual page

Overview

In the software world, documentation tools abound. Doxygen, javadoc, kdoc and others allow to extract specially formatted comments from source code and generate a set of interlinked HTML pages giving the annotated class structure of the program.

Similar tools for hardware description languages such as VHDL are much thinner on the ground. There is vhdldoc by Christoph Schwick; however, its parser is rather restricted to the coding style of its author. Disappointing experiments with vhdldoc caused me to create a new documentation utility specifically for VHDL from scratch. Around the same time, VHDL support was added to doxygen. But this functionality looks unmaintained, some documented markup features do not work, and doxygen does not (cannot) offer the VHDL-specific features that VHDocL does. Recent versions of VHDocL can parse doxygen markup and come with a conversion script.

VHDocL serves to document a hardware design at the structural level. Signals, formulas, function bodies and other functional components of the source code are ignored. Entities and architectures, function declarations, constants, processes, instantiations, generate statements and other constructs relating to the structure of the design are parsed and documented in HTML pages. As with other documentation generators, the code can be annotated with special comments which will be added to the HTML documentation.

The HTML ouput is interlinked extensively: instantiations are linked to the declaration of the component and to the entity to which it is bound. Bindings are determined across libraries if necessary and taking for...use statements into account. VHDocL also supports configurations.

From a presentational point of view, the generated documentation can be customised by a CSS style sheet file provided by the user, and by up to two logos displayed on every page.

VHDocL has been tested on a number of open-source designs and is being used on FPGA designs by me and by colleagues as well as larger ASIC designs.

Features blurb

Finally I have got round to putting up an example documentation output that has been requested repeatedly. Unfortunatly, it is less than perfect: All my own VHDL designs are copyright by my employer, so I cannot publish them, and as far as I can tell the same is true for other users. (If you have a design documented for VHDocL that may be published as an example, please let me know via the mail address vhdocl at this domain.) Most open-source designs are not documented at all, let alone for VHDocL. Finally I decided to use part of the System09 project on opencores, which has some documentation, and converted its comments to VHDocL compatible doc comments, partly automatically, partly manually. Unfortunately the amount of documentation is still rather uneven; and the resulting docs demonstrate only the most basic features of VHDocL.

Installation

Download VHDocL 0.2.6 from January 2018 (gzipped tar archive)

Installing:

  1. Install Perl. Linux users can obtain it using their distribution package manager; Windows users can for example install ActivePerl or one of the other Perl distributions for Windows
  2. If necessary, install the modules Cwd and File::Spec, File::Path, Digest::MD5, and possibly Time::HiRes (if you want to use the --benchmark option). Often most or all of these are contained in Perl base packages, but some users have reported having to install some by hand. (Use perldoc <module> to find out if you already have a module, or just run VHDocL and watch for errors.)
  3. Download and unpack the VHDocL distribution archive using tar xzf vhdocl...tgz or 7zip
  4. Run the enclosed Perl script install-vhdocl.pl to install. Add the option -h to view all options. Use the option -n for a dry run which displays the install paths. For Windows and MacOS, the installation directory has to be given on the command line. For UNIX-like systems the default is /usr/local, and the script and manual page will be installed in the canonical subdirectories.

If you want to be able to use labour-saving features of UNIX systems under Windows, such as finding VHDL files with the find command and piping the file list into VHDocL, you should install Cygwin. You can then install and use VHDocL as on a UNIX-like system.

Getting the current development version:

Obligatory health hazard warning: The current development version may not be well tested and therefore endanger your peace of mind. You have been warned.

If you still want to try the very newest version of VHDocL, you can clone its git repository with this command: 

git clone http://volkerschatz.com/repositories/vhdocl

Read the installation notes in the INSTALL file and run the script install-from-git.pl to install.

VHDocL and doxygen

As of version 0.2.5, VHDocL can parse and interpret doxygen documentation comments. I decided against incorporating all markup features of doxygen into VHDocL because they duplicate much of what HTML already offers and because I did not want to tie my hands about future improvements that might clash with existing doxygen markup. If you want to run VHDocL on sources documented for doxygen, you have to do nothing extraordinary, as VHDocL will automatically recognise comments starting with "--!" as being written for doxygen, in contrast to its own that start with "--*" or "--+".

If you want to use a VHDocL-specific feature, the simplest way is to add lines of "--*" comments to your doxygen documentation. VHDocL concatenates doxygen and its own doc comments for the same declaration, and doxygen will presumably ignore those starting with "--*". If you decide at one point that you want to use VHDocL exclusively, you can clean up your mixed (or pure-doxygen) comments with the Perl script doxyconvert that comes with VHDocL. It converts doxygen doc comments to VHDocL comments. It reads from its command-line argument or from stdin and writes to stdout, and you can use it as follows: 

mv source.vhd source.vhd.orig
doxyconvert source.vhd.orig > source.vhd

If you have a backup anyway (for example in a version management system), you can use reservoir or sponge to transform a source file in place: 

doxyconvert source.vhd | reservoir -o source.vhd

(reservoir buffers the output of doxyconvert until the conversion is completed and only then overwrites the original file.)

To convert a whole directory tree of source files, you can use a shell loop: 

find source_tree -iname \*.vhd\* | while read f; do
    mv $f $f.orig
    doxyconvert $f.orig > $f
done

Upgrade path from vhdldoc

For those (like myself) who have some old designs documented for use of vhdldoc, I wrote a small script which converts vhdldoc's documentation format to VHDocL's. (It is also contained in the VHDocL distribution package.) The main difference is that vhdldoc wants ports and generics documented with markup codes in the entity documentation, while VHDocL treats them as declarations in their own right. Besides, VHDocL allows to document library and use clauses and therefore requires an entity's description to directly precede it. Note that you need not convert your sources just to generate documentation; VHDocL's -m options turns on compatibility mode, which allows sources documented for vhdldoc to be parsed.

To convert a source file, do the following in a terminal: 

mv source.vhd source.vhd.orig
vdocupdate source.vhd.orig > source.vhd

Always make backups, and look over the results afterwards. vdocupdate is a simple script designed to spit out every non-comment line unchanged, but it is not being used all that much. You might want to run diff on the old and new files, and verify that your design still does what it should.

To convert a whole source directory tree, you could do the following: 

find source_tree -iname \*vhd\* | while read f; do
    mv $f $f.orig
    vdocupdate $f.orig > $f
done

All this assumes vdocupdate is somewhere in your executable search path; otherwise you will have to give its path.

Further work

Development of VHDocL has slowed in recent years as I do less integrated circuit design than I used to. All recent extensions were at the request of users, so do contact me if you need something VHDocL could but does not yet provide. (If it is a lot of work and/or does not fit with my idea of what VHDocL should be doing, I may turn you down, but you can always ask.) Bug reports are especially welcome. In non-trivial cases, VHDL code snippets that demonstrate the problem, or known workarounds or quickfixes are helpful. Direct any request to the e-mail address vhdocl at this domain.

VHDocL's manual page

NAME

vhdocl - a VHDL documentation and structure examination utility

SYNOPSIS

vhdocl [options] <input files...> [ [-l <library>] <input files...>]

print_filenames | vhdocl [options] -

vhdocl [-f] <config.vhdocl>

DESCRIPTION

VHDocL is the equivalent of doxygen, kdoc or javadoc for the hardware description language VHDL, including its newest variant, VHDL 2008. It generates a set of interlinked HTML pages from a hardware design. Specially formatted comments in the VHDL code are read and incorporated into the HTML pages (see "MARKUP LANGUAGE" below). For undocumented designs, VHDocL can still help understanding by making the structure of the design apparent.

An HTML page is generated for every entity, architecture, configuration, package or package body and context declaration. Documented items include processes, instantiations, ports, generic constants, component declarations, function and procedure declarations. Instances are bound to their matching entity and hyperlinked to its HTML page. See "OUTPUT" below for more information on generated files.

Besides, VHDocL creates a global list of entities (with their architectures and configurations) and packages and an instantiation hierarchy. The hierarchy results from the bindings of instantiations of components, entities and configurations within architectures or configurations. VHDocL takes for...use statements, configurations and default bindings of components into account when determining bindings of component instantiations. Nested configurations (i.e. configurations which configure sub-instances within instantiated modules) are also supported.

VHDocL is not a VHDL syntax checker. It tries to be as tolerant as possible regarding coding style and as a consequence may occasionally accept incorrect VHDL. Usually, however, incorrect code will cause it to fail without any useful error message. VHDocL parses its input using regular expressions designed to match those elements of VHDL which are relevant to its task and will simply ignore what it does not recognise.

OPTIONS

--benchmark

Print how much time vhdocl took for parsing each file and for subsequent processing. Only really useful to the author for identifying hot spots. Requires the Perl module Time::HiRes.

--custom=text|file.html

Add link to custom page to the navigation row at the top. The text is the text of the hyperlink, the file or URL the destination. Multiple --custom options create multiple links. On the command line, the vertical bar may have to be escaped from the shell.

--exclude=glob

Exclude files matching the glob pattern from processing. This is primarily intended to qualify directory searches, but single file names from the command line are also filtered. The glob argument is a list of shell glob patterns separated by commas and/or spaces. Each pattern has to match the complete file name or (if it contains a directory separator) the last part of the path. Matching is case insensitive. This option can occur multiple times but is not cumulative; rather, its current value applies to subsequent source files until the next --exclude option. The glob pattern will usually have to be escaped from the shell, for example by enclosing it in single quotes.

--eyecandy

Adds a block diagram to each entity page that contains no information not already present in the page. With --latex, the block diagrams are also included in the LaTeX output.

-f file.vhdocl, --configfile=file.vhdocl

Tells VHDocL to interrupt command line argument processing and to read options and input file names from the given configuration file. If present, this will usually be the only option (but need not be). Processing of command-line arguments will resume after the config file has been read. See "CONFIGURATION FILE" below for the configuration file format.

Footer string to be printed at the bottom of every documentation file. This will be put before the "Generated by VHDocL" notice which is also printed at the bottom. HTML entities and markup are allowed, for example to print a copyright sign or to separate the text from the "Generated..." notice by a horizontal rule.

-h, --help

Print brief usage message and the most important command-line options, then exit. No processing will be done if this option is encountered.

--homehtml=file

Insert the HTML document file into the home page of the documentation. file may but need not be a complete HTML document. If it is, only the part within the body tags will be copied, and the header will be discarded.

--javasyntax

Generate JavaScript for syntax highlighting of source HTML pages instead of generating marked-up pages directly. This will save some CPU time and may therefore be faster for large designs. On the downside, there will be a delay loading the HTML pages of large source files as the browser processes them.

-j n, --jobs=n

Use n tasks to parse source files in parallel. n=0 disables forking worker tasks for parsing. The default (when no -j option is provided) is determined with nproc or taskset -p on Linux, or set to 3 on other systems. This option is useful mainly when the VHDL sources are located on a fast SSD or a RAM disk, so that parsing speed is limited by CPU speed, not disk IO.

--latex

Generate LaTeX output. The LaTeX does not have the same content as the regular HTML documentation. LaTeX output only contains interface (entity and package) documentation for users of IP cores, and unlike the HTML output is not intended as developer documentation. See "LATEX OUTPUT" below for more information.

--leftlogo=image

File name or URL of an image to put in the top left of every HTML page generated. Intended for institute or company logos. If this is a file, it will be copied to the documentation folder.

-l libname, --library=libname

Indicates that the following source files belong to the VHDL design library <libname>. This will affect how components are bound. The default library is "work". All file names given before the first (or in the absence of any) library option are assigned to it.

-m, --compatibility

Vhdldoc compatibility mode. DON'T USE this option when writing new documentation.

-o path, --outputdir=path

Set the output directory. It (and the required subdirectories) will be created if it does not yet exist. The default output directory is "./doc".

--packagesummary mode

Print a summary of declarations at the top of package documentation. The summary shows the @brief description if available, or the first paragraph (at most 100 characters) of the full description. Possible modes are: always, never, auto and section. For auto and section, the summary is printed only if one of the declarations has sufficient documentation that the full description is not identical to the summary. For section this is decided for type declarations, constants, functions/procedures and components separately, for auto either everything or nothing is summarised.

--parsedebug

Switch on debugging of the VHDL parser. Prints out every declarative item found, and whether entering or returning from a nested block. Only of interest to the author.

-p word, --prefix=word

Set a prefix for all HTML file names generated in this run. This allows to generate documentation of several unrelated designs in the same output directory without interference.

--psl

This option is now enabled by default and will eventually be deprecated, as the Property Specification Language is part of the VHDL 2008 standard. For now, PSL support can still be disabled with --nopsl. See the "OUTPUT" section below for details on which PSL directives are documented.

-q, --quiet

Do not output what VHDocL is doing. Errors and some warnings will still be reported, though less verbosely than they would normally.

-r, --recursive

Search directories given after this option recursively for VHDL files. The negated form +r or --norecursive switches off recursion for the following directories, until the next -r option.

--rightlogo=image

File name or URL of an image to put in the top right of every HTML page generated. Intended for institute or company logos. If this is a file, it will be copied to the documentation folder.

Insert hyperlinks to each VHDL source file into its HTML page and the source overview. This allows to edit the file with one click if you set your browser's file associations accordingly. This option is enabled by default, but it may make sense to disable it, for example when the documentation is to be put on a web server.

--stylesheet=stylefile.css

File name or URL of a CSS stylesheet to reference in the headers of all generated HTML files. This allows the user to influence the appearance of the generated HTML. If this is a file, it will be copied to the documentation folder.

-t "modules ...", --topmodule="modules ..."

Designate some entities or entity-architecture/configuration combinations top modules. These top modules will be listed separately in the instantiation hierarchy page. The option argument is a list of space-separated strings. Listing an entity name makes all architectures and configurations of this entity top modules. Specific architectures and configurations can be given in the syntax entity(architecture) and entity[configuration]. This option is not affected by --library, so you have to give the library explicitly (as library.entity) if it is something other than work.

--tabsize=width

Set tab alignment for source markup pages. A zero width, the default, omits tab expansion and leaves it to the browser to display tabs correctly. This probably works only for a tab size of 8, however setting this option incurs a small but measurable increase in processing time. This option only applies to source files it precedes, and may be present multiple times to set different tab sizes for different files.

--title=string

Title string to be printed at the top of every documentation file. Intended to contain a brief description of the purpose of the design documented. HTML entities and markup are allowed, for example to print non-ASCII characters.

--toplink=[text|]file.html

Gives a hyperlink to appear in the navigation bar of all generated HTML files. That link replaces the one to the documentation home page, which will not be generated. Intended for "interfacing" with other local documentation of which the generated design docs are part. If present, the text before the vertical bar is used for the text of the hyperlink reference (the default is "Home"). Be aware that your shell may try to interpret the vertical bar and escape it if necessary.

--version

Print version of VHDocL and exit. No processing will be done if this option is encountered.

Long options may be abbreviated. Their arguments may also be separated by a space instead of =. Boolean-valued short options can be negated by replacing the "-" by a "+", long options by prepending "no" to the option name. Options other than the -l/--library, --tabsize, -r/--recursive and --exclude options can be mixed freely with input file names, and the last of multiple occurrences overrides the others.

USAGE

The most immediately obvious way to use VHDocL is by giving the source files to be parsed on the command line, like this:

    vhdocl submodule1.vhd topmodule.vhd submodule2.vhd

This will cause VHDocL to read the VHDL files, create the default output directory "doc" and some subdirectories and generate HTML pages in these directories. The file extension .vhd/.vhdl may be omitted when specifying source files.

It is not necessary to tell VHDocL every single source file name. If all your design files are located in a single directory, it is sufficient to say:

    vhdocl .

(Assuming you are currently in that directory.) VHDocL will then process all files with the extension .vhd or .vhdl in that directory. To include files in subdirectories, add the option -r:

    vhdocl -r .

In order to exclude some source files, you can use the --exclude option:

    vhdocl --exclude \*_tb.vhd -r .

For more sophisticated selection criteria, you can use the find command and pipe its results in to VHDocL's stdin:

    find . -iname \*.vhd -a -mtime +7 | vhdocl -

The argument "-" causes VHDocL to suspend command-line processing and read arguments from standard input.

It is not necessary to tell VHDocL which of the source files contains the top module(s), as it will automatically resolve instantiations and treat those modules which are instantiated nowhere as top modules. (So unless you omit testbench files from the source file list, they will be regarded as top modules.) The -t option allows you to designate some top modules, which are then displayed more prominently on the hierarchy page. This allows you to separate your design top modules from test benches and other uninstantiated modules.

Arguments to VHDocL, both options and input file names, can be given in three ways: on the command line, on standard input and in the configuration file (see below). These three possibilities can in principle be intermixed freely (though in how far that is a good idea is a different matter). Parsing of command-line arguments will resume after parsing a configuration file or standard input, and parsing of the remainder of a config file will continue after parsing an included configuration file.

Assuming your design comprises two design libraries, work and play, and you are currently in the directory of the play library, which does not have any subdirectories and is located beside the directory containing the work library, you can generate documentation with:

    find ../work -iname \*.vhd | vhdocl - -l play .

VHDocL will read all file names found by find from standard input and assign them to the default library work. Then it encounters the library option and the directory ".". It finds all VHDL files in this directory and assigns them to the library play.

CONFIGURATION FILE

Instead of on the command line, VHDocL options and input files can be given in a configuration file. This allows these arguments to be saved as part of a design project. A configuration file to be read is specified with the -f option. As a special case, if only one file name is specified on the command line and if that file has the extension .vhdocl, this is taken to be a configuration file not a source file.

The configuration file is a plain text file containing VHDocL options, input files and possibly comments. An option is specified by the option name, which is identical to the long command line option without the "--", an optional equals sign and its value.

Boolean-valued options can be specified by just giving their name or its negated form ("no..."). If a value is given, it may only be "1", "on", "yes", "true", "0", "off", "no" or "false" (case insensitive). The option "configfile" serves as an include directive.

Input files and directories are specified like options, with "input" instead of the option name. File names are taken relative to the location of the configuration file. (So are the arguments of options like "outputdir", "stylesheet" etc.) Multiple "input"s are allowed, as are several files per "input", separated by spaces. File names containing any of *?[]{}~ are interpreted as glob patterns for searching for source files (but not directories). File names which contain any of these characters have to be quoted by single quotes. File names containing white space can be quoted by single or double quotes (which do not quote glob characters). As on the command line, the source files are assigned to the library given with the latest "library" option, or the work library if no "library" option was encountered. VHDocL warns if input files or directories do not exist, or if glob patterns yield no files, but not for empty directories.

The configuration file is line-oriented. Every option or input file specification has to be contained in a single line. However, lines may be continued in the following text line by putting a backslash at the end of the previous line. The backslash may be followed by white space and a comment. Comments start with the "#" character and extend up to the end of the text line. To avoid ambiguities, "#" characters are not allowed in comments, and if a "#" is contained in an option value, a comment must be present. In other words, VHDocL removes anything from the last "#" to the end of the line.

A configuration file could for example look like this:

    ######################################################
    #  Contrived VHDocL config file for non-existent design
    ######################################################
    
    quiet= true
    noparsedebug
    leftlogo= http://www.bigbucks.inc.biz/logo.png
  
    # These go into library work:
    input topmodule.vhd submodule1.vhd \  # comment allowed here
          submodule2.vhd
    
    library play
    input= fun.vhd songndance.vhd

As on the command line, directories may be given instead of files, and all VHDL files in those directories will be parsed, subdirectories included if the "recursive" option is in force. The special input file "-" for reading file names from standard input is not allowed in config files.

MARKUP LANGUAGE

Though VHDocL helps to understand undocumented designs, its primary purpose is as a documentation tool. Most VHDL declarative items can have a description associated with them, which will be printed in the relevant HTML page. These descriptions are given in comments in the VHDL code which start with "--*" instead of "--". They have to directly precede the declarative item to which they refer or be located on the same line. Documentation comments preceding statements or declarations which are not documented are discarded. Empty lines (just "--*" and white space) serve to separate paragraphs in the documentation text.

Here is an example:

    --* This process defines an up-counter.  This would not normally
    --* warrant much of a description, but this is to demonstrate that
    --* VHDocL documentation comments can extend over several comment
    --* lines.
    --*
    --* Here is an equally contrived second paragraph, again designed to
    --* show how to write documentation for VHDocL.
    upctr : process( reset, clk ) is
    begin
      if reset = '1' then
        count <= (others => '0');
      elsif rising_edge(clk) then
        count <= std_logic_vector(unsigned(count) + 1);
      end if;
    end process upctr;

To prevent separators from being misinterpreted as documentation, "--*" may not be immediately followed by a further "*", or the comment will be ignored. If you want to create a separator in the documentation, insert a space between "--*" and the row of asterisks.

The description text in the documentation comments can contain certain HTML tags. The following tags are allowed without attributes: b, i, tt, u, big, small, sub, sup, em, strong, ul, ol, li, br, center, pre, table, tr, td, and th. The tags a, span and img are allowed with attributes. Note that the URLs in the a and img tags will not be transformed in any way, so they have to be either an absolute URL or a path relative to the future location of the documentation HTML file in which they will appear. The tags code and var are a special case: VHDocL will mark up text inside code tags as VHDL source code, and within var as VHDL identifiers. This will not be done if these tags have any attributes already, allowing the user to override the default and use CSS classes from custom style files.

For example, the pre tag can be used to create ASCII graphics:

    --* This entity represents an adder tree with four inputs:
    --*
    --* <pre>
    --*           +
    --*      ,---' `--.
    --*     +          `+
    --*    / \         / \
    --* in1   in2   in3   in4
    --* </pre>
    
    entity adder4 is
      port (
        --+ Inputs to be added up
        in1    : in std_logic_vector(7 downto 0);
        in2    : in std_logic_vector(7 downto 0);
        in3    : in std_logic_vector(7 downto 0);
        in4    : in std_logic_vector(7 downto 0);
        --* Output giving the addition result.  This is two bits wider
        --* than the inputs to avoid overflow.
        result : out std_logic_vector(9 downto 0)
      );
    end entity adder4;

The example demonstrates another feature of VHDocL: If a documentation comment starts with "--+" instead of "--*", the given description is assigned not just to the following declaration, but to all following declarations of the same type (ports in this case), until a different description is encountered. "--+" is intended and will work only for "simple" declarations such as ports, constants and so on, not for declarations like processes or functions which are followed by a block of code. Similarly to "--*", "--+" may not be immediately followed by a further "+".

This brings us to the question of what declarations can be documented. First, the "big six" top-level declarations (entities, architectures, configurations, packages, package bodies and context declarations) can have descriptions. Also documented are ports, generics, library and use statements, and context references. Within architectures and packages, constants, functions, procedures and component and type declarations (including records, record elements and units) can be documented. Likewise generate and block statements, processes and instantiations inside architectures and "for ... use" statements in architectures and configurations. Local declarations of constants, functions etc. within other functions, generate statements of similar declarations with their own declarative part cannot be documented and will not be output to the generated HTML pages. See "OUTPUT" below for a description of what VHDocL generates.

The description of entities, architectures, configurations, packages, package bodies and context declarations can contain the following markup codes, some of which are also valid for constants, types, functions, procedures and components (called "minor declarations" below). Their arguments extend up to the next empty line or the next markup code.

@author name, ...

Author or list of authors separated by commas. Cumulative if it occurs several times.

@brief description or @short description

Brief description to be printed at the top of the item's HTML page and in the global lists. Use only one of @short and @brief, and only once. This is also available for minor declarations.

@date date

Modification date of this item.

@deprecated, @internal, @simulation, @synthesis, @testbench

Causes that word to be printed prominently in the top region of the item's HTML file. @deprecated and @internal are also valid for minor declarations. Design units marked @internal or @testbench are not included in the LaTeX output.

@frominstance / @fromwrapper [ entity[.port] ]

Only for ports and generics of entities: causes the documentation to be inherited from a homonymous port or generic of an entity instantiated in this one, or by which this one is instantiated. This is intended to avoid duplication of documentation when an entity wraps or implements another.

The optional argument specifies the name of the entity, component or instance label from which to inherit, which allows resolving ambiguities. Its optional suffix, separated by a dot, specifies the name of the port (or generic) to inherit from. The documentation of the affected port or generic is replaced, not amended. If the ports / generics of an instantiated component are documented, they take precedence over those of the corresponding entity. Inheritance can be chained so long as no cycles are created.

@id ID

Revision control system ID of the item.

@param name description

Description of function or procedure parameter name.

@return description

Description of function return value.

@see reference1, reference2, ...

Cross reference. This markup code may occur several times, and every time multiple cross references may be given separated by commas. If the reference is the name of an entity, architecture, configuration or package, the reference will be hyperlinked to its HTML page. For minor declarations, cross references may also point to other minor declarations. Using selected names allows referencing declarations in other packages or libraries.

@version version

Revision of the item.

Markup codes have to be preceded by white space or the beginning of a line, so e-mail addresses are not misinterpreted. If this is not sufficient, you can use the HTML entity &#x40; to insert a verbatim "@".

@date, @id and @version tally nicely with keywords automatically substituted by revision management systems such as Subversion (http://subversion.tigris.org/) or git (https://git-scm.com/, see below). (@author is a different matter since Subversion merely substitutes the author who did the last commit.) If you use Subversion, you can enable keyword substitution for your VHDL file with the following command:

    svn propset svn:keywords "Date Id Rev" source.vhd

You can then write in the description of an entity:

    --* @date $Date$
    --* @id $Id$
    --* @version $Rev$

The date, ID and version number of the last change to source.vhd will then be inserted into the documentation comments by Subversion. VHDocL strips the Subversion keywords and dollar signs, leaving only the information substituted by Subversion. This is in fact done for all Subversion keywords in all documentation comments, so you may also use them in your documentation text if you like. Note that VHDocL descriptions relate to an entity or an architecture (or other declarative item), whereas Subversion keywords relate to files. So a changed date does not necessarily mean that something changed in the entity declaration. But if you have a separate file for each entity/architecture and package/package body pair, having Subversion data in their description is still meaningful.

A similar feature is supported for sources stored in a git repository. If the text after a @date, @version, @id or @author markup is just "$git$", VHDocL runs a git command on the source file to obtain that information. The date, version and author is from the most recent revision of the file according to git log; the version is made more readable by git describe. The file ID is determined by git hash-object and can also be used for files not in a repository. The same caveats as for Subversion apply: The author of the most recent revision is not necessarily what you want, and a design unit may not be modified even if its file was.

Doxygen compatibility

vhdocl can parse doxygen markup comments starting with --!. It supports the documentation markup codes \author, \brief, \date, \deprecated, \internal, \param, \private, \result, \sa, \see, \short, \return and \version by replacing them with its corresponding own. The codes \arg, \b, \c, \code / \endcode, \e, \em, \i, \li, \n, \p, \verbatim / \endverbatim are transformed to their HTML equivalent. All doxygen markup codes may start with @ as well as \.

OUTPUT

VHDocL generates five top-level documentation pages which are located in the output directory: A list of entities (with their architectures and configurations), a list of packages and contexts, an instantiation overview, an instantiation hierarchy and a list of source files. They are named entities.html, packages.html, instantiations.html, hierarchy.html and sources.html, possibly preceded by the prefix. The difference between the instantiation overview and hierarchy is that the overview merely shows the first-level instantiations in each architecture and configuration, while the hierarchy recursively shows all instantiations in sub-(sub-...)modules. Both list every instantiated module only once, even when it is instantiated several times in the same parent module. The hierarchy stops at recursive instantiations, if applicable.

There is also a home page index.html in the output directory which links to the five pages mentioned above. The --homehtml option allows to insert an existing HTML document into this page, for example a general description of the project. If a top-level URL is given with the --toplink option, this is supposed to replace the home page, and index.html will not be generated. The top-level declarations listed in the top-level HTML files are hyperlinked to the HTML files which describe them in detail, located in the correspondingly named subdirectory of the output directory. If a @brief/@short description is available, the top-level HTML files display it.

All entities, architectures, configurations, packages or package bodies and contexts are described in HTML files of their own located in the respective subdirectory. Packages and their package body share the same file. It contains their description, with special markup codes such as @author displayed prominently near the top. The name of the source file which contains their definition is displayed, and the source HTML page may be hyperlinked depending on --sourcelinks. The top-level library and use clauses and context references in that source file are documented. The documentation of other sub-declarations follows.

An entity's HTML page documents its ports and generics and links to the pages of its architectures and configurations and to the entities and architectures that instantiate them. Architecture pages contain all of the following as applicable: declarations of functions, procedures, types, constants and components, instantiations, processes and generate and block statements. Instantiations are hyperlinked to the instantiated component, entity or configuration. Use statements referring to component instantiations are not printed separately, but expressed implicitly in the binding of the instances. Attributes are mentioned in the documentation of the declarative items they refer to. Similarly, generate and block statements are documented along with the instantiation or process they enclose. If they do not contain either, they are ignored, like use statements or attributes which refer to nothing.

Here is an example of how an instantiation which is inside three nested generate statements is documented:

    Comparator : RankCmp
        Compare centre pixel to each other pixel in the neighbourhood
        Generic map:
            DataWidth   => 8
        Binding: work.RankCmp (combinatorial)
        This instantiation is inside the following constructs:
            RankRows : for row in 1 to WindowHeight generate
            RankCols : for col in 1 to WindowWidth generate
            SkipCentre : if row /= WindowHeight/2+1 or col /= WindowWidth/2+1 generate

The first line gives the name of the instance and the name of the component, which is hyperlinked to its declaration. This is followed by the instance's description and its generic map. Next, the component binding is printed, with links to the appropriate entity and architecture. Last comes a list of the generate statements enclosing this instantiation. If they had descriptions, they would be printed under the generate statement they refer to.

Unless the option --psl is disabled, some PSL statements in architectures are documented. This includes definitions of named sequences, endpoints, properties and a default clock, and the verification statements assert, assume, assume_guarantee, restrict, restrict_guarantee and cover.

Pages of configurations display the prescribed bindings in a hierarchical manner similar to the global instantiation hierarchy. The use statements are hyperlinked to the pages of the selected entities, architectures and/or other configurations.

Packages and their package bodies are documented in the same HTML page. It contains the declarations of generics, types, constants, functions, procedures and components. By default, PSL sequence, endpoint and property definitions are also included. The documentation of corresponding declarations in the package and its package body is merged, and the package body section is omitted unless it contains unique declarative items.

Source files are converted to HTML files with syntax highlighting and line numbering. This is done by assigning CSS classes to words and expressions in the code. Their appearance is determined by a default CSS file and can be overridden in the user CSS file. The same applies to source code quoted in the documentation pages. The source file itself is hyperlinked from the source pages (unless you choose --nosourcelinks), so you can edit it by clicking on the link if you have the file associations of your browser set accordingly.

CUSTOMISING APPEARANCE

Numerous CSS classes are assigned to the HTML elements of the output. Most of them apply to the VHDL syntax, both in the source file pages and the code fragments in the documentation pages. Others control the indentation of the layout tables used for most lists and the appearance of descriptions from the documentation comments. The default VHDocL style file vhdocl.css defines the standard syntax markup style and contains examples of some other CSS classes.

archdecl

First line of component, function, procedure, PSL or type declaration in an architecture or package body. Allows to visually separate successive declarations with long descriptions. The reason for lumping together architectures and package bodies is that both their declarations are local, in contrast to those in packages. This can be visually distinguished by choosing a different appearance for this class and packdecl.

bigdesc

Description of major design element (entity, architecture, configuration, package or package body, context). See also smdesc.

bigbrief

Brief description at the top of the pages describing design elements. (Not when brief description is printed in lists.)

declid

Identifier of a declarative item documented by VHDocL. Applies to entities, architectures, packages, configurations, functions, procedures, components, and instances. By default, the appearance is the same as for identifier.

doccom

Appearance of VHDocL documentation comments in the source HTML pages. Up to version 0.2.4, this also applied to descriptions in documentation pages, but for that purpose it has now been superceded by bigdesc and smdesc.

identifier

VHDL identifier, other than those marked by the classes declid, pslid, typeid or vhdlieee.

nocode

Non-code words inside quoted code, such as the "unnamed" notice for nameless processes. Not used in source pages.

packdecl

First line of component, function, procedure, PSL or type declaration in a package (but not the package body). Allows to visually separate successive declarations with long descriptions.

packsum

Package summary section. Only effective if --packagesummary is enabled.

pslid

Identifier of PSL named sequence, endpoint or property. Ineffective if PSL support was disabled.

pslword

Keyword of PSL (Property Specification Language). Ineffective if PSL support was disabled.

shaded

Applies to every other line in the source HTML pages. Defaults to light grey background colour.

smdesc

Description of subordinate declaration. Applies to all declarations except the six major design elements. See also bigdesc.

smbrief

Brief descriptions of declarations that are not major design elements. (Not when brief description is printed in summary for --packagesummary.)

typeid

VHDL type identifier. Standard IEEE types belong to both this class and vhdlieee. The !important directive can be used in the CSS style file to choose which its appearance will be.

vhdlcode

Encloses all code quotes, allowing for example to set a monospace font. All other classes related to syntax markup occur within this class.

vhdlcom

Non-documentation comments in the source HTML pages.

vhdldecl

VHDL keyword denoting a declaration documented by VHDocL.

vhdlieee

Identifier from IEEE standard package.

vhdlio

VHDL I/O direction indicator such as in, out and inout.

vhdlvar

VHDL declaration keyword variable, signal, constant, attribute or file.

vhdlword

Other VHDL reserved word.

vhdlstr

Quoted VHDL (bit) string or character or bit.

vhdoclind

Class to which table cells used for indentation belong. Indentation is proportional to their width. The default value is 50 pixels.

vhdocltab

Class of layout tables. Their cell padding is set to 3 pixels by VHDocL and can be modified by setting the padding CSS property on their cells (not on the tables themselves).

The assignment of classes to source listings is based solely on word recognition, and as a consequence is not perfect. For example, the word in occurring in for...generate statements will be misidentified as belonging to the vhdlio class.

LATEX OUTPUT

If the --latex option is active, VHDocL generates LaTeX documentation in the subdirectory latex of the documentation target directory. The LaTeX output is not equivalent to the HTML output. HTML is much more suitable for code documentation due to its unlimited page size, absence of serial page order and JavaScript interactivity. The LaTeX output is provided for inclusion in printable manuals aimed at IP core users, not developers. Unusually long source code fragments such as RAM initialisers may give rise to overlong lines and require postprocessing for prettyfication.

With that in mind, the LaTeX output includes only interface documentation of entities, packages and contexts, and nothing at all on architectures, configurations, package bodies and source files. The markup codes @internal and @testbench, which are purely informational in the HTML output, cause a declarative item to be omitted from the LaTeX documentation. If both HTML developer documentation and LaTeX user documentation is to be generated from the same sources, all design units that are not intended for users should be marked @internal.

Four TeX files are generated - a top-level file, top.tex, a file intended for style customisation, style.tex and one file each for packages (packages.tex) and entities (entities.tex). Output file names are affected by --prefix as usual. style.tex is included late enough to override defaults in the top-level file, and is not overwritten if it exists. The documentation of a package or entity takes up one subsection in their respective TeX files; the section headlines are in the top-level file.

The documentation comments are translated from HTML to their LaTeX equivalent where necessary. Inline LaTeX in the comments is not supported.

The generated TeX code uses a number of LaTeX packages. The less common ones are listings for VHDL syntax markup and longtable and tabu for tables continuing over several pages. The alltt package is used to translate the pre HTML tag, amsmath to translate some HTML entities (special characters) and inputenc to allow UTF-8 encoded documentation comments. If the generated LaTeX is to be incorporated into a different document, the usepackage statements from top.tex have to be copied.

If the --eyecandy option is active, entity block diagrams are included in the LaTeX output.

MACHINE-READABLE OUTPUT

The instantiation hierarchy is also output to a machine-readable text file in JSON format that is compatible with YAML 1.2. This allows other tools to make use of the information VHDocL extracts.

The top-level data structure is an array with three elements, the hierarchy itself, an array of designated top modules and an array of other uninstantiated modules. The hierarchy itself is an object (called a dictionary or hash in other languages) that maps the names of nodes to objects describing their instantiations and other properties. Node names are constructed from the template "library.entity-architecture[-configuration]". Each node object has the entries "entity", "architecture" and possibly "configuration" as well as "file" (the file name where it is defined). The "instantiations" entry has as its value an array of node names instantiated in it.

BUGS AND LIMITATIONS

VHDL is acknowledged to be a hard language to parse, and it offers many freedoms which lead to large differences in coding style. VHDocL performs a basic parsing of the declarative elements in the input files by trying to identify them using regular expressions. The parsing has now been tested on a largish number of designs, most of them not coded by the author. Still, it is possible that your design may be incorrectly parsed. If so, you can help me greatly by sending me a copy of the VHDL file which failed to be parsed.

Purely syntactical issues aside, the more advanced features of VHDocL (such as support for multiple libraries and for configurations) could not be tested as thoroughly as its more frequenly used features. If something breaks there, I would also be interested in your design, or even better a simple test case.

Instantiations without either a port map or a generic map are not supported. Positional association for generic maps is not supported.

Nested declarations, such as functions inside functions, constants inside processes, etc. are parsed but not documented.

The home page of VHDocL is http://www.volkerschatz.com/hardware/vhdocl.html. Backfeed is welcome to the e-mail vhdocl at that domain.

COPYRIGHT AND CREDITS

VHDocL is (c) 2007-2018 Volker Schatz. Credits to Minh Cuong Tran for providing a first implementation of the clickable hierarchy view and syntax highlighting, and for much efficiency testing. Many thanks to Torsten Meißner for testing on OS X. Likewise, thanks to Andrea Campera of Campera ES for suggesting LaTeX user documentation output and block diagrams, and pointing me to a better implementation of the latter. Thanks to several other users for smaller fixes, bug reports and helpful feature requests.

VHDocL is free software and may be redistributed and/or modified under the terms of the GNU General Public License, version 3 or later.

TOS / Impressum