Migrating ALINT Designs and Settings to ALINT-PRO

Introduction

Aldec ALINT-PRO replaces ALINT, Aldec's legacy linting solution, and pushes the verification capabilities for FPGA and ASIC designs to a new level. While preserving the most useful ALINT features and similar design rule checks, ALINT-PRO offers a greatly improved usability, advanced debugging capabilities, higher quality, and better performance. Support of advanced clock domain crossing (CDC) verification methods, reading design constraints (SDC and Aldec-specific), schematic visualization of the synthesized netlist, clock/reset networks and the CDCs are the major new features introduced in ALINT-PRO.

Existing ALINT users are advised to migrate to ALINT-PRO. Most of the migration steps can be performed automatically. This application note summarizes the key steps necessary to migrate the projects created for analysis using ALINT, including project structure, preference settings, linting policies and exclusions (waivers).

Migration Overview

ALINT workspaces and designs can be converted to matching ALINT-PRO formats using a GUI-based wizard or TCL scripting commands for conversion.

The source ALINT files (workspace, design, policies, exclusions) are not modified during the conversion. New ALINT-PRO workspace and project files are created in the same directory with the initial sources.

Policy and exclusion files are now part of the project settings in ALINT-PRO and do not require separate files.

Be aware that you need to explicitly allow overwriting ALINT-PRO project during conversion if it already exists on the disk.

How to Convert ALINT Workspace

Let us consider the conversion process on a very simple ALINT workspace example, having a single project (Fig. 1), a configured custom policy (Fig. 2-3) and an exclusions file (Fig. 2, 4), as well as manually specified global clocks (Fig. 2):

Figure 1. Workspace Structure

Figure 2. Design Properties

Figure 3. Design Policy

Figure 4. Design Exclusions

Run the workspace migration by following the guideline below:

1. Open ALINT-PRO and select Tools | Convert | ALINT Workspace to open the conversion wizard.

2. Select the workspace name and location:

   

   Figure 5. First Step of the Workspace Conversion Wizard

3. Setup proper values to checkboxes:

   • Overwrite existing files - if the output workspace or project files with corresponding names already exist on disk, check this option to overwrite the existing files.

   • Use 'alint' workspace configuration - If the ALINT workspace has a custom active configuration, it will be replaced with the 'alint' configuration settings.

     ALINT workspaces have a pre-defined configuration 'alint' and possibly several custom configurations, like 'debug' or 'release'. When this checkbox is set, the conversion will use the 'alint' configuration, otherwise the currently active configuration will be taken as source of settings.

     The configurations were important in ALINT due to the common project format with the Aldec Riviera-PRO simulator, where the users expected to have a similar project structure, but applied different set of settings for linting and for simulation. ALINT-PRO no longer has a concept similar to ALINT configurations, as it no longer shares numerous identical functions with Riviera-PRO.

   • Delete ALINT files after conversion - after successful conversion, the initial ALINT files (workspace, design, policy, etc.) and generated files (library, .avdb, etc.) will be deleted;

4. Specify directories to be searched for the referenced rulesets and policies. For a given custom policy, the files containing inherited rulesets/polices are searched within the workspace and project directories, and in the directories defined in the Policy directories/Ruleset directories properties of the ALINT design. Skip this step when there are no additional search paths required.

   

   Figure 6. Second Step of the Workspace Conversion Wizard

5. Review the extracted structure of the workspace and click Finish to complete the conversion. A missing file is indicated with a red color. In such a case, reviewing the specified search directories might be necessary.

   

   Figure 7. Third Step of the Workspace Conversion Wizard

Double clicking the ALINT workspace file (*.rwsp) in the ALINT-PRO File Browser also starts the same conversion wizard with the original workspace file already selected.

When scripting commands are preferred over GUI, the following conversion command handles the migration of ALINT workspaces:

convert.alint.workspace <old_workspace_file> [-force] [-alint_cfg] [-cleanup] [-path <path> ...] [-f <list_file>]

Refer to product documentation (Help | Command Reference) for details on the possible command arguments.

Below is an example of the workspace migration command for the demo design:

convert.alint.workspace blackjack_mixed.rwsp -force -alint_cfg

The following message is printed in the Console following the successful conversion:

# CONV-1107: The <PATH>/<workspace_name> workspace file conversion SUCCEEDED

Additional warnings might be printed during the conversion process. Click on the message ID to open a detailed description and review the generated warnings to ensure proper migration of the workspace.

Figure 8. Opening Message Description

The converted workspace is loaded into the Project Manager automatically.

