Real-World Reuse: RTL Recycling

In the real world of electronic product design, time-to-market can have a large impact on success. To facilitate production speed, RTL from existing projects is often recycled for use in the new project. The danger of this approach is that recycling code that was never designed for reuse can actually lead to delayed projects. Time is lost understanding the existing code, establishing the quality of the design, and potentially modifying code to meet company standards.

This paper presents the theory that a method can be applied to recycling RTL code that in turn leads to a design that can be easily reused on a new project. By applying this method to the very real process of recycling RTL in the context of a new project, the resultant code actually has been designed for reuse. The method includes:

• Techniques for quickly finding and organizing required files in a directory full of data
• Methods for determining data integrity
• Effective use of RTL code checkers and design rules to establish code quality
• RTL code documentation techniques
• Efficient preparation for code reviews
• Applying version management processes
• Building a quick and inexpensive reuse repository to share designs

The reader of this paper can selectively employ any or all of these methods to efficiently establish an inexpensive reuse environment.
Finding Files

In order to recycle RTL code within the context of a new project, all the files required for successful simulation need to be located. As Figure 1 shows, the task is to separate and organize required files from all the files available.

 
Figure 1: Separating required files

Files can be categorized as:

• Design files: the actual RTL and supporting files that comprise the design. These files are critical for reuse.
• Support files: any documentation or script files that ease the use of the design. These files can be useful for the new project.
• Output files: any files created by design tools from the previous project. These files tend to not be useful for the new project and actually get in the way.

Look for one or more of the following items to help determine the complete set of design files:

• A makefile for building at least one configuration of the design
• A file list that captures the RTL files that comprise the design
• A script that builds a file list for the design
• A document listing the hierarchical composition of the code
• A version management repository
• The top level of the design to attempt to piece together the necessary structure

If none of the preceding files exist, try adding each RTL file to a new simulator project. This is a hit-and-miss process, but if the design can ultimately be compiled for simulation, all the required files exist.

During the process of finding valuable files, save them in a defined directory structure. For example, it is common to store files in a simple structure similar to the sample that Figure 2 shows.



Figure 2: Sample directory structure

Determining Data Integrity

Before reusing a design, the integrity of the data must be insured. At a minimum, there cannot be any missing files or files containing syntax errors. Additionally, the hierarchical composition of the design must be understood.

During the process of finding required files, it might be determined that some files are missing. Missing files can be categorized as:

• Includes or packages: typically reused design definitions that are referenced to another location.
• Referenced instances: either inserted by downstream tools or direct, technology-specific instances.
• Missing blocks: stubbed-in design blocks that have yet to be coded.

In order to recycle a design, all missing files must be either located and made part of the new project or created.

Use any tool that compiles RTL to determine syntax or semantic errors in the code. Errors can be caused by:

• Missing files: cause many errors to occur, especially missing include or package files.
• Tool settings: some tools require the specification of a particular dialect of Verilog or VHDL. If these settings do not match the dialect of the recycled RTL, many construct errors will occur.
• Actual errors: incorrect syntax or semantic use of RTL constructs.

Actual syntax errors are a sure sign that the design has never been simulated and it could take significant effort to ensure that this design is worth recycling.
 
Many tools exist that allow you to see the hierarchical relationship of the design after the files are part of a project. Use one of these tools to understand the structural composition of the design.

Visually inspect the testbench for the recycled design. If the answer is “no” to any of the following questions, there is significant work involved in recycling this design. Does the testbench:

• Contain a rich set of tests?
• Define assertions?
• Use modern verification structure (such as scoreboards and monitors)?
• Specify code coverage points?

As a final check, use a simulator to compile and load the design. If you do not get any errors, the design integrity is assured. However, the quality of the testbench environment determines the verification of correct function.

Using Code Checkers

Code checkers (or linters) apply a set of RTL coding rules to recycled code or code under development. These rules often represent collective knowledge as to how to write quality RTL code. Running a design checker facilitates getting an estimate as to the quality of the code based on the number and types of violations that occur. Some violations are easy to fix and have no impact to other parts of the code. For example, incomplete sensitivity lists or not having a default case defined for a finite state machine. Other violations take considerable time to fix. For example, eliminating combinational feedback loops requires re-writing significant code.

Assess which violations must be fixed in order to recycle this code in the new project. Estimate the time it will take to fix the violations and adjust scheduling accordingly. Be prepared to defend violations that remain in the code to the design team.

