Many of today's large, complex designs can contain thousands of lines of Verilog or VHDL code. Quite often, teams of engineers—with some members possibly situated in disparate locations worldwide—will work on these designs. But a simple mistake in just one line of code can cause the team to iterate through several steps in the design process.
Therefore, it's crucial that team members check the code against coding standards and best practices while they write it. It's also important to follow a common methodology for checking all source code to ensure that no nasty surprises crop up when running downstream tools.
Checking RTL Designs
Register-transfer-level (RTL) design checkers supply the means for automating the enforcement of coding standards and best practices that have been gathered by a team over years of experience. For example, the team might want to check the design for clock and reset issues, for code that could affect synthesis quality (like combinational feedback), or for RTL code responsible for downstream issues in the past (like clock-domain crossings).
Often, a single person maps this knowledge into design-checker rules for the whole team or corporation to share. This ensures that all members of the team are checking their designs against the same set of rules. Any reports made—delivered within the team or to management—after running these checks are then based on a common foundation of rules. If a new rule is added, or an existing rule is modified, the team or corporation needs to know about this. Otherwise, new and conflicting violations could appear from one day to the next.
In general, using any tool within a collaborative environment requires some planning and tool setup. Checking designs effectively within a team, or across several multidisciplinary teams for that matter, implies that you should consider taking a few key steps (Fig. 1) .
Developing A Rule Strategy And Creating Rules
Most design checkers have built-in rules. Some of these tools come with pre-configured rule sets, like the Reuse Methodology Manual (RMM). A typical approach to establishing rules follows five steps:
- Run the design checker on HDL source file(s) that are familiar to you using a pre-configured rule set that comes with the tool.
- Examine the results.
- Create your own rule set.
- Place any of the rules that match your needs from the pre-configured rule set into yours.
- Start adjusting the individual rules to match your rules.
Designers should keep several key issues in mind when developing a comprehensive rule strategy.
Adding Rules: If you're lucky, your team or corporation maintains a written set of rules that should be checked. The good news: this document comprises the collective wisdom of people on your team. The bad news: many companies mandate that their designers read this document and remember its content as they write code.
Design checkers allow you to add your own rules to match this document. So the updated checks always exist, which helps you to run them automatically without having to remember them in all of their variations.
Next, add your own rules to those found in the pre-configured rules (those rules that matched your needs). But before you do that, establish a strategy for organizing and naming your rule sets. This approach has several benefits:
- Grouping rules into rule sets lets you establish policies that selectively enable or disable particular groups of rules. A policy is simply a method to point to one or more rule sets.
- The results from running the rules will map to the rule set category, helping the design team to understand the type of rule violation. For example, if you have a Reuse rule set and a Synthesis rule set, every designer will see if the violation is associated with a certain type of check.
- Establishing a well-named hierarchy of rule sets lets you quickly add rules in the appropriate category, preventing the addition of a redundant rule (Fig. 2) .
- A well-named rule also provides another valuable clue for the design team as to what is specifically wrong with the code.
Number Of Rules: In general, designers or teams don't like to be inundated with violations. Carefully consider how many rules you should develop, and what level of checking you want to enforce for the team. The best approach is to establish an important set of rules (that are known, say, to cause downstream errors), which everyone must run. Then, carefully consider adding "lesser" violations.
For example, if you have a rule stating that every line of code must be 60 characters long or less, the designer will likely see hundreds of errors when running that rule on existing code. Do you really want this rule in your rule set?
Rule Severity: Another aspect to consider is the severity of each rule. You will probably have a smaller set of rules that, if violated, cause downstream bugs. These rules could benefit from the use of an Error flag. Then, you can carefully decide which level of severity to assign to lesser violations, such as warnings or notes. Clearly labeling rules with suitable severity levels helps you tackle the most urgent violations first.
Violation Clues: Typically, you want to provide as much information to the design team as possible about the rule violation. This lets the designer quickly change the code to avoid the violation. The rule set and rule names that you supply significantly help in this effort, as do the messages issued by the design-checking tool about the violation. Another way to help your teammates and other designers is to create additional information for each rule. Figure 3 shows how to use rule parameters and descriptions to provide the design team with more information.
Some tools enable you to specify your own violation message or include additional messages for the violation. Also, a few tools support linking to added documentation about the rule that will help the team understand how to correct the violation. Typically, this additional documentation is the most beneficial if several examples are included. Make sure you take advantage of all violation clues that a tool can offer.
Rule Quality: Aside from giving as much information as possible about a violation to the designers or teams, consider the quality of your rules:
- Does the rule actually match the intent of the rule from your document? Did you create a test case for this rule to ensure this match?
- Do two rules clash? For example, a designer may inadvertently create two naming rules that check for conflicting items, such as "all ports must start with P_" and "all port names must use lowercase letters."
- Do you have a redundant rule? This means that the designer sees twice as many violations (or two violations for one line of code).
After you create your rules and rule sets, you want all designers to use this information when they run the design checker. Most design checkers store this information in files or directories.
One approach to sharing rules within a team is to set up a central server for storing the rules so that every authorized user can access them, and then copy your rules data to that machine. It's a good practice to change the access rights to these files to read-only. Therefore, someone won't accidentally change the data, affecting everyone on the team. Typically, design checkers then will permit you to set an environment variable or fill in a path name from within the tool to point to the shared rules information.
What if designers want to work from home? If the rules reside on a central server that team members can securely access from outside, then every designer is already set up to work remotely. But that's not always the case. If the server isn't remotely accessible for security or other reasons, the designer will have to take a snapshot of the rules before leaving and then point the tool to a local copy. When the designers return, it's a good practice to switch back to the central rules and run an analysis on their code, just in case the central rules have changed.
Managing Design Checking
At the beginning of the project, consider how to manage design checking. There are several common considerations:
Design Reviews: Most teams establish milestones that require design reviews within the team. In terms of design checking:
- You might establish a specific level of acceptable violations before reviews take place. Ideally, there should be no errors, and perhaps a threshold is set to determine an acceptable level of warnings and notes.
- You might decide that all of the rules must be run on the design before a review takes place.
- You can decide on a process to review existing violations and to help designers fix tricky violations.
Issuing Reports: A team may decide to create and circulate additional reports on an ongoing basis during a project. Also, during a project, you might want to send a particular piece of information to someone else on the team. The team should decide what reports are required, their format, and their content.
Version Management: Teams using version management must establish the acceptable levels of violations when checking in portions of the design. In addition, some teams might run a different set of rules on the whole design, versus rules run by designers on their portion of the design. The team might also decide to place the central rule sets under version management.
Tool Versions: Establish a procedure for the team when using a newer version of the design checker:
- You might want to archive your rules, any reports that you collected, and source files before switching versions. Most tools are upward-compatible, but caution never hurts.
- Create a report for all of the rules in your rule sets. New releases of the tool might contain rule changes. Saving your rule report will point out any of these differences.
- You also might want to establish rules about which version of the tool must be used for a particular project. For example, you might want to stay on one version of the tool for the duration of an ongoing project.
Tracking Rule Changes
After the team starts using the design checker and the rules on a daily basis, several situations may occur:
- An existing rule isn't checking the code as expected. In this case, you would need to examine the code and the rule, and then either adjust the rule or tell the designers the bad news that their code needs to be fixed. You might also need to adjust your test case for this rule. In some cases, you might need to report this situation to your tool vendor.
- The designers have found a new check that they think needs to be added. In this case, a new rule must be created and added to the rule set.
- The designers might complain that the rule should be eliminated. Here, the rule would either be turned off via the tool or removed from the rule set.
In all of these situations, a team typically sets up a simple process depicted in Figure 4:
- Agreement: Establishes a method for the team to agree on a change.
- Notification: Informs all those affected that the rule set is changing, and when.
- Update: Tells all those affected that the new rule set is now in the central location and what changes they should expect when they run the tool. This update usually includes a reason why the changes were made.
You might want to save a rule report that captures all of the rule data and retain the rule sets in a different location before making any changes. This lets you revert back to the original rules in case the team decides that the changes weren't a good idea after all. The rule report provides a means of manually reconstructing rule sets in case you accidentally delete them. This implies that you should store the rule report in a different location than the rule sets.
Ensuring Code Accuracy
As designs get larger and more complex, it has become increasingly common for designers to work in teams, often remotely located in different time zones worldwide. Using design checkers helps your team trap potential problems while the designers write their code. Moreover, establishing a methodology for using design checkers within the team provides every designer with consistent access to the corporate RTL coding knowledge base, ensuring RTL code accuracy in team-based designs.