Figure 9. Converted Workspace Structure

Figure 10. Converted Project Policy

Figure 11. Converted Project Waivers

After converting the ALINT workspace, make sure that you:

• review the Console output for the possible conversion warnings;

• review the structure of the imported ALINT-PRO workspace;

• ensure that the configuration data, such as policy and exclusions was converted properly.

Design Properties

The preference settings of the initial ALINT design are automatically mapped to respective ALINT-PRO properties. Normally, the project can be run in ALINT-PRO without doing any additional setup.

For example, the VHDL standard taken by default in ALINT is IEEE Std. 1076™-2002, while in ALINT-PRO it is IEEE Std. 1076™-2008. The converted design will still have 2002 standard, like it was before the conversion.

Figure 12. Imported Standard Version

When clock/reset controls are explicitly defined in an ALINT design via the Global clock signals or Global reset signals properties, they are imported into an ALINT-PRO project in the form of design constraints. In this case the <project_name>.adc constraints file is created and added to the output project. This file should contain the corresponding create_clock and create_reset constraints for the identical hierarchical paths.

Figure 13. Created Constraints File

There are options that are not supported in ALINT-PRO due to differences in underlying mechanisms. If such an option has been configured in an ALINT design, a corresponding message is printed to the Console during the conversion. Review the messages to be sure that nothing important is missed.

Shared Libraries

In ALINT-PRO a library is an integral part of a project. It is automatically created with the project and its name is equal to the project's name. The project's library should be exported in order to share it with other projects.

An exported library is a library that is separated from the project. Exporting creates a copy of library binaries. This copy is no longer connected to the project, and its content is no longer modified whenever the project state is altered, so the library data needs to be manually refreshed by re-exporting the newest version of the source project.

The predefined global ALINT-PRO libraries, in particular, standard VHDL libraries (std, ieee), as well as Verilog and VHDL libraries from target FPGA vendors (Xilinx, Altera, Microsemi, Lattice) are provided as exported libraries. Exporting the libraries is the correct technique for sharing rarely modified common libraries.

Alternatively, the library project should be included into all workspaces that use it instead of exporting and attaching. This scenario should be used when the shared library is frequently modified, so that the referencing projects always use the latest library binaries.

ALINT-PRO does not support importing ALINT library mappings (library.cfg) files. In order to use a shared library (not a VHDL standard or FPGA vendor library) in ALINT-PRO, use the following guideline:

1. Create another ALINT-PRO project and add sources of the shared library to this project.

2. Parse the project.

3. Use the Export... option from the right click menu of the project library node in the Library Viewer window and specify the library name and location to save the library.

4. Attach the exported library to your workspace using the Attach... option from the right click menu of the Attached libraries node in Library Viewer.

The following commands can be used to create an exported library in the batch mode:

workspace.project.createfromdisk -name control work_with_libraries/control/src
project.parse
project.export.library -project control -path ../libraries

Then the exported library can be attached to your workspace:

library.attach.local -file ../libraries/control/control.alintrepo

Designs with Multiple Libraries

Grouping common design units within separate libraries is a popular method to achieve a higher grade of re-usability. Often, one or more additional supplementary libraries are used in the project with no intent to become roots of design hierarchy. These libraries only provide building blocks for the main project.

ALINT-PRO provides a concept of library projects to model simplified processing and perception for supplementary libraries. Library projects are useful to model ASIC cell libraries, IP customizations, and in-house shared primitives reused between similar designs.

Library projects can only act as containers of library source files and related parsing settings, but cannot form their own elaboration or synthesis hierarchy. Instead, units that originate from library projects should be instantiated in regular projects. Only parse and parse linting phases are allowed for a library project and, correspondingly, the number of preference settings is greatly reduced compared to a regular project.

To change the type of an existing project to a library project go to the Design entry page of the project Properties. Then choose Library project in the Project type property.

Figure 14. Changing Project Type

Library projects have their own icon to distinguish them in a workspace tree.

Figure 15. Workspace Containing Regular and Library Projects

Also the dependencies between the main regular project and related library project(s) should be specified to set the correct order of parsing. Note, that the dependencies between designs in an ALINT workspace are properly imported as the project dependencies in an ALINT-PRO workspace. No additional setup is necessary for existing dependencies.

A new library project can be created similarly to a regular project using the Create New Library Project Wizard (the New | Library project option from the File main menu) and using the Create Library Project option from File Browser context menu. Refer to the 'Creating Workspace and Project' section of the 'Getting started with ALINT-PRO' Application Note for details.