Some code checkers also have the ability to assign a weighted score to each coding rule. This allows the tool to present an overall quality metric for the code based on deducting violations from a total possible score. Use this capability to objectively measure code quality and to present findings to the team.

It is also good design practice to use code checkers to ensure RTL quality during the development of any new code surrounding the recycled code. It is efficient to catch coding violations as the code is written to minimize design errors in downstream tools (such as simulation, synthesis, or place and route).

Documenting Code

Often, the code to be recycled was written in a hurry. One of the first elements omitted when code is quickly written is documentation. But, documentation is key to understanding recycled code. Look for the following items to help understand code:

• Headers: often a template that shows a revision history and who made changes. Use this history to understand variants and configurations of the design as well as design decisions. If no header exists, consider adding one to each source file for use in the new project.
• Comments: look for comments around key modules and processes in order to understand the details of the implementation. Important signals and variables are typically commented as well. If comments are sparse, consider adding them to the code as you learn about fundamental elements of the design. Copy valuable comment descriptions to a design document, if appropriate.
• Diagrams: often designers of the original code employ tools that generate visualizations of the RTL. Typically, this takes the form of structural block diagrams. If a top-level diagram does not exist, consider creating one for use in the new project.
• Associated documents: any requirements, specification, or project documents that exist for the design are very useful and should be stored and linked to the design in the context of the overall new project.

Figure 3 provides an example of a top-level repository page and the links to the design review websites for each design.

Preparing for Design Reviews

The next step for recycling code is to hold a design review within the team. Design reviews are also common at particular milestones of any new project. One method to help automate preparing for design reviews is to create a stand-alone website. At the top level, enter a brief design description and some up-to-date notes on the design status. Then create (or use a tool to generate) a web page for the design and link in the following:

• The RTL source, including the testbench (leaving behind any source that is not part of the design).
• Any graphical representations of the source code.
• Project documents and scripts used to automate tool runs.
• Supporting design files (like C files, memory content files, processor software, etc.).
• Useful reports (such as code quality and code checker reports).

Using a HTML browser as a means to communicate allows team members around the world to access information without touching the actual design data and without requiring any tool other than a browser.

Take notes during the design review and link those into the website in order to capture a review history.
Applying Version Management

Before the recycled code can be used on a new project, it needs to be plugged into an existing version management system for the project. If a system is not in place, strong consideration should be given to using version management on the new project.

Designs are typically created within a team that could be geographically dispersed, all working on different blocks of the design. These design descriptions go through several iterations. However, at some point, someone on the team will want to build the design into the whole system. If the team does not employ version management, odds are that at least one of the files has errors or is missing, meaning the design will fail.

There are many free and commercial tools to help manage versions of the RTL code. But version management is more of an education and discipline concept. The entire team needs to be well versed in the concepts of labeling files, checking in and out code from a central location, and building the design successfully for testing. If a version management methodology is not valued or it is considered hard to use, teams can find themselves with members that do not have the discipline to use the system. A good method to combat this syndrome is to:

• Pick a simple tool like RCS or CVS and learn the basics.
• Set up a short training class for the team, covering the concepts and methodology.
• Discuss how the team would like to interact with the version management system. The key is to enable a system that is easy to use.
• Then integrate a version management tool into the code creation process.

Version management is not just valuable for making sure the wrong file does not find its way into the design flow. Consider investing in version management:

• To enable backing out of changes made to the system. If a team member checks in some blocks, and all of a sudden the system does not simulate correctly, that code can easily be backed out of the build.
• To keep a history of design changes. Iterations and variants can be labeled and added to the design build easily.
• To archive the design. All the files required to build the complete design can be tracked with a version management system. This means archiving stand-alone versions of a design is a simple task.

There is no greater waste of time than creating a design that already exists within a team or corporation. To complete the RTL recycling flow, create a simple web page that centrally houses designs that everyone can share, including the design that was just recycled. A simple reuse repository can be built and maintained by creating a web page that contains:

• A row of information for each design, including: a short description, parameters describing the design, and a date for design completion.
• For each design, a link to the website used for the design reviews. This website acts as the documentation for the design.
• For each design, a link to the well-organized source files for downloading.
• A running history of what designs were added and when.

Figure 3 provides an example of a top-level repository page and the links to the design review websites for each design.



Figure 3: Sample reuse repository

Conclusion

In the real world, designers have always recycled code in order to jumpstart a new project and to save time. By following the recycling flow presented in this paper, a design for reuse flow is actually implemented for the recycled code and for any new project, as Figure 4 shows.



Figure 4: The recycling flow actually implements a design for reuse flow