Better Automatic Generation of Documentation from RTL Code

One technical topic I always find intriguing is the availability of links between documentation and chip design. It used to be simple: there weren’t any. Architects wrote a specification (spec) in text, in Word if they had PCs, or using “troff” or a similar format if they were limited to Unix platforms. Then the hardware designers started drawing schematics or writing RTL code, and the programmers did their thing. Verification and validation were all about making sure everything worked together.

Whenever the specification changed, manual updates to the hardware and software were required. When implementation issues caused the design to differ from the original intent, the impact was rarely reflected back in the spec. Thus, when it came time to produce documentation for the end user, it was a lot of manual work to combine bits of the spec, update to reflect the actual design, and add explanatory material for the target audience.

These days, we have links galore. There are many ways to generate hardware and software code from various specification and documentation formats, plus methods to generate documentation from source code. The former is not a new idea. I remember working on a new processor design around 1988-1989 in which the details of the instruction set changed numerous times. I wrote an “awk” script to automatically generate the Verilog RTL design for the instruction decoder based on a tabular representation of the opcodes and their meanings.

These days, there are lot of pieces in a typical chip that can be generated from various specification formats, such as registers from IP-XACT or SystemRDL and state machines from transition tables. We’re starting to see generative AI spit out even larger chunks of the design, essentially based on natural language specifications in the form of chats. Being able to regenerate RTL code whenever a specification changes saves a great deal of time of effort over the course of a chip project.

Generating documentation from code is also not a new idea. Solutions in this space started on the software side, with tools such as Doxygen. The idea is that certain aspects of the documentation can be generated automatically from the code, with pragmas or some other in-line mechanism available for programmers to control the generation and add content. Numerous options for document generation are now available, with AI-based techniques quickly gaining acceptance. Being able to regenerate documentation every time the source code changes also saves a lot of time and eliminates a lot of manual effort.

From what I can gather, documentation generation from code is very common in the software world. However, I’ve been surprised by how few hardware projects embrace this approach in a big way.  I often hear designers and verification engineers complain that languages such as SystemVerilog are not as well supported by shareware documentation tools. They also say that they don’t have the level of control needed to get the quality of results their end users demand.

AMIQ EDA has a commercial product, Specador Documentation Generator, focused on hardware design and verification code. I figured that there must be some good reasons why their users chose this solution over free utilities, so I chatted with CEO Cristian Amitroaie. The first thing he said was that Specador was created with hardware engineers in mind. It supports source code written in SystemVerilog, Verilog, VHDL, the e language, and more. It covers the RTL design plus the verification testbench, components, models, and tests. It generates both PDF and HTML output.

To me, the most impressive aspect of Specador is that it leverages all the language knowledge available in the AMIQ EDA Design and Verification Tools (DVT) suite. Their front end compiles all the design and verification code and builds a flexible internal model. Users of the integrated development environment DVT IDE can easily browse, edit, and understand the code, and even query the model with AI Assistant.

Understanding the design means, for example, that users can generate design hierarchies, schematics, and state machine diagrams. Since the DVT tools also understand the Universal Verification Methodology (UVM), users can generate class or component diagrams including TLM connections, cross-linked class inheritance trees, and other useful forms of documentation for the testbench. My choice of the word “documentation” here is deliberate, because many of the design and verification diagrams that users might generate within the IDE are also useful as part of user manuals and other chip documentation.

Cristian stressed that Specador (like all their products) uses accurate language parsers to compile the code so that it understands the project structure. Users can employ it to document design or verification environments, even when comments are not present to provide additional context. Of course, Specador also supports the ability to use comments to format documentation and to add content that can’t be inferred from the source code.

I asked Cristian what’s new in Specador, and he mentioned that AMIQ EDA keeps implementing new features and enhancements based on customer feedback. For example, they recently added the ability to quickly preview the documentation directly in the IDE, the ability to apply custom filters when generating schematic or FSM diagrams, the ability to work with Markdown and reStructuredText markup languages, and last but not least the ability to generate documentation using their AI Assistant.

Specador makes it possible for design and verification engineers to easily create and maintain proper and well-organized documentation. Users can control what documentation they create by filtering or selecting elements in the design and testbench. They can quickly embed or link to external documentation. Specador integrates easily into existing development flows, allowing design and verification groups to automate the documentation process.

Above all, Specador keeps the generated documentation in sync with the source code, saving a great deal of maintenance time and effort as the code evolves. I thank Cristian for his time, and recommend looking at the product information, exploring the documentation generated for the Ibex embedded 32-bit RISC-V CPU core, and reading a post on real-world user experience to learn more.

Also Read:

2025 Outlook with Cristian Amitroaie, Founder and CEO of AMIQ EDA

Adding an AI Assistant to a Hardware Language IDE

Writing Better Code More Quickly with an IDE and Linting

 

 

Share this post via:

• 
• 
• 
•