FPGA Vendor Libraries

Standard and FPGA vendor libraries are installed along with ALINT-PRO. These libraries are global, so they are visible in every workspace. There are built-in timing constraints for most commonly-used vendor libraries that enable precise linting for designs with vendor library cells.

An important difference between ALINT and ALINT-PRO is that only libraries provided with the ALINT-PRO installation should be used. Avoid building FPGA vendor libraries on your own and do not attempt to re-use the libraries from ALINT, Riviera-PRO or Active-HDL. If the required library is missing in the ALINT-PRO installation list, please contact Aldec Support to request the library.

One more difference is an approach to library versions. Unlike simulators, ALINT-PRO only needs interfaces of FPGA vendor library primitives and the predefined timing constraints. ALINT-PRO does not attempt to analyze the bodies of the vendor primitive modules, and only uses the timing abstractions specified with constraints.

As a result, ALINT-PRO does not necessarily require the exact same version of a given FPGA vendor library, like the version used for post-synthesis simulations. As all the FPGA vendors attempt to keep the primitive's pins backward compatible with previous chip families, you can safely use the default provided version. The library versions are continuously updated in official and service releases of ALINT-PRO, and staying up-to-date helps to avoid possible library version incompatibility.

How to Import ALINT Policy and Rulesets

ALINT ruleset and policy files can be imported into ALINT-PRO as a project's policy properties. ALINT-PRO does not use additional external files for policies, so policy data is stored as a part of the project file (*.alintproj). ALINT configuration files are not modified during the import.

ALINT-PRO attempts to do its best to find the most appropriate mapping between the rule identifiers in ALINT and ALINT-PRO. The same applies to configuration rule parameters, when defined in the policy file. Although the majority of the rules and parameters have equivalents in ALINT-PRO, in rare cases the changes between the products might be too big. I.e., rules about comment templates, such as standardized file headers, were strongly reworked, and the configuration of such rules needs to be re-written from scratch. The conversion script issues warnings for all the cases it was not able to handle gracefully.

Refer to the Migration Guide documentation (Help | Migration Guide in the main menu) for detailed tables of the rules and parameters mapping.

So, assuming there is a custom ALINT policy like below:

Figure 16. Policy to be Imported

to import it to ALINT-PRO you can use Import Policy Wizard, which can be activating by running the Tools | Import | ALINT Policy command or by double-clicking on the ALINT policy file (*.alintpolicy) in the File Browser:

1. Specify location and name of ALINT policy file;

2. Specify location and name of ALINT-PRO project file;

3. Clean project policy before import - check this option to clear the policy settings if they are unnecessary for the project linting. Otherwise, the imported settings will be merged with already specified ones.

4. Specify the additional directories for searching of inherited configuration files (if the ruleset directory is other than the working one).

Figure 17. Import Policy Wizard

Figure 18. Policy Search Path Specification

Figure 19. Imported Policy

