System for VHDL design documentation

CESNET technical report number 5/2007
also available in PDF, PostScript, and XML formats.

Pavel Erlebach
15. 5. 2007

1   Abstract

The aim of this report is to describe the system for generating the VHDL design documentation. The source files (mostly in XML and FIG format) are stored in CVS of the Liberouter project (possibly in more versions), the output files are publicly available via website (in PHP/HTML and figures in PNG format). The result of generating is the whole part of the website dedicated to VHDL design, which is the main page, project pages, component pages (possibly in several versions) and an internal page containing the list of errors, warnings and another additional information.

2   Introduction

The Liberouter group is engaged in many projects (as NetCOPE, IDS, SCAMPI asf.) which need to be documented for both internal and external purposes. The best way how to make this documentation available for external partners, seemed to be the website. However, it was unbearable to demand the webpages to be written by VHDL designers. Hence, the idea of a generating system appeared. The VHDL designer writes a documentation of his project/component in a well-known language and it is then automatically compiled into the format which can be seen publicly via website.

The format of text source files was declared to be the XML format partly using the Satrapa XML description. The format of figures was not unified, one can use either whatever viewable format such as JPG, GIF, PNG and so on, or create schemes in the FIG format, which is automatically converted into PNG format by the system.

3   The main concept

The source XML files are stored in CVS in a fixed hierarchy. The exact description of the location and the expected content of these files is inscribed in 35 pages specification document, let us outline only the very basics here. The main files vhdl.xml (resulting in the main page) and project.cfg (containing paths to source files of documentation of each project) are stored in the folder cvs:/liberouter/vhdl_design/doc/. In the case of projects and components very similar scheme is used - one XML file, one optional CFG file with paths to source files of (sub)components and in addition, one XML file containing the information about versions.

3.1   XML to HTML conversion

The conversion is done partly in common way, that means with help of XSL transformations. In some parts XSLT is not powerful enough, then the conversion is done by Perl. Let us note, that the original Techrep format for technical reports is used in the specification, but in a little modified way, e.g., references to external files, pages of another components or projects were added.

Each compiled XML file results in 3-6 web pages (HW section, SW interface, Address space, etc.) corresponding to the specification. In Figure we can see the sample of source XML code and resulting web page.

Figure 1: XML code and resulting web page

3.2   Pictures

In the documentation all viewable formats of pictures can be used. In addition, it is possible to include a picture in the FIG format, which is automatically converted into the PNG format. Since it is often needed to display a too large picture, all pictures are automatically resized to fit the webpage if needed and only clickable thumbnail is then displayed. Moreover, it is possible to specify the relative width of a picture (0-1), where 1 is maximal width allowed by the size of the page. An example is shown in Figure.

Figure 2: Example of resized pictures

3.3   Address space

Address space is the example of the part of documentation, which cannot be handled by XSLT. It is required to create a tree structure of address spaces and registers based on arbitrarily nested tags linked by attribut id in the source XML file. Moreover, the offsets must be recalculated and pages of particular registers created. In Figure, we can see a sample of source code and resulting page.

Figure 3: Address space processing

3.4   Versions

It is possible to have each project and component in arbitrary count of versions in CVS. The information, which versions will be generated, is hidden in the version file which is required to be in each component and project folder. The process is then as follows. The CVS in the most actual version is downloaded, the particular version file is compiled, the web page of versions is created and then for each given version the CVS is downloaded and the documentation is generated. Let us note, that this process takes approx. 90% of the computation time, especially downloading of various version of CVS (9% is then needed to convert pictures and the XSL transformations take the minimum of computation time).

3.5   Binding to previous version of documentation system

In the past, the first version of system generating documentation appeared, but after some time it was decided, that it needs to be reworked (e.g., generating of versions was not supported). Relatively large part of XML source files was created according to the specification of the previous system. However, after this system was created, new XML source files started to be produced according to the new specification and it was needed to solve somehow the presence of XML source files of both inner schemes. The active projects were rewritten according to the new specification and the completed projects were kept unchanged. The binding itself is then made only in the main page - there are references on projects in both versions. Of course, a direct URL reference pointing across the versions can be pasted into the web pages, however, it is not recommended by reason of the difficult maintenance.

3.6   Offline generating

Besides the generating, which is performed automatically and outputs the web pages on the project website, the system supports so-called offline generating which is useful in the case of debugging the documentation of a component/project. The VHDL designer downloads the CVS in appropriate version and then he can run the generating of a single component/project in conformity with his own needs. He does not have to wait until all documentation is generated on the web and he even does not have to be connected to the internet (that is why it is called offline generating). Let us just add, that for simplicity reasons the output is in HTML format (not PHP like in the case of online generating).

3.7   Error log

After both offline and online generating the error log is created where whole process of the generating is noted. The log contains eventual errors and warnings together with messages about successful generating. Further, it shows synoptically the hierarchy of generating (in what order the generating proceeds, which component/project forces generating of which component and so on). Figure shows a sample error log.

Figure 4: Error log sample

4   Conclusion

In the mid-2006 the system was created, then the testing and bug fixing followed together with refining the specification and corresponding updating. Currently, 532 web pages is generated containing 208 pictures.