Creating and Linting a Design in ALINT

Introduction

ALINT is a design rule checking (linting) tool for VHDL, Verilog, and mixed-language designs that identifies critical HDL code issues early in the ASIC and FPGA design flow. The tool points out coding style, functional and structural problems in Verilog®, VHDL, and mixed-language designs, and prevents them from spreading into the downstream stages of your design flow. This Quick Start Guide gives a brief conceptual overview of the ALINT design check flow by guiding you through:

Design Setup: source files, vendor libraries, clocks and resets, top-level.
Linting Check: identify goals and create flow, run flow.
Results Analysis: browse and filter, generate reports, reduce reported issues.

These three topics are all you need to complete design linting.

Starting the Tool

You may use the following program scripts [1] located in the main installation directory of ALINT to start the tool in either GUI or Batch mode:

runalint – GUI
runalintcon – Batch (interactive)

Assuming that you have a valid license, you should see the default ALINT environment (Figure 1) after executing the runalint script.

Figure 1: ALINT Environment (Default Perspective)

Adding Source Files

You will need to create a Workspace and a Design, which will allow grouping and managing collections of individual files [2]. To add your project files, run the New Design Creation Wizard by selecting File | New | Design... (Figure 2) and:

Type a new design name
Select the location
Click Finish button

Figure 2: New Design Creation Wizard

Right-click on the newly created design and select Add | New File… (Figure 3) to add all of your project files.

Figure 3: Adding Project Files to ALINT

Unnecessary files can be removed by selecting a file or group of files and then Delete.

NOTE: By default the files are removed from the current Design but not from the disk.

Once the design files are added, it is time to set up project-specific settings: attach precompiled FPGA vendor libraries (if necessary), specify clocks and resets, select top-level(s), and define any exclusions for files, instances, or design units that should be skipped from the design analysis.

Attaching Vendor Libraries

If your project uses some components from a vendor library (e.g. unisim from Xilinx) then you will have to attach these libraries to the list of the design libraries in ALINT so that the tool can compile your project. The list of currently attached libraries can be observed in the Library Manager. Each library in the Library Manager can be attached as global or local. In Figure 4, libraries listed under the library.cfg node are global and thus are visible in all designs, whereas quick_start is local, and only visible within the currently active design.

Figure 4: Library Manager

Click here for the detailed instructions on how to deal with the vendor libraries. The bottom line is that you can either download the pre-compiled libraries from www.aldec.com, or compile them from the source files by yourself. Once a library is attached, it appears in the Library Manager, and its contents can be expanded by clicking on the triangle next to the library icon.

NOTE: The components from the FPGA/ASIC vendor libraries typically do not have to be checked and therefore linting has to be disabled when a vendor library is getting compiled by a user from the source files. Once a library is visible in the Library Manager, the engine recognizes its contents and automatically substitutes all library primitives with the equivalent models that are essential for the advanced chip-level checks (click here for details on native support for Xilinx® and Altera® vendor library primitives).

Specifying Clock and Reset Signals

Unless there are some internally generated clock or reset signals in your design, the tool will detect all clock and reset lines automatically. If you do not have any internally generated clocks and/or resets you may skip this section and proceed to the next step. Please note that auto-detected clocks and resets are reported in the Console window during the elaboration-time linting, which is the second and final phase of a design linting session:

# ALINT: Info: ...Detected clock signals: bjack.GEN_CLK, bjack.SYS_CLK.
# ALINT: Info: ...Detected reset signals: bjack.GEN_RES, bjack.START.

In the case when a non-existing clock or reset is specified, the tool reports that it cannot be found and attempts to find clocks or resets automatically. In the case when there is some internal clock generator in your design (e.g. PLL with several clock outputs), the auto-detection may not be possible and you must specify clock(s) manually. In order to do that, go to your current design Properties as shown in Figure 5 and edit the list of clock signals.

Figure 5: The List of Clocks in Your Design

If you need to specify reset signals manually, right-click on the design in the Design Manager and then go to Properties | Linting | Entries | Global Reset Signals and edit the list of signals (specify hierarchical names).

NOTE: Every clock in your design infers at least one separate clock domain – essential source of information for rules that are being checked for the potential functional malfunctions due to clock domain crossing datapaths. Such rules are based on analysis of the signals that travel across the different clock domains and are also known as CDC rules. If two or more clock lines in your design are synchronized [3] then you must mark them as belonging to the same domain to enable accurate CDC-related checks. In order to mark clocks as synchronized, you must use the alint_gclkjoin switch. Go to Preferences | Linting | General and modify the Additional options for ‘alint’ edit box:

#CLK_A and CLK_B are joined (marked as synchronized – 1 clock domain inference) 
-alint_gclkjoin top.cgen.CLK_A top.cgen.CLK_B

#CLK_A, CLK_B, and CLK_C are joined (multiple –alint_gclkjoin switches)
-alint_gclkjoin top.cgen.CLK_A top.cgen.CLK_B -alint_gclkjoin top.cgen.CLK_B top.cgen.CLK_C

The design is ready for the linting analysis once the source files are added, vendor libraries are attached, and clocks/resets are specified.

Linting Check

In this section you will learn how to analyze your design with ALINT. Before proceeding to the actual design analysis process, please note that there are two possible approaches/methodologies:

Traditional
Phase-Based Linting (PBL)

In this application note, we are going to use the PBL methodology because it automatically resolves two common problems with the traditional approach:

High number of violations reported per session (natural occurrence when designs are checked against many rules)
A high level of “noise” caused by false or irrelevant violations

(Click here for detailed description of PBL and its benefits over traditional linting). We are going to use one of the predefined flow templates that allow you to start analyzing your design efficiently a few seconds after you are done with the tool installation and initial design setup.

Creating Linting Flow

Select File | New | Flow… to start the New Flow Creation Wizard. Type in your flow name, set flow type to STARC_VHDL - Essentials [4] predefined template, and check the Attach new flow to the design option as displayed in Figure 6.

Figure 6: New Flow Creation Wizard Settings

Once you are done with the new flow settings, click Finish to attach the flow to your design. When a flow is attached, its phases are displayed in the Flow Manager window and the flow name appears next to the design name in the Design Manager.

Running the Flow

The linting flow is an iterative process or set of phases that must be executed and completed sequentially (refer to Figure 7 for a generic flow diagram). Every phase addresses a certain set of design issues and also has the pass criteria – quality requirements, that should be satisfied before the next stage becomes available.

Figure 7: Generic Linting Flow

There are two types of pass criteria:

Design Quality in the current phase – an integral number that is calculated based on the ratio of violated and non-violated rule weights (see details in User’s Guide | GUI Reference | Linting Windows | Violation Viewer | Design Quality Report Generation Wizard.
Critical Rules that must never be violated (selection from the rules used at a current phase).

Figure 8: Flow Manager

To run a flow:

Click the Run button in the Flow Manager (Figure 8) to run the current flow
Flow execution stops at a phase that requires your attention
Fix violation detected at this phase and repeat action #1

NOTE: If your design is VHDL or mixed-language [5], you will be asked for a top-level(s) design unit setting (Figure 9) during the first run of a flow. Select the Save choice for active design option to prevent the same inquiry from appearing every time you re-run the flow (this setting can be reset in Design Properties | Linting | General | Top-level design unit if necessary).

Figure 9: Top-Level Inquiry

Current phase and whole flow execution status is indicated both in the Flow Manager (check the status icons associated with every phase) and Console window (look for messages prefixed with ALINT_FLOW_MANAGER).

Results Analysis

Each phase execution results are stored in a separate Violation Database (.avdb) file. If the currently executed phase requires your attention, the flow execution stops and the resulting database is automatically [6] loaded into the Violation Viewer. This section explains the basic capabilities of the Violation Viewer, a key tool for analysis of design rule violations that were detected during a linting session.

Grouping by Origin

The Violation Viewer provides several predefined viewpoints/tabs (Figure 10) that allow accessing rule violations from different angles, depending on their origin, for example:

Summary – numeric data about violations detected per rule, source file, design unit, etc.
Sources – violations grouped by source files
Design Units – violations grouped by design units (entity, architecture, module)
Instances – violations grouped by instances
Rules – violations grouped by rule IDs
Rule Levels – violations grouped by rule criticality (Rule, Recommendation 1—3, Suggestion)

Figure 10: Violation Viewer

NOTE: Violation Database stores information only about those design units and instances that have some rule violations associated with them. In other words, you may not be able to see the complete list of design units under the Design Units tab of the Violation Viewer, or the Instances tab may not be available at all in case if there no violations associated with any instance (you did not run elaboration-time linting for example).

Filtering

You can narrow down the list of detected issues by using the Filters tool available in the Violation Viewer. The following filtering criteria are set in the sample (Figure 11): display violations detected only for design units that start with “bin2bcd” and have importance level of Recommendation 1 or higher (Rule).

Figure 11: Filters in the Violation Viewer

NOTE: Filter(s) activation affects the current view only but the database itself is not altered; filters can be modified or reset at any time later.

Cross-Probing

When you select any rule in the Violation Viewer, the appropriate violation message(s) is (are) listed in the messaging pane. Cross-probing is simple: double-clicking on a violation message brings you directly to the source code section/context that has caused this violation. You may find it useful to undock the Violation Viewer and enable the Stay on Top option in the upper-right corner of this particular window. This way, both the violations and the source code will always stay on top as shown in Figure 12.

Figure 12: Cross-Probing to a Source Code

NOTE: Quick context-dependent rule reference is always available in the Rule Description Viewer (updates once you select different rule).

Exporting to Other Formats

Either the current (filtered) view or the whole database can be exported to other formats such as .html, .csv, or text.

Figure 13: Export to .html Example

Use the drop-down Export button at the Violation Viewer toolbar to generate violation report in another format ( – .txt, – .csv, – .html). Resulting report appearance depends on currently selected viewpoint (refer to Figure 13 for example of .html report generated from the Rules tab).

Managing Exclusions

Your design may include some block or context for which you will need to disable certain rules. For example, you may have an RTL model as well as your own implementation of a block in the form of EDIF netlist (in such a case, the RTL model is valid for simulation purposes only, and does not need to be checked against synthesis rules). There could be a number of other reasons why one may want to prevent certain rules from being checked in certain contexts, and ALINT provides an exclusion file (.alintexclusions) and an Exclusions Editor – a unified mechanism for rule exclusion management. You can create a set of exclusions upfront and then associate it with your design. But the most convenient way is to specify exclusions on-the-go, directly from the Violation Viewer while analyzing your violations. Before proceeding with the practical part, let’s quickly go through the basic terms. There are two types of nodes in the Violation Viewer – container and leaf (Figure 14).

Figure 14: Different Node Types in the Violation Viewer

Container nodes have one or more sub-node, whereas leaf nodes do not have any. Right-click on any node to see the context-dependent actions that depend on a node type:

Container node – batch disabling for all or only violated rules for all source files, design units, or instances that reside within the currently selected node.
Leaf node – individual disabling for particular design units that reside within the currently selected leaf or for the source file itself.

Examples based on the fragment of the violation database is displayed in Figure 14:

Right-click on blackjack.v and select Disable rule(s) for | Design Units | Violated Rules. As a result, RMM.VLOG.5.2.9.1, STARC_VLOG.1.1.1.3, STARC_VLOG.1.1.3.3, and all other rules detected for blackjack.v will be disabled for all design units described in blackjack.v.
Right-click on blackjack.v under the RMM.VLOG.5.2.9.1 node and select the Disable rule(s) for option. Two independent choices are available here for RMM.VLOG.5.2.9.1: the rule can be disabled for “blackjack.v” (the source file) or “MIXED_BJACK” (design unit described in the source file).

Figure 15: Exclusion Editor with Sample Set Loaded

At the practical side, you can create a custom set of exclusions by using File | New | Exclusions File and associate it with your design in Design Properties | Linting | General | Exclusions File. From now on, all exclusions you specify while analyzing violations will be recorded to this set. You can open and edit your current exclusions set at any time in the dedicated Exclusions Editor (Figure 15) by double-clicking the appropriate .alintexclusions file in the File Browser [7] or using the File | Open | File… menu.

Conclusion

Our quick look into basic capabilities of ALINT (as far as the GUI is concerned) is over. Please note that this document does not cover topics such as custom policy creation and batch mode commands that are important if you prefer using shell scripts rather than the GUI environment, and rely on a full custom policy rather than on predefined flows. As you can see, it takes minutes to load your design and run a check against one of the preset flows. Violations detected during the design linting sessions are a different story, and it is hard to predict how much time you are going to need to analyze and fix them (it all depends on your design size, complexity, and code quality).

References

[1] These scripts are available under the tool installation directory and they have different extensions depending on the OS (.bat – Windows, .sh – Linux).
[2] Please note that workspace and design creation are optional, and all linting operations can be performed using commands and/or script files in the current working directory.
[3] Synchronized clocks have constant frequency and phase relationship.
[4] Predefined flows with the STARC qualifier are based on the rules from RTL Design Guidelines that were put together by Semiconductor Technology Academic Research Center (STARC) in Japan. STARC is a consortium of major semiconductor companies with many years of ASIC and FPGA design experience, its contributors list includes but is not limited to Fujitsu, Panasonic, Sharp, Sony, and Toshiba.
[5] For Verilog designs, the top-level(s) is detected automatically.
[6] You can manually load violations detected during any phase execution by right-clicking on the phase and selecting View Phase Results.
[7] Hint: you can have exclusions set added to your design so that it appears in the Design Manager and can be quickly accessed with a double-click. Right-click your design and use Add | Existing File… to add an .alintexclusions file.