ALINT ruleset import process is quite similar: use Import Ruleset Wizard (click Tools | Import | ALINT Ruleset or double click ALINT ruleset file (*.alintruleset) in File Browser.

Alternatively, you can use the import.alint.policy or the import.alint.ruleset commands to import ALINT policy or ruleset correspondingly.

The policy of the demo example can be imported using the following scripting command:

import.alint.policy "<example_dir>/policy_with_nested_ruleset.alintpolicy" "<example_dir>/blackjack_mixed.alintproj" -path "<example_dir>/ruleset"

Ensure that the import process has been finished successfully and the Console window contains the following message:

# CONV-1130: The <PATH>/<*.alintpolicy> policy file import SUCCEEDED.

Review possible conversion warnings, if issued.

Difference in Rules' Checking Approaches

One of ALINT-PRO goals is to improve the implementation of ALINT rules, and this can result in possible conflicts during the policy migration. This section explains typical conflict resolution scenarios.

Some netlist-level rules common for VHDL and Verilog plugins in ALINT contained identical functionality. Which rule should trigger was being decided by the language of the main violation's instance. For such cases, ALINT-PRO replaces two rules with a single netlist rule, which is independent of the language. For example, an ALINT project could have a policy with the recommendations of not using latches with asynchronous set/reset (STARC_VHDL.2.4.1.3 and STARC_VLOG.2.4.1.3):

Figure 20. Language-Dependent Rules Checks for ALINT Project

The configuration file with one of these checkers (or both) will be imported into ALINT-PRO's project policy with one equivalent checker (STARC_NETLIST.2.1.4.3):

Figure 21. Language-Independent Checker for ALINT Project

Another type of conflict may appear for cases when a certain rule completely covers the checks of another rule. It usually happens when there are similar rules in the HDL guideline (same pattern, but possibly different motivation). ALINT-PRO attempts to avoid having the duplicated or almost fully overlapping rules as much as possible, so only the rule with larger scope is provided by ALINT-PRO.

If we consider two rules: STARC_VHDL.2.1.6.3 ("The index of an array should be simple signal names only") and STARC_VHDL.2.1.6.5 ("For an array index, other than constant and signal name should not be used"), it is the second one that has more extensive check area. Therefore, ALINT configuration file with STARC_VHDL.2.1.6.3 will be imported into ALINT-PRO's policy as STARC_VHDL.2.1.6.5 rule checker. In such case the following message will be output to Console:

# CONV-1123: Warning: The STARC_VHDL.2.1.6.3 rule is replaced with STARC_VHDL.2.1.6.5 as it covers all required checks.

One more point is that some ALINT rules can be mapped to several ALINT-PRO rules. If such a rule is a part of ALINT policy, all the mapped ALINT-PRO rules join the converted policy.

Below is an example of this case:

Figure 22. Rule Check for ALINT Project

Figure 23. Policy for ALINT-PRO Project

Parameters Import

Rules are imported from ALINT into ALINT-PRO with the set of parameter value definitions. However, there are several points that need clarification.

An ALINT rule with default configuration will be imported as an ALINT-PRO rule with default configuration provided in plug-in files. If an ALINT rule has a custom configuration, it will be imported as an ALINT-PRO rule with a custom configuration.

Figure 24. Custom Configuration for ALINT STARC_VHDL.1.1.3.3 Rule

Figure 25. Custom Settings for ALINT-PRO STARC_NETLIST.1.1.3.3 Rule

Sometimes a parameter mapping does not exist. It can happen if an ALINT parameter was deprecated, or if the behavior of the rule has changed dramatically. When the mapping does not exist, the value of such a parameter is ignored and a warning similar to the one given below is issued:

# CONV-1121: Warning: The 'LIB_LIST' parameter of the 'STARC_VHDL.1.1.1.10' rule configuration cannot be imported. The checker verifies only names of cells from ASIC libraries installed with ALINT-PRO.

If the ignored parameter is important for your design, please, contact Aldec Support to resolve the issue.

When a Verilog and a VHDL ALINT rule are mapped to an ALINT-PRO netlist rule, and the configuration is conflicting, ALINT-PRO ignores the parameter values from the ALINT policy and uses the default settings.

Importing Exclusions File

ALINT Exclusions are now called Waivers in ALINT-PRO. The basic concept is identical - waivers declare certain contexts (source file, design unit, instance), where the output of one or more rules should be ignored. Unlike ALINT, the waivers do not require a separate file and are part of the project's preference settings.

To import ALINT exclusions file(s) as ALINT-PRO waivers, follow the guideline below:

1. Select Tools | Import | ALINT Exclusions to open a wizard;

2. Specify ALINT exclusions file name (*.alintexclusions) and location;

3. Specify ALINT-PRO project file name (*.alintproj) and location;

4. Check Clean project waivers before import option if you do not want to merge importing settings with the current ALINT-PRO settings.

Figure 26. Import Exclusions Wizard

Another way to import the exclusions file(s) is to use the scripting command:

import.alint.exclusions <old_exclusions_file> <project_file> [-force] [-f <list_file>]

The exclusions of the demo design can be imported using the following scripting command:

import.alint.exclusions arch_name_conv_excl.alintexclusions blackjack_mixed.alintproj

The exclusions file is not modified during the importing.

Figure 27. ALINT Exclusions to Be Imported

Figure 28. ALINT-PRO Waivers

When the import succeeds, the following message is printed on the Console:

# CONV-1145: The <PATH>/<exclusions filename.alintexclusions> exclusions file import SUCCEEDED.

You can examine the imported waivers at the Linting | Waivers page of the project Properties. Also the project.waiver.list scripting command can be used to display waiver data.

Conclusions

Migration from ALINT to ALINT-PRO starts from converting the workspaces and projects into new storage formats. ALINT-PRO is equipped with smart conversion scripts that convert design structure, preference settings, linting policy, and the waivers. It is important to review possible migration warnings to avoid confusion, especially when the linting rules and the values of rule configuration parameters do not have direct equivalents between ALINT and ALINT-PRO.

Aldec can provide assistance in the case of migration difficulties. Please contact Aldec Support in case you need help with the migration.