vhdl-documentation.pdf

CESNET technical report number 5/2007

System for VHDL design documentation

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 1 . 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.

1 http://www.cesnet.cz/doc/techzpravy/2000-1/

3 The main concept

The source XML files are stored in CVS in a fixed hierarchy. The exact de-

scription 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 (con-

taining 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 conver-

sion is done by Perl. Let us note, that the original Techrep format 2 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 1 we can see

the sample of source 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 2.

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 3, we can see a sample of source code and resulting page.

2 http://www.cesnet.cz/doc/techzpravy/2000-1/

CESNET technical report number 5/2007

Figure 1: XML code and resulting web page

CESNET technical report number 5/2007

Figure 2: Example of resized pictures

CESNET technical report number 5/2007

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

CESNET technical report number 5/2007

Plik z chomika:

Inne pliki z tego folderu:

Inne foldery tego chomika: