Automatic Documentation Generation for RTL Design and Verification

Ask any hardware or software engineer working on a product, and they will tell you that writing documentation is a pain. Customers have high expectations for user manuals and reference guides, usually requiring a team of technical writers to satisfy their requirements. In order to meet time-to-market deadlines, documentation must occur in parallel with the later stages of product development. Every time that a user-visible feature changes, the documents must be updated. Even after product release, constant refresh is needed. Software adds new functionality with every release; hardware changes less frequently but chip variants are common and embedded software updates in system-on-chip (SoC) designs may add new features.

Software development teams have tried to tackle this challenge by developing tools that could automatically generate at least some parts of the documentation. The structure of the source code provides some guidance; this is generally augmented by including in the code special comments (sometimes called pragmas) that have meaning to generation tools. As a simple example, a “case” statement might define the available opcodes for a processor. A pragma might flag this statement as relevant for documentation and a tool might extract the description for each opcode from comments embedded in the source code.

There are many documentation generators available; Wikipedia lists more than twenty of them. All those listed are focused on programming languages such as C, Java, Perl, and Python. In fact, Wikipedia defines a documentation generator as “a programming tool that generates software documentation.” But what about hardware designers writing SystemVerilog code? Surely, they would like to be able to generate documentation for their chip designs as well. To find out if there is a solution, I turned to Cristian Amitroaie, CEO of AMIQ EDA. His company took the software notion of an Integrated Development Environment (IDE) into the hardware world with their Design and Verification Tools (DVT) Eclipse IDE. They also expanded the idea of code linting, also originally for programming languages, and developed their Verissimo SystemVerilog Testbench Linter.

It turns out that AMIQ EDA has also adopted the idea of automated software documentation generation and created a tool specifically for hardware design and verification engineers. Their Specador Documentation Generator handles source code written in SystemVerilog, Verilog-AMS, VHDL, and the e verification language. As I expected, it can document chip designs, useful both for chip-level products and for larger systems whose functionality is largely determined by the chips within. Specador also handles the verification constructs of e and SystemVerilog, so it can document testbenches as well. This is clearly valuable for IP providers who offer the verification environment as a product, but it is also useful to document testbenches for internal design blocks. New team members or future projects that reuse the code will benefit from high-quality documentation.

I have to say that Specador produces professional-looking results, with different fonts and styles, hyperlinks, and even generated diagrams. I asked Cristian to share some of the secret sauce of how this all works. As with the other AMIQ EDA products, the fact that they compile the source code is the key to their understanding of it. Some documentation generators just skim the code looking for pattern matches. Specador compiles the code, so it identifies elements such as functions, modules, classes, and ports without the need for special comments or pragmas. This saves a lot of time for the engineers and makes it possible to get reasonable documents with minimal setup effort.

Even if the code is poorly commented, the generated documentation is accurate and detailed.  It shows design and verification hierarchies, port and function tables, and more, all hyperlinked to simplify navigation. The documentation is also linked with the corresponding source code and remains up to date as the source code evolves. More advanced users can define “comment processors” that extract additional semantic information from comments.

As we have noted before, SystemVerilog is a particularly complex language, with many extensions to both traditional RTL syntax and software programming languages. Specador includes support for all the powerful features of SystemVerilog, including coverage, assertions, and object-oriented programming (OOP). This leads to deep knowledge of the design and testbench, enabling better documentation with specialized diagrams for block schematics, state machines, instance trees, inheritance trees, and more. These diagrams are smart; for example, a user can click on a class in an inheritance diagram and jump to the point in the manual where that class is documented or step down/up into the design hierarchy.

As with software documentation generators, Specador provides value throughout the project, and beyond. Whenever the code is changed to add functionality or fix a bug, documentation is simply re-generated. Design, testbench, and documents remain in sync. I’ll say the same thing about Specador that I did for DVT Eclipse IDE: it’s hard to imagine any team designing or verifying RTL without this product in their toolbox. Please join me in thanking Cristian for his insight and for developing tools useful every day on real-world hardware projects.

To learn more, visit https://dvteclipse.com/products/specador-documentation-generator.

Also Read

An Important Next Step for Portable Stimulus Adoption

With Great Power Comes Great Visuality

Renaming and Refactoring in HDL Code