Getting Started with ALINT-PRO Batch Mode

Introduction

This document is intended for those who wish to use command-line style to facilitate and automate design analysis. Iteration processes, regression testing, and integration into the user's larger scenarios involving external systems all become easier with batch processing. Besides the graphical user interface, ALINT-PRO offers two more command-line operation modes to perform interactive queries or to execute automated scripts non-interactively. Used within Windows or Linux OS, both modes provide full functionality of the product.

This application note describes the basic capabilities for ALINT-PRO running from command-line and batch scripts.

Operation Modes

You can launch and run ALINT-PRO in three different operation modes:

Graphical user interface (GUI);
Console; or
Batch.

GUI mode provides different windows, wizards, menus, etc. for working with ALINT-PRO interactively. One of the GUI elements is the Console window, which includes an interactive command-line component.

Console mode is a command-line interface. It runs at the command-line shell and is interactive as well.

Batch mode is the only non-interactive command-line mode. It executes specified scripts and terminates when the script is finished or once an error is encountered.

Interactive Console Mode

To invoke ALINT-PRO in interactive console mode, you may perform one of the following:

Double-click the ALINT-PRO Console icon on your desktop;
Select START | All Programs | Aldec | ALINT-PRO <version_number> Console;
Launch the runalintprocon script from the installation directory; or
Run the alintcon program from the bin/ subdirectory.

After performing one of the above actions, the interactive shell initiates, and you can begin manually entering commands at the command-prompt. Commands can be followed by arguments (if any). It is important to remember that if arguments contain a path with whitespace, then the path should be enclosed in braces or double quotes. Avoiding braces and double quotes within the path is preferred.

The program stops at a prompt, allowing you to enter commands interactively. This way, the user has complete control over the design flow.

ALINT-PRO console mode can be terminated with quit, bye, or exit commands.

ALINT-PRO uses Tcl as a scripting language and includes an embedded Tcl interpreter. Numerous language constructs such as variables, lists, loops, procedures, etc. allow you to manage the design process. The Tcl interpreter version is stored in the tcl_version variable. Information on Tcl and Tcl built-in commands can be found at http://www.tcl.tk. Standard Tcl libraries included in the product are extended with ALINT-PRO's own libraries suitable for the typical procedure automation.

To view the list of the commands provided in ALINT-PRO, consult the Command Reference guide (see <installation directory>\documentation\cmd_ref\html\cmd_ref.html). You can also press tab at the command prompt for a complete command list.

Common utility commands can be used to change directories (cd), create new directories (mkdir), print the current directory (pwd) or a list of the files/directories contained within the current directory (dir), move files or rename directories (move), print messages (echo), etc.

Let us now consider the commands which ALINT-PRO supplies to manage the design analysis (all the examples given below are relative to the ALINT-PRO installation directory).

Creating a Workspace and Project

After launching the interactive console mode, a workspace with project(s) should be created:

workspace.create <workspace_name>

or opened:

workspace.open blackjack_mixed.alintws

If you create a new workspace, it needs projects that altogether model the entire design.

Add a new project to the workspace:

workspace.project.create <project_name>

or add an already existing one:

workspace.project.add <project_file>

You can add files to a project by listing them as arguments:

workspace.file.add -destination <project_name> <files_list>

or using -f switch (if source files are listed in a file):

workspace.file.add -destination blackjack_mixed -f ./examples/quick_start/create_from_disk/bjack_mixed/src/files.lst

It is possible to create a project and add all files from the specified directory with one command:

workspace.project.createfromdisk -name <project_name> <directory_with_source_files>

Project Dependencies

ALINT-PRO allows defining dependencies between multiple projects and files within a workspace:

workspace.dependency.add -project <project_name> [-file <node_name>] -dependency <dependent_project_name>\
  [-dependency_file <dependent_node_name>]

Once specified, the project parse order is defined implicitly.

Dependencies can be set between files of a project. For example:

project.dependency.add -project blackjack_mixed -file blackjack.v -dependency gates.vhd

The gates.vhd file is parsed before parsing of the blackjack.v file.

Design with Multiple Libraries

A design can be modeled with one or more additional supplementary libraries that are used in the project as containers of library source files and related parse settings. For such cases, it is reasonable to introduce library projects into the workspace.

A new library project can be created similarly to a "regular" project using the commands:

workspace.library.create -destination <virtual_hierarchical_path> -force <library_project_name>

workspace.library.createfromdisk -destination <virtual_hierarchical_path> -name <new_name> <directory>

As these libraries are only "building blocks" for the main project and cannot form their own elaboration or synthesis hierarchy, units that originate from the library projects should be instantiated in "regular" projects. Also, the dependencies between the main "regular" project and related library project(s) should be specified to set the correct order of parsing (only parse and parse linting phases are allowed for a library project).

workspace.dependency.add -project system -dependency amplifier

The library project amplifier is now a dependency for the system "regular" project and is thus parsed first (both projects are included in the audio_system workspace from ALINT-PRO's installed examples).

Global Preferences and Project/File Properties

When a new project is created, the project Properties are inherited from the global Preferences. A special set of commands, global.pref.*, is provided to adjust the global Preferences. The default settings of the project properties can be customized with a vast family of project.pref.* commands such as:

# Specify top level unit
project.pref.toplevels -top <unit_name> -top <unit_name> ...

# Specify vendor libraries for Verilog design
project.pref.vloglibs -lib unisims_ver

# Specify language standard
project.pref.vhdlstandard -format vhdl2008
project.pref.vlogstandard -format sv2005

If the workspace has a number of projects, each can have its own settings (use the -project <project_name> argument)

project.pref.vlogstandard -project blackjack_mixed -format sv2009

By adding the -file <file_name> argument, you can fine-tune the settings for a file:

project.pref.vlogstandard -project blackjack_mixed -file bjack_c.v -format v95

To view the entire list of the global.pref.* and project.pref.* commands provided in ALINT-PRO, consult the "Global Preferences" and "Project" sections of the Command Reference guide (<installation directory>\documentation\cmd_ref\html\cmd_ref.html).

Linting Policy

The exact set of rules enabled for design analysis, as well as their configuration parameters, form a linting policy that can be configured globally or customized for individual projects. Use the project.policy.clear command for cleaning the default policy (if needed) and the project.policy.add command for adding new rules to the policy:

project.policy.add -rule ALDEC_BASIC_VHDL.2051_a

You can set a new parameter value with the project.policy.ruleconfig.setvalue command. To set additional values of parameters with list types, use the project.policy.ruleconfig.addvalue command.

project.policy.ruleconfig.setvalue -rule ALDEC_BASIC_VHDL.2051_a -parameter VARIABLE.REGEXP='.+_v$'

For more detail, please refer to our 'Customizing Linting Policy' Application Note.

Running Analysis

At this moment, the design organized as one or more projects is ready for analysis: the workspace is created/opened, the active project is defined, the dependencies within the workspace are specified, and various preference settings that configure design entry and linting stages are set. It is now time to begin running analysis.

The design analysis phases can be ran with or without linting and either run individually or all at once:

all phases of the project analysis (design entry and linting);
```
project.run -project blackjack_mixed
```

a separate design entry phase;

project.parse -project <project_name>, 
project.elaborate -project <project_name>,  
project.synthesize -project <project_name>, or 
project.constrain -project <project_name>

a linting phase specified for the project;

project.lint -project <project_name> [-parse] [-elab] [-synthesis] [-constraints] [-chip]

all linting phases for the project (no phase argument).
```
project.lint -project <project_name>
```

If a command does not have a project name as the argument, then it is applied to the active project.

For more information on the design analysis phases in ALINT-PRO, please refer to our 'Getting started with ALINT-PRO' Application Note.

Reports

When analyzing a design, ALINT-PRO generates a number of reports that facilitate the working process and are useful for formal code reviews.

Information about synthesized and constrained projects (such as clock/reset signals, equivalent logic gate counts for instances, etc.) can be viewed in a text-format file:

project.report.synthesis -report <file_name>

Violations detected during design linting are available for analysis and are registered in reports:

violations reported for all projects of the workspace;

workspace.report.violations -format <report_format> -report <file_name_or_console>

violations reported for a particular project;

project.report.violations -format <report_format> -report <file_name_or_console>

design quality HTML report (presents quality percentage based on the ratio of violated to non-violated rules).
```
project.report.quality -report <file_name>
```

The following output formats are available for violations reports (using -format {simple_text | full_text | csv | pdf | html} argument):

simple text;
full text;
CSV (comma-separated values);
PDF;
HTML (only for project.report.violations).

Some examples:

# Synthesis report generated in the synth.txt file
project.report.synthesis -project blackjack_mixed -report synth.txt

# Violations reported on the gates.vhd source with the "Rule" rule level are printed to console
project.report.violations -report console -source {gates.*} -severity warning -rule_level rule

# Design quality report printed to the qreport.html file with the rule levels as a grouping criterion
project.report.quality -report qreport.html -classification rule_levels

In some scenarios, the detected violation may be considered as irrelevant or low priority. The user can explicitly express this intent by changing the violation's relevance using the waivers mechanism. The waived violations should not be counted as issues that break the verification process. Refer to 'Using Waivers to Skip Irrelevant Violations' article for details.

Batch Mode

Sometimes it is time-saving to debug and test the design analysis scenario with the GUI or the interactive console mode, and then write out the macro file. The macro file is a Tcl script that can easily be edited as you update the design.

Batch mode is intended to execute macro(s) or script(s) without the user's manual intervention.

To start running ALINT-PRO in non-interactive batch mode, either the runalintprocon script or alintcon program should be launched with the -batch argument.

For example:

runalintprocon -batch -do runme.do

where the -do argument specifies a macro (runme.do) which includes the set of commands required for the design run scenario.

Another method of launching this mode is to use the alintbatch program from the bin/ subdirectory. This program is intended for linting the given files in non-interactive mode. It allows:

creating workspace and project in the specified location;
adding files to the project;
executing linting;
generating log files and reports;
removing temporary files.

The following arguments can be used:

<source_file> - source file(s) to be linted (can be specified multiple times);
-project_name <project_name> - name of the created project;
-use_project <additional_project> - additional project to be attached to the workspace before main project parsing;
-preference <preferences> - name and location of ALINT-PRO macro file where project properties are defined (e.g., rules to be verified during linting); it is executed before parsing. The argument can be specified multiple times;
-output <output_directory> - directory for workspace and project creation as well as location of temporary data. If omitted, the current working directory is used;
-log_file <log_file> - log file name. If omitted, it is alint.log.

The next group of arguments define linting phase(s) to be executed:

-parse_lint;
-elaboration_lint;
-synthesis_lint;
-constraints_lint;
-chip_lint.

Design entry phases (parse, elaboration, synthesis, or constraints) that correspond to the given linting phase will be executed before it. In other words, parse, elaboration, and synthesis phases will precede synthesis linting phase if -synthesis_lint argument is used.

If the -parse_only argument is used, then only the parse phase is executed (linting results are not available).

In the case where no *_lint arguments are provided, all linting phases are executed.

These next four arguments specify types and names of the reports to be generated:

-violations_simple_txt <simple_txt_report> - simple text report file name. If omitted, the report is saved to alint_violations.txt in the output directory;
-violations_csv <csv_report> - CSV report file name. If omitted, the report is not generated;
-violations_full_txt <full_txt_report> - full text report file name. If omitted, the report is not generated;
-synthesis <synthesis_report> - synthesis report file name. If omitted, the report is saved to alint_synthesis.txt in the output directory.

Some more arguments:

-cleanup - removes all the generated data (including project file and temporary data) from the output directory, excluding reports;
-start_gui or -start_console - starts ALINT-PRO in the GUI or in the command-line mode when linting is finished; the linted project is opened after ALINT-PRO launches;
-force - allows files to be overwritten in the output directory;
-f <list_file> - specifies the name of a file with command options; it can be inserted in any position of the command line.

Below are two examples of using the alintbatch program:

alintbatch and2.vhd -project_name logic_elements -parse_only

creates the logic_elements project in the current directory;
adds and2.vhd file to the logic_elements project;
parses the logic_elements project.

alintbatch top.vhd -project_name top -preference prefs.do -use_project logic_elements.alintproj -cleanup

creates the top project in the current directory;
adds the top.vhd file to the top project;
executes the prefs.do macro file;
adds the logic_elements project to the workspace;
runs the top project;
generates a synthesis report to the alint_synthesis.txt file;
generates a simple text violations report to the alint_violations.txt file;
deletes the created project file and any generated temporary data.

Conclusions

ALINT-PRO allows the user to work both via convenient GUI instruments and automated scripts. Both application modes provide full functionality for design analysis. While the GUI mode might be preferable for getting started with the product and for some debugging procedures (such as violation analysis using cross-probing to HDL code and RTL schematic), the console mode is more suitable for integrating ALINT-PRO into a company's accepted design flow as well as automating routines (such as regression testing). Both modes can be combined to maximize the application's capabilities. For example, creating workspaces, environment setup, design analysis, and report generation can all be automated, and then further investigation of complex cases can be performed via GUI tools.