Automating Your Documentation Flow

 

In my last post, I mentioned that Agnisys is currently in the middle of a series of new webinars on how specification automation benefits many teams developing intellectual property (IP) blocks and system-on-chip (SoC) designs. When we first started supporting register and memory automation, we focused on generating register-transfer-level (RTL) design descriptions and Universal Verification Methodology (UVM) simulation testbench models from executable specifications. You generate these outputs as soon as the specifications are ready and re-generate them every time that the specifications are updated throughout the project.

This is of clear benefit to design and verification engineers. The designers never have to write any RTL code for registers or memories, or update code manually when requirements change. Similarly, the verification team developing the UVM testbench for the IP or SoC incorporates the generated models without having to develop them by hand, and automatically updates them when needed. When we added sequence automation to our product family, we helped the UVM effort even more. Over time, we’ve added design and verification generation for a wide range of standards-based IP as well as SoC-level interconnection of IP and custom blocks.

We’ve also expanded the project groups who directly benefit from our automation. We generate assertions that formal verification engineers use to find bugs and prove correctness of the RTL design. We also generate C/C++ code used by embedded programmers as a base for their drivers, firmware, and other software interacting closely with the hardware. This code runs in pre-silicon simulation, but it also runs on the actual SoC in the bring-up lab and can be adapted to develop the chip production tests run on automated test equipment (ATE). Here is a summary diagram we introduced a few months ago:

I’m sure you noticed immediately that I haven’t yet mentioned documentation or technical writers, and that’s my focus for the rest of this post as well as the topic for our most recent webinar. Keeping documentation in sync with the design is one of the biggest challenges on a large SoC project. Many bugs are due to different teams interpreting documents differently or working with inconsistent versions of the specification. For example, the system architects might modify some part of the spec and the RTL team implements it, but the verification team is not aware of the change until its simulation regression tests suddenly start failing.

Of course, this sort of inconsistency is exactly the sort of problem that specification automation is intended to prevent. We realized early on that documentation should also be generated from executable specifications whenever possible. We added several popular document formats such as Microsoft Word, PDF, and HTML to the outputs we generated for registers and memories. We have continued to generate documentation for all the types of specification automation that we support. In our view, documentation is every bit as important as any other output that our tools produce.

With our IDS NextGen (IDS-NG™) solution, a common front end and “dashboard” for all our users, there are several options for creating the executable specifications. For example, registers can be specified using a domain-specific editor within IDS-NG, imported from Microsoft Word or Excel, or read from a standard description such as SystemRDL. Similar options exist for sequences, interconnects, and the other parts of the design that we automate. In the simplest flow, the user simply selects the desired output format and pushes a button to generate the document.

There are many options within IDS-NG to customize the generated documentation in its various formats. For example, HTML can be produced in hierarchical or flattened format. For both HTML and PDF, the user can select font type, size, and color for any register attribute. Other customizable options include:

• Customizing templates, headers, and footers in the documentation
• Adding external items above or below specified portions of the documentation
• Controlling the generation of variant, signal, enum, and define tables
• Removing specified components from the generated documentation
• Combining tables for related registers
• Adding tables within register descriptions

Options are also available for other parts of the solution beyond registers. For example, each sequence is a set of steps that can be documented naturally with a flowchart, so automatic flowchart generation is available. Special views within the IDS-NG graphical user interface (GUI) show sequences, registers, hierarchy, and more. It is easy to navigate using these views. Hints are provided as the user specifies the design elements, while errors that affect the specification are detected and highlighted. IDS-NG also has a built-in integration with the Git version control system to make it easy to manage updates.

In summary, IDS-NG provides a common front end for capturing all executable specification information related to the IP or SoC and generating appropriate documentation. This documentation can be re-generated every time the specification changes, keeping all project teams in sync and providing the technical writers with content for their user manuals. To find out much more about how all this works, I invite you to go here and watch the recorded webinar. You can also view the complete list of webinars in the series and register to attend upcoming events live. Enjoy them!