SpyGlass® Policy Customization Guide · SpyGlass Rule Definition SpyGlass Rule definition concepts Developing New SpyGlass Rules How to develop custom rules using standard rule-Primitives

SpyGlass® Policy Customization Guide

Version 4.4.1

October 2010

Atrenta, Inc.2077 Gateway Place, Suite 300San Jose, California 951101-866-ATRENTA (1-866-287-3682)http://www.atrenta.com

©Copyright 2001-2010 Atrenta, Inc. All rights reserved.

Copyright Information

This document is protected by copyright and distributed under licenses restricting its use, copying, and distribution. No part of this document may be reproduced in any form by any means without prior written authorization of Atrenta and its licensors, if any.

DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.

Atrenta, SpyGlass, and Predictive Analysis are registered trademarks of Atrenta Inc. All other trademarks are the property of their respective owners.

Printed in the United States of America.

Table of Contents


Preface............................................................................................................................. 7

About This Book......................................................................................................................................7

Contents of This Book ............................................................................................................................7

Typographical Conventions ...................................................................................................................8

SpyGlass Rule-Checking Environment ........................................................................ 9

Overview...................................................................................................................................................9

SpyGlass Custom Rule Development .................................................................................................10

Structure of a SpyGlass Policy Ruledeck File ....................................................................................11Header Section.................................................................................................................................12Use Section ......................................................................................................................................12Policy Registration Section...............................................................................................................13Library Registration Section .............................................................................................................15Severity Declaration Section ............................................................................................................16Require File Section .........................................................................................................................18Rule Parameter Description Section ................................................................................................19

Using spyObsoleteParameter API ............................................................................................20Using spyRegisterReportParameter API...................................................................................22

Rule Description Section ..................................................................................................................22Rule Group Description Section .......................................................................................................23Report Description Section...............................................................................................................23End-of-Policy Section .......................................................................................................................23

SpyGlass Rule Definition............................................................................................. 25

Overview.................................................................................................................................................25

Rule-Primitive Description files ...........................................................................................................27

Understanding Rule Description..........................................................................................................27Rule Description Section ..................................................................................................................27Rule Function Section ......................................................................................................................30Rule Registration Section.................................................................................................................30

Registering Rules ..................................................................................................................................34

Version 4.4.1 October 2010 iii

Table of Contents


Registering Individual Rules .............................................................................................................35Registering Rule Groups ..................................................................................................................38Registering Multiple Severities/Messages for a Rule .......................................................................39

Developing New SpyGlass Rules ................................................................................43

General Methodology on Developing New Rules ...............................................................................43

Searching Atrenta Infrastructure for Rule-Primitives ........................................................................44Adapting Atrenta Standard Rules .....................................................................................................45Using SpyGlass Built-In Checks.......................................................................................................46

Creating New Rules ...............................................................................................................................48

Creating Rules by Copying Existing Rules .........................................................................................59

Adding Command-line Options to SpyGlass Rules ...........................................................................62

Changing SpyGlass Rule Usage information .....................................................................................64

Specifying Obsolete Rules ...................................................................................................................64

Creating Custom Reports.............................................................................................67

Overview.................................................................................................................................................67

Custom Report Concepts .....................................................................................................................67

The spyRegisterReportGenerator function.........................................................................................69

Creating Report Generator Functions .................................................................................................69

Reading VDB Rule Message Information ............................................................................................70

A Report Generator Example................................................................................................................71

Overloading SpyGlass Policies ...................................................................................75

Introduction............................................................................................................................................75

Single Policy Overload Feature............................................................................................................76Using the SpyGlass Design Environment.........................................................................................76

Customizing Rules ....................................................................................................................76Customizing Policy or Rule Group Severity Label.....................................................................78Customizing Parameters ...........................................................................................................79

iv October 2010 Version 4.4.1

Table of Contents


Saving Policy Overload Information ..........................................................................................81Analyzing with Overloaded Policies ..........................................................................................81

Working in the Batch Mode ..............................................................................................................81The spyOverload API Function .................................................................................................82Overloading Rules.....................................................................................................................82Overloading Rule Parameters...................................................................................................85Using Overloaded Policies ........................................................................................................86

Named Policy Overloads Feature ........................................................................................................87Named Policy Overloads in the SpyGlass Design Environment ......................................................87

Other Features of the Rule Customization Window ..................................................................92Named Policy Overloads in the Batch Mode....................................................................................92

Appendix A: Introduction to Perl ................................................................................ 95

Using Perl...............................................................................................................................................95

Perl similarities to C ..............................................................................................................................95

Perl differences from C .........................................................................................................................96

Defining and using constants and variables in Perl ..........................................................................96

Using Regular Expressions in Perl......................................................................................................98

Defining and using Subroutines/Functions in Perl ............................................................................99

Version 4.4.1 October 2010 v

Table of Contents


vi October 2010 Version 4.4.1

Preface

About This BookThe Atrenta® SpyGlass® Policy Customization Guide describes how to create custom rule policies.

Contents of This BookThe SpyGlass Policy Customization Guide has the following chapters:

Chapter Describes...

SpyGlass Rule-Checking Environment How SpyGlass performs rule-checking

SpyGlass Rule Definition SpyGlass Rule definition concepts

Developing New SpyGlass Rules How to develop custom rules using standard rule-Primitives

Creating Custom Reports How to create SpyGlass report generators for your custom rules

Overloading SpyGlass Policies How to design overloaded policies

Appendix A: Introduction to Perl Basic Perl concepts

SpyGlass® Policy Customization Guide 7

Typographical Conventions


Typographical ConventionsThis document uses the following typographical conventions:

The syntax described in this document uses the following convention:

To indicate Convention Used

Program code OUT = IN;

Object names OUT

Variables representing objects names <sig-name>

Message Parameter name must start with P_

Message location OUT = IN;

Reworked example with message removed OUT_CLK = IN;

Important Information NOTE: This rule...

Convention Indicate...

Square brackets “[ ]” An optional entry or parameter.

Braces “{ }” An entry that can be specified one or more times

Vertical bar “|” A list of choices out of which you can choose one

Horizontal ellipsis “. . .” Other items that are normally provided

8 October 2010 Version 4.4.1

SpyGlass Rule-Checking Environment

OverviewThe Atrenta® SpyGlass® Predictive Analyzer runs on one or more HDL files (either Verilog, VHDL, or both) and analyses these designs for predefined rules, contained in “policy” ruledeck files. The policy ruledeck files enable SpyGlass to be used repeatedly with different source files, calling up different sets of rules to be checked at different times.

The overall SpyGlass Rule-Checking environment is shown in the following figure:


SpyGlass Custom Rule Development


FIGURE 1. SpyGlass Rule-Checking Environment

SpyGlass Custom Rule DevelopmentSpyGlass ships with a large number of standard policies having a rich set of rules, enabling you to immediately apply these policies to your design and get useful information.

However, you may wish to add your own rules, modify the standard rules, and also create unique company reports to meet your specific requirements.

SpyGlass allows you to customize the rule-checking in the following ways:

Modify the standard policies

You can modify defaults for rule severities, messages, allowed name syntax or other parameters to reflect your local preferences.

Create new rules based on SpyGlass standard rule-primitives

Source Files

Library Files

Options

Schematic Data

SpyGlass SpyGlass DesignEnvironment

Policies

Rule-Primitive Libraries

Violation Database

Reports




It is possible, in the core SpyGlass product, to create new rules based on the pre-defined rule primitives.

Create new rules based on SpyGlass Objects

See the SpyGlass Objects User Guide for more details.

Create new rule-primitives and rules based on these custom rule-primitives

You can also develop entirely new custom rule-primitives (requires the optional SpyGlass Builder product) and create rules based on these rule-primitives.

You can also modify the standard reports generated by SpyGlass rules or add your own reports.

The intent of this document is to provide suitable information to allow you to create new rules or custom report generators. As the majority of the environment is based on Perl, a minimum knowledge of Perl is required in order to do this.

Structure of a SpyGlass Policy Ruledeck FileA policy ruledeck file is an ASCII text file named <policy-name>-policy.pl where <policy-name> is the name of the policy. For example, the standard SpyGlass Lint policy ruledeck file is named lint-policy.pl. Each main policy ruledeck file may include one or more other files where the rule description has been distributed for better file management. For example, the standard SpyGlass Lint policy ruledeck file lint-policy.pl uses the verlint.pl file (contains description of Verilog only rules), vhdllint.pl file (contains description of VHDL only rules) and mixedlint.pl file (contains description of rules that work on both Verilog and VHDL designs). If the policy have a small number of rules, it is recommended to use only one main file (as done for SpyGlass Clock-Reset policy, SpyGlass ERC policy etc.).

Each policy ruledeck file has the following sections:

Version 4.4.1 October 2010 11

Structure of a SpyGlass Policy Ruledeck File


Header Section

The Header section contains the policy description and policy revision history. Each line in the Header section must be a Perl comment line, that is, starting with Perl comment character (#) as the first character in the line.

The Header section is optional but is recommended for better understanding of policy users.

If your policy description is distributed over a number of files, it is recommended that each file has its own Header section.

Use Section

The Use section specifies the policy package details.

To avoid Perl Callback function namespace clashes between different SpyGlass Policies that are simultaneously registered, SpyGlass

Section Contains...

Header Section Policy description and revision history

Use Section Policy Package information

Policy Registration Section Policy Registration and Information

Library Registration Section Associated SpyGlass-compatible libraries’ declarations

Severity Declaration Section Rule severity-labels’ declarations

Require File Section Child files’ declarations

Rule Parameter Description Section Rule parameters’ declarations

Rule Description Section Rules’ declarations

Rule Group Description Section Rule Groups’ declarations

Report Description Section Rule Reports’ declarations

End-of-Policy Section Policy file termination command




supports the package concept where you can specify declare a package namespace for a SpyGlass Policy. Then, you should specify the Policy-specific Perl Callback functions in the following format:

<package-name>::<func-name>

For example, the SpyGlass STARC Policy has the following use section:

package starc;

This statement declares the Policy Package namespace as starc. Now, all Perl Callback functions in SpyGlass STARC Policy are specified as in the following example:

$msg="Primary port/module '%s' does not follow naming convention.";spyRegisterRule("Verilog", "STARC-1.1.1.6", "PrimModPortName", "veSrpNames_Init", "veSrpNames","Mandatory", $msg, 5,"starc::veSRP_1_1_1_6 topmodule topport", 1);

You also need to include the following mandatory call that includes the standard package named spyglass to enable standard SpyGlass Policy APIs:

use spyglass;

Policy Registration Section

The Policy Registration section specifies the policy information.

For example, the SpyGlass STARC Policy has the following Policy Registration section:

print "STARC rules\n" if !defined $::spyInIspy and !defined $::norules;

spyRegisterPolicy("starc", "1.6.6","SpyGlass rules that check HDL designs

for IP Reuse guidelines compiled by STARC.","3.3.0", "", "", "", "");




The first line prints STARC Rules to stdout and SpyGlass log file provided you are not running the STARC policy from the SpyGlass Design Environment (controlled by !defined $spyinIspy) and you have not specified the -norules command-line option (controlled by !defined $norules).

Next lines have a call to spyRegisterPolicy function call that sets the following values:

Variable Purpose Value in STARC Example

<policy-name> Specifies the policy name in case-insensitive manner.

Used as display-label wherever the policy name is required to be reported.

starc

<policy-version> Specifies the policy version.

Printed from -version (and -policies=<policy-name>) command-line option

1.6.6

<policy-description> (Optional) Specifies the short policy description to guide users about the policy purpose

SpyGlass rules that check HDL designs for IP Reuse guidelines compiled by STARC.

<SpyGlass-min-version> Specifies the minimum SpyGlass Version required for running the this version (<policy-version>) of the policy.

3.3.0

<policy-help-file> (Optional) Specifies the policy help file (in ASCII Text format) containing policy’s long description.

By default, SpyGlass looks for an ASCII text file named <policy-name>-help.txt in the same location as the policy file.

Nothing

<Policy-Start-Func> (Optional) Specifies a Perl function that will be run before init functions of any rules of the policy are run.

Nothing




NOTE: If your policy description is distributed over a number of files, the Policy Description section must be in the main policy ruledeck file only.

Library Registration Section

The Library Registration section registers the associated SpyGlass-compatible library files that contain the description of rule-primitives used by the rules of the policy.

Each SpyGlass-compatible library is declared using the spyLoadSharedRuleObject API function in the following syntax:

spyLoadSharedRuleObject("<lib-name>” );

Where <lib-name> is the name of the SpyGlass-compatible library file without the .spyso extension.

For example, to declare a SpyGlass-compatible library file named libVeStarc-$(plat).spyso ($(plat) variable for platform mnemonic is automatically set by the Makefile), use the following command:

spyLoadSharedRuleObject("libVeStarc");

The Library Registration section is mandatory if the rules in the policy are using rule-primitives of SpyGlass-compatible library files.

If your policy description is distributed over a number of files, it is

<Policy-End-Func> (Optional) Specifies a Perl function that will be run after exec/exit functions of all registered rules of the policy are run.

Nothing

<high-profile-rule-list> (Optional) Specified a space-separated list of high-profile rules that should be reported first in SpyGlass reports and in the Policy Tab of the Message Window of the SpyGlass Design Environment

Nothing

Variable Purpose Value in STARC Example




recommended that you declare the library file(s) associated with the rules described in a file in that file itself.

Severity Declaration Section

The Severity Declaration section registers each of the rule severity-labels used in the policy under the standard severity-classes.

Each rule severity-label is registered using the spyRegisterSeverity API function using the following syntax:

spyRegisterSeverity("<policy-name>","<severity-label>","<severity-class>",<severity-label-limit>,<severity-label-description>);

Where

<policy-name> is the policy mnemonic within which specified severity-label mapping to severity-class is applicable. <policy-name> is case-sensitive and must be the exact policy mnemonic.

<severity-label> is the severity-label being registered. <severity-label> is case-insensitive.

<severity-class> is one of the standard severity-classes under which the severity-label is being registered. <severity-class> is case-sensitive and must be exactly one of the following — FATAL, ERROR, WARNING, INFO, and DATA.

<severity-label-limit> is an integer value that limits the maximum number of messages that can be reported from all rules (of this policy) for this severity-label.

NOTE: This limit applies individually to each policy and does not include waived messages or other such messages. Specifying -1 means infinite messages of the severity-label can be reported.




<severity-label-description> is a short description of the severity-label and is used in the SpyGlass Design Environment as rule help.

On execution, the spyRegisterSeverity API function returns 1 (for success) or 0 (for failure). When the spyRegisterSeverity API function fails, it means that the severity-label is not registered under the specified severity-class.

NOTE: The following severity-labels are predefined within SpyGlass environment. However, these severity-labels can be re-registered with exact same severity-class. Such re-registration may be used for further explanation of severity label (in the context of policy using it), and specification of maximum message limit. If these pre-defined labels are used without explicit registration, the default limit of -1 is used.

In addition above predefined severity-labels, each policy may define any number of additional severity-labels.

It is recommended that all user-defined rule severity-labels should be declared before use in rules. However, you may not declare the severity-labels (feature provided for backward compatibility). Then, all user-defined rule severity-labels are automatically declared under the ERROR severity-class. When SpyGlass encounters an un-declared severity-label, a warning message is printed to stdout and SpyGlass log file.

If your policy description is distributed over a number of files, the

Table 1: Predefined Severity-Labels and their Severity-Classes

Predefined Severity-Labels Severity-Class

Fatal FATAL

Error ERROR

Warning WARNING

Info INFO

Data DATA




Severity Declaration section must be in the main policy ruledeck file.

For example, the SpyGlass STARC policy registers the rule severity-labels under the standard severity-classes as follows:

spyRegisterSeverity("starc", "Prohibited", "ERROR", -1, "");spyRegisterSeverity("starc", "Mandatory", "ERROR", -1, "");spyRegisterSeverity("starc", "Caution", "WARNING", -1, "");spyRegisterSeverity("starc", "Recommended","WARNING", -1, "");spyRegisterSeverity("starc", "Reference", "INFO", -1, "");

Require File Section

If your policy description is distributed over a number of files, you need to require all child files in the main policy ruledeck file. Each child file should be declared using the require function of Perl.

For example, the standard SpyGlass Lint policy ruledeck file lint-policy.pl uses the verlint.pl file (contains description of Verilog only rules), vhdllint.pl file (contains description of VHDL only rules) and mixedlint.pl file (contains description of rules that work on both Verilog and VHDL designs). These child files are declared as follows:

if (uc($spyglass_language) eq "VHDL") {require "vhdlstarc.pl";require "mixedstarc.pl";

}

if (uc($spyglass_language) eq "VERILOG") {require "verilogstarc.pl";require "mixedstarc.pl";

}

if (uc($spyglass_language) eq "VERILOG+VHDL") {require "verilogstarc.pl";require "vhdlstarc.pl";require "mixedstarc.pl";

}

The Require File section is not required if your policy is entirely




described in one file.

Rule Parameter Description Section

If the rules in your policy use rule parameters, you need to declare each of the rule parameters using the spyParameter API function in the following syntax:

spyParameter("<policy-name>","<rule-list>","<ruleparam-name>",<ruleparam-value-list>);

Where

<policy-name> is the policy mnemonic within which the specified rule parameter is being declared. This field is currently ignored. Hence, you can also leave it blank.

<rule-list> is the list of rules to which this rule parameter is applicable. Then, you can view the help of these rules also when you view the description of this rule parameter in the Parameter Selection dialog of the Run > Policies... menu option in the SpyGlass Design Environment.

<ruleparam-name> is the name of the rule parameter. <ruleparam-name> is case-sensitive.

<ruleparam-value-list> is the possible values of the rule parameter. The first-mentioned value is the default value of the rule parameter.

For example, some of the rule parameters declared in the SpyGlass STARC policy are as follows:

spyParameter("starc","STARC-2.10.6.5","size_of_mult_max","16");spyParameter("starc",["STARC-1.1.5.1","STARC-1.1.5.4"],"regname", "reg");spyParameter("starc","STARC-2.1.1.1", "comb_logic_style",["function","always"]);




spyParameter("starc","STARC-3.5.2.1","src_master_dir","");

You can see from the examples that the possible values of a rule parameter can be a number, a string, a list, or null.

NOTE: You should appropriately fill the rule list in the spyParameter API. If a rule dependent on a given parameter is not mentioned in the rule list argument of spyParameter API, then SpyGlass may generate spurious 'checkCMD_unused_param01' warning messages for such parameters, even if their dependent rules are active in the current run.

NOTE: If you use special characters $, %, @, \, or " (double quote) in the rule parameter values, you are required to precede each such special character with a \..

If your policy description is distributed over a number of files, it is recommended that you declare the rule parameters associated with the rules described in a file in that file itself and the global rule parameters in the main policy ruledeck file.

Using spyObsoleteParameter API

You can declare a rule parameter as obsolete using the spyObsoleteParameter API in the following syntax:

spyObsoleteParameter ("<obsolete_parameter>","<alternate_parameter>");

OR

spyObsoleteParameter("<obsolete_parameter>", "");

Where

<obsolete_parameter> is the old parameter name that has to be deprecated.

<alternate_parameter> is the alternate parameter name that should be used in place of the old parameter name. If you specify an




alternate parameter name as the second argument, then this parameter will be sed in place of the old parameter (obsolete parameter).

Specifying the second parameter (alternate_parameter) is optional. You may just specify an empty string ("") as the second argument, in which case, SpyGlass will ignore the (obsolete) parameter and will not set an alternate parameter.

For example, if you need to set the gen_sdc_use_inferred_clocks rule parameter as obsolete, you may use the spyObsoleteParameter as given below:

spyObsoleteParameter("gen_sdc_use_inferred_clocks", "");

Now, if the gen_sdc_use_inferred_clocks rule parameter is specified at the command-line as shown:

spyglass -batch -policy=constraints -gen_sdc_use_inferred_clocks

then, SpyGlass ignores the parameter and displays the following warning:

WARNING: Ignoring obsolete parameter '-gen_sdc_use_inferred_clocks'

If the spyObsoleteParameter API is set as below:

spyObsoleteParaemter(“allowed_drive_cells”, “drive_cells_list”);

and if you specify at the command-line the following:

spyglass -batch -policy=constraints -allowed_drive_cells

Then, SpyGlass generates the following warning message:

WARNING: Parameter '-allowed_drive_cells' is obsolete. Insteadsetting new parameter '-drive_cells_list' to specifiedvalue '1'




Using spyRegisterReportParameter API

You can use the spyRegisterReportParameter to register parameters for a report of a specified policy. The syntax of this API is given below:

spyRegisterReportParameter(“<policy_name>”,“<report_name>”,“<parameter_name>”,“<parameter-value>”,FILE_BROWSER);

<policy_name> argument specifies the name of the policy for which the report parameter needs to be set.

<report_name> argument specifies the name of the report for which the report parameter needs to be set.

<parameter_name> argument specifies the name of the parameter name.

<parameter_value> argument specifies the parameter value.

An example of the spyRegisterReportParameter is given below:

spyRegisterReportParameter("area","diff","diff_with","./spyglass.vdb",FILE_BROWSER);

Rule Description Section

The Rule Description section is the main section where the rules in the policy are declared.




See SpyGlass Rule Definition for further details.

Rule Group Description Section

The Rule Group Description section lists the rule groups under which the rules in the policy are grouped.

See SpyGlass Rule Definition for further details.

Report Description Section

The Report Description section describes the policy reports.

See Creating Custom Reports for further details.

End-of-Policy Section

Each policy must end with the following line:

1;





SpyGlass Rule Definition

OverviewAt the heart of the SpyGlass environment are the rules, normally managed together in policies. The policies are text (Perl) files that define the rules to be checked. Atrenta ships several standard policies covering Lint, OpenMORE, and other optional policies covering ERC and DFT. You can modify these standard rule policies and can also develop your own policies from scratch.

The rules are the definitions of issues to be checked in the design. Each rule needs to be ‘registered’ to make it visible to SpyGlass and has a number of programmable attributes to define the specific function (see Registering Individual Rules for the full definition of the attributes). Among the attributes is, very importantly, the rule-primitive that should be called for the rule. The aim of the rule-primitive is to split the database access from the rule definition to make rule definition as easy as possible while still providing great flexibility and power.

The rule primitive is a set of C functions, found either in the SpyGlass core, or in a shared library, which does the real work of checking the


Overview


rule. It is the rule-primitive that accesses the design database and extracts information based on the specific rule-primitive being used and the design object being accessed. It also provides information on the rule and object for use in generation of the messages for any rule-messages detected. For each rule-primitive, there may be one, two, or three executables, one of which is called when SpyGlass first starts (the initialization function) prior to reading the design, the second is called when the design object is found in the database, and the third is called after the rule-checking.

The breadth and flexibility in SpyGlass comes from the extensive range of rule-primitives supplied as part of the core environment, together with the ability for users to create new rule-primitives, if required, using the optional SpyGlass Builder product.

What rule-primitive should be called for each rule is specified as part of the registration, together with any parameters the rule-primitive may accept that are unique to that rule. Some rule-primitives take no parameters, usually when there is only one meaningful way in which a rule can be checked (for example, checking for a blank line between port declarations of different input and output types). Other rules take one or more simple parameters (for example, an integer defining the maximum allowed length (in characters) for the rule which checks line lengths).

Some rule-primitives accept the name of a Perl function rather than a specific parameter. This Perl function, which must be defined in the policy just prior to the rule definition itself, performs a detailed test to determine whether a rule has been violated based on information passed to it by the rule-primitive. For example, for a name check rule, the rule-primitive would extract the object name from the design and invoke the specified Perl function, passing the name as one of the arguments to the function. The function tests the name for validity against a specified pattern or set of patterns. The result of the test (pass or fail) is returned to the rule-primitive for final processing. The rule-primitive will then generate suitable messages (if required) as defined in the rule registration.




As well as accepting arguments as part of the definition of the rule, each rule-primitive may also pass arguments back to be used within any messages.

Rule-Primitive Description filesThe standard rules-primitives are documented in the following files:

The *.txt files in the <your-inst-dir>/SPYGLASS_HOME/doc/c_primitives/<lib-name> directory (for standard rule-primitives of the Lint and OpenMORE policies)

The *.txt files in the <your-inst-dir>/SPYGLASS_HOME/policies/<policy-name>/c_primitives directory for other policies

Use the Help > On-line Manuals menu option in the SpyGlass Design Environment or the spydocviewer utility in the batch mode to access these files.

The registration of rules and definition of arguments is covered in Registering Individual Rules, and the definition of new rules is covered in subsequent chapters.

Understanding Rule DescriptionEach SpyGlass rule is described in the following sections:


Rule Function Section

Rule Registration Section


The Rule Description section contains the rule type details, rule short help, and rule long help in proscribed format.

The Rule Description section must be contained with in a pair of =pod


Understanding Rule Description


and =cut lines in the following format:

=pod++++<rule-name> <rule-lang-type> <policy-name>*<rule-short-description>*<rule-long-description>*=cut++++

Where

<rule-name> is a unique string of alphanumerical characters and underscore character.

<rule-lang-type> can be one of the following:

<policy-name> is the policy mnemonic within which specified rule is being declared. <policy-name> is case-sensitive and must be the exact policy mnemonic.

<rule-short-description> is one-line description of the rule purpose. This description is used in the SpyGlass Design Environment to provide short rule help.

<rule-long-description> is multi-line description of the rule purpose. This description is used in the SpyGlass Design Environment

Value Indicates that the rule works on...

Verilog Verilog Only designs or Verilog portions of Mixed-Language designs

VHDL VHDL Only designs or VHDL portions of Mixed-Language designs

Verilog+VHDL Verilog Only designs, VHDL Only designs, or entire Mixed-Language designs (with same short description and long description for both Verilog and VHDL)

Verilog.VHDL Verilog Only designs, VHDL Only designs, or entire Mixed-Language designs (with same short description but different long description for Verilog and VHDL)




to provide detailed rule help.

For rules of Verilog.VHDL type, the long description must be in the following format:

Verilog:<long-description-Verilog>

VHDL:<long-description-VHDL>

The header lines (Verilog: and VHDL:) must have at least one space at the start of the line.

Then, the SpyGlass Design Environment automatically displays the correct long description based on the current language context.

NOTE: The <rule-short-description> and <rule-long-description> sub-sections are optional. If you do not provide these descriptions, there would be no rule help available in the SpyGlass Design Environment or through the spyexplain utility.

NOTE: While displaying the rule long description, the SpyGlass Design Environment removes all line breaks and merges the lines into one paragraph. To start a new paragraph, you must add one blank space at the start of the line.

The following example shows the Rule Description section of STARC-1.1.1.1 rule of SpyGlass STARC Policy:




Rule Function Section

The Rule Function section has the associated Perl function, if any.

Rule Registration Section

Every SpyGlass rule is required to be registered using the spyRegisterRule API function that uses the ruleInfo object with the following structure:

struct ruleInfo {int language;char *registeredName;char *aliasName;char *initFuncName;char *execFuncName;char *severity;char *msg;char *msgArgFormat;int weight;char *argList;

Rule NameRule Language

Policy Name

Short Help

Long Help




int condition;ruleInitFuncPtrType initFunc;ruleExecFuncPtrType execFunc;void *attribute;long violationCnt;long nviolations;int debugEnabled;int ruleType;long maxviolperline;long maxviolperfile;long maxviolperrun;int enable;int returnStatus;void *Data;int all_waived;char* policy_name;int severity_label_index;char *exitFuncName;ruleExitFuncPtrType exitFunc;

};

The purpose of various fields in the ruleInfo object that you need to supply are as follows:

NOTE: You should leave all other fields as empty strings:

language Indicates the language to which the rule applies. The possible values of this field are Verilog, VHDL, or Verilog+VHDL. The values are case-insensitive.

registeredName The name under which the rule will be registered by SpyGlass. The rule name must be a string of alphanumerical characters and underscore character.

The rule name is used with the -rules and -ignorerules command-line options to select or deselect the rule for a given SpyGlass analysis run. The rule name appears in all reports and can be used to control waivers, filtering, and other features (see the SpyGlass Predicitive Analyzer User Guide for more details). You can have the




same name for a rule that works on Verilog designs and a rule that works on VHDL design. However, rule names must be unique (case-insensitive) within one language. If you use the same name for more than one rule within a language, the second definition overrides the first definition.

aliasName (Optional) An alternate name for the rule.

Aliases are typically used to identify the rule with some external standard (for example, the relevant section in the RMM) or with a section in an internal standard or HDL coding guidelines.

Alias names need not be unique and may contain spaces. If no alias is required, you can leave this field as an empty string.

execFuncName The name of the exec-function of the corresponding rule-primitive to be called after the design has been read in, in order to check the rule.

You can check the details of the exec-functions of standard rule-primitive in their respective Rule-Primitive Description files.

For some standard rule-primitives, the argument may be an empty string. If you are using custom rule-primitives, the argument must always be supplied (i.e. it should be non-empty).

severity The severity-label you want to associate with the rule.

The severity-label can be any string. Typical examples would be Error, Warning, Info etc. but you can also use numeric or other values.

NOTE: Two severity-labels (waiver and disabled) are handled specially by SpyGlass and should not be used.

msg The message you want associated with the violation.

Many rule-primitives return arguments that can be used within the messages in the same format that would be used in a C printf function. You can change the message associated with a rule by editing the text string, including the message arguments if required. You can check




what arguments are passed to error messages for each function by referring to the reference for standard rule primitives. See The registration argument may alternatively be a Perl variable (for example, $msg). The Perl variable should then define the rule message prior to the spyRuleRegister line.

NOTE: If your message expects a string (%s specification) in a position in which a string argument will not be passed, SpyGlass will probably crash, just as the printf function would if you tried to print a non-string value using %s.

weight (Optional) A weight value you want to associate with the rule. This weight value is useful in computing reusability scores.

argList An argument list for the associated rule-primitive.

Many rule-primitives take an argument list. For example, the name check primitives (veNames for Verilog, vhNames for VHDL) expect the name of a Perl function and the type of object to check. When SpyGlass finds each instance of the defined object (for example, all signals) in the design database, it will extract the name of the object from the database. It will then invoke a Perl callback routine it expects to find as the first element in the Rule argument list and pass the object name to it, expecting the Perl function to check it for validity and return a pass/fail status. Other functions expect a list of names or a numeric value. You can check what arguments are expected by each standard rule-primitive in their respective Rule-Primitive Description files.

condition A rule-running condition.

When you specify the policy using the -policies or -policy


Registering Rules


command-line option, a rule is run or not run as per the following table:

NOTE: With the corresponding policy specified, only the rules with condition value 4 are run even when the -norules command-line option is also specified.

Registering RulesIn order for SpyGlass to check any rules, they must first be made visible to the analysis engine by ‘registering’ them. Once registered, they are then available for checking. This is true both for rules supplied by Atrenta as well as custom rules defined by users. Rules can be registered individually (see Registering Individual Rules), as a group (see Registering Rule Groups), or as a ‘policy’, as shown below:

Condition Value Rule Behavior

0 Rule is permanently switched OFF. You can switch it ON using -rules command-line option.

1 Rule is normally switched ON by default. You can run the rule by specifying this rule or any of ‘containing’ group explicitly with the -rules command-line option.

Rule can be switched OFF by:

• use of the -rules command-line option and not listing this rule or any of ‘containing’ group explicitly.

• use of the -ignorerules command-line option and listing this rule or any of ‘containing’ group for exclusion.

2 Rule is permanently ON and remains unaffected by use of the -rules or -ignorerules command-line options.

3 Rule is permanently ON and runs as early as possible within its design View group. It remains unaffected by use of the -rules or -ignorerules command-line options.

4 Rule is permanently ON and runs as early as possible within its design View group. It remains unaffected by use of the -rules or -ignorerules command-line options.




FIGURE 1. Rule Hierarchy

As can be seen, the same rule can be included in more than once (e.g. Rule 5), and rule groups can include other groups as well as individual rules (Group A included in Group B). SpyGlass will ensure at run-time that if the same rule is registered more than once, it will only be checked once for each instance in the design.

This flexibility in registration allows SpyGlass to be set up to run differing sets of rules at different times in the design process, as well as being able to switch the rule set used based on runtime options. It also allows users, if they so wish, to be able to concentrate on fixing critical design issues associated with a specific rule (e.g. clock domain crossings) without being distracted by other lower priority rules.

The rule registration can be defined in one or more standalone policies (such as those supplied by Atrenta) which are then pointed to by a control file or the rules/groups can be explicitly registered as part of the control file.

Registering Individual Rules

In order to register a rule for use in SpyGlass, the spyRegisterRule call is used with a number of definable arguments.

MultipleRule Decks

Rule Deck BRule Deck A Rule Deck C

Rule Group BRule Group A

Rule 2Rule 1 Rule 3 Rule 4 Rule 5 Rule 6 Rule Group A

Rule 5


Registering Rules


Registering Verilog Only or VHDL Only Rules

The following example shows the rule-registration of a Verilog only rule (STARC-3.2.3.2):

$msg="Bit width mismatch between port '%1' of instance '%3' and its connected net, [Hierarchy '%6'].";spyRegisterRule("Verilog", "STARC-3.2.3.2","BitWidthMismatchPortInst","", "veLintInstConnection","Mandatory", $msg, 10, "", 1);

Here, the rule alias is BitWidthMismatchPortInst, associated rule-primitive is veLintInstConnection, the rule severity-label is Mandatory, and the rule-ordering condition is 1 (that is, the rule is ON by default).

Now, consider the following example that shows the rule description of a VHDL Only rule (STARC-1.1.1.7):

sub vhSrp_1_1_1_7_actLowName {my $name = shift;return 0 if $name !~ /_X$/;return 1;

};

$msg = "Active low signal name '%s' must end with _X";spyRegisterRule("vhdl", "STARC-1.1.1.7", "ActLowName", "",

"vhNames", "Mandatory", $msg, 5, "vhSrp_1_1_1_7_actLowName activelow", 1);

Here, the rule alias is ActLowName, associated rule-primitive is vhNames, the rule severity-label is Mandatory, and the rule-ordering condition is 1 (that is, the rule is ON by default). Also, there is an associated Perl function vhSrp_1_1_1_7_actLowName that is invoked on the signal name with argument activelow.

Registering Language-Independent Rules

The following example shows the rule-registration of a language-independent rule (STARC-1.3.3.4):




$msg = "Reset '%s' is not generated in a separate module at top-level";spyRegisterRule(

"Verilog+vhdl", "STARC-1.3.3.4","GateResetAtTop","vnCheckGatedResetAtTop_Init", "vnCheckGatedResetAtTop","Mandatory", $msg, 10, "", 1);

Here, the rule alias is GateResetAtTop, associated rule-primitive is vnCheckGatedResetAtTop, the rule severity-label is Mandatory, and the rule-ordering condition is 1 (that is, the rule is ON by default). Also, there is an associated initialization function vnCheckGatedResetAtTop_Init.

Registering Rules Separately for Verilog and VHDL

In some cases, a rule checks the same issue for both Verilog and VHDL designs but use different attributes. Then, such rules have the same rule description section but different rule registrations for Verilog and VHDL.

Consider the example of NoTopLogic rule of SpyGlass OpenMORE Policy. The rule has the following rule description section:

=pod+++++++++++++++++++++++++++++++++++++++++++++NoTopLogic Verilog+VHDL OpenMORE*There should be no logic inferred at the top level of the hierarchical design*Logic inferred directly at the top-level of the hierarchical design cannot easily be optimized in synthesis with the remainder of the logic It is better to include any such logic at lower levels in the design.If the design has no hierarchy then this rule will not flag a violation.In Verilog mode, gate and UDP instances will not be treated as hierarchy.=cut+++++++++++++++++++++++++++++++++++++++++++++++++

However, the rule registration section is as follows:

$msg = "Logic inferred at the top level";spyRegisterRule(

"Verilog", "NoTopLogic", "(OpenMORE 5.6.8.1)", "veForbidTopLogicInit", "veForbidTopLogic",

"Guideline", $msg, 5, "", 1);


Registering Rules


$msg = "Logic Inferred at the top level of hierarchy";spyRegisterRule(

"vhdl", "NoTopLogic", "(OpenMORE 5.6.8.1)", "", "vhNoTopLogic","Guideline", $msg, 5, "", 1);

The initialization functions, rule-primitives, and messages used for Verilog and VHDL are different.

Registering Rule Groups

While it is convenient to be able to choose which individual rules you want to run, this method could be cumbersome if you want to run a large set of rules. SpyGlass provides support for this requirement using a concept of “rule groups”. A rule group is simply a set of rules that can be referred to by a single name. You do not need to worry about possible overlaps between groups and/or rules. Before running validation, SpyGlass filters the list you provide to remove duplicate rules allowing you to include the same rule in multiple rule groups.

In order to register a rule group for use in SpyGlass, use the spyRegisterGroup API function as follows:

spyRegisterGroup(<rulegrp-lang>,<rulegrp-name>,<reserved-args>,<rulenameorgrp-list>);

Where

<rulegrp-lang> can be one of the following:

Value Indicates that the rule group works on...

Verilog Verilog Only designs or Verilog portions of Mixed-Language designs

VHDL VHDL Only designs or VHDL portions of Mixed-Language designs

Verilog+VHDL Verilog Only designs, VHDL Only designs, or entire Mixed-Language designs




<rulegrp-name> is a unique string of alphanumerical characters and underscore character. You can define rule groups with same name under all language types.

<reserved-args> is for future use and should be left as an empty string.

<rulenameorgrp-list> is a space-separated list of rule names or rule group names that must be defined before this the spyRegisterGroup API function call.

NOTE: SpyGlass will exit with an error message if a rule group definition results in recursion by including its own group-name in the rule or rule group list.

When you ask for information on rule groups using the -printgroups command-line option, SpyGlass will print the rule group name followed by the names of the rule or rule group contained in the rule group.

The rule groups are also used within the SpyGlass Design Environment to define the structure of the Filter hierarchy for filtering rule messages (in a post-process analysis) or for selecting rules to be checked (in a full interactive session). A well-structured and meaningful set of rule groups within a policy is therefore very important to present a clear, concise hierarchy to users for filtering the design rule checking.

For best support of the SpyGlass Design Environment, it is a requirement that all policies contain a final group to be defined that contains all the rules in that policy. This should include any sub-groups if present but should exclude members of sub-groups. The name of this last registered group should most logically be the name of the policy.

Registering Multiple Severities/Messages for a Rule

SpyGlass provides multi-message support for rules that flag multiple messages. That is, a rule (with the same name) can have multiple messages with different severities.


Registering Rules


The multiple messages/severities of rules are registered using the spyRegisterRuleMessage API function as follows:

spyRegisterRuleMessageLANGUAGE=><language>RULE=><ruleName>MESSAGELABEL=><msgLabel>SEVERITY=><severity>MESSAGETEXT=><msg>WEIGHT=><weight>MESSAGEARG=><msgArgInfo>BUSMERGEINFO=><bmInfo>

The spyRegisterRuleMessage API function takes the following arguments:

<language> (mandatory) indicates the language to which the rule applies. Refer to the language section for more details

<ruleName> (mandatory) indicates the name of the rule as specified in the spyRegisterRule API function.

NOTE: The combination of <language> + <ruleName> uniquely identifies a given spyRegisterRule call. Therefore both need to be specified verbatim, to define the message for the given rule. If no rule is found with the given language, then the corresponding call to spyRegisterRuleMessage API is incorrect, and is ignored with a warning.

<msgLabel> (mandatory) is a string that is used to identify a given message of the rule. Only alpha-numeric message labels without any spaces are supported. In addition, message labels are case sensitive.

NOTE: All messages of a rule should have unique labels. However, across rules, these labels can be common. It is recommended that some meaningful keyword is used as a label value, so that its reference at subsequent stages is easy.

NOTE: If there are two messages of a rule with same labels, then the last label definition is used, and earlier one is ignored with a warning message.

<severity> (mandatory) indicates the severity-label that you want




to associate with the rule. Refer to the severity section for more details.

<msg> (mandatory) indicates the message text given for a rule

<weight> (optional) defines the weight of the message. If the weight value is provided, then the value will be associated with the current message. If the value is not provided, then the weight registered with the spyRegisterRule API will be used.

<msgArgInfo> (optional) defines the message arguments and also the internal type of bus-merging objects. The supported argument types are s, d, f, c, e, l, vn, ve, vs, and vh.

<bmInfo> (optional) defines the information related to bus-merging. It helps in manipulating the type of bus-merging (OW/TW), the bus-merging arguments, the TAG, and the attributes for bus-merging and so on.

The spyRegisterRuleMessage API registers the multiple rule messages. If there are N messages (with different severity) for a rule, then there are as many calls to spyRegisterRuleMessage API, with each call defining one of the messages. In addition, each of these calls associates a unique label with which a message can be referred to later. The arguments associated with the spyRegisterRuleMessage API are key-based and hence position independent.

The spyRegisterRuleMessage API should be called just after the spyRegisterRule API. The severity label and message can be left blank in the spyRegisterRule API, if the same are being defined using the spyRegisterRuleMessage API.

Once the rule messages and their severities have been defined using the spyRegisterRuleMessage API, these should be accessed in rule-cprimitives to flag the desired messages.


Registering Rules



Developing New SpyGlass Rules

General Methodology on Developing New RulesOne of the first instincts that you may have when you want to check for something that SpyGlass does not currently check, is to create a completely new rule. But more often than not, there are a number of easier ways that the required check can be implemented (listed below in order of complexity):

By modifying the arguments and/or the Perl call-back routine to a currently registered rule (see Adapting Atrenta Standard Rules)

Using the SpyGlass Built-In checks (see Using SpyGlass Built-In Checks).

Creating a new rule based on Atrenta standard rule-primitives

By creating a new rule-primitive and creating a rule based on this rule-primitive

This feature is only possible if the optional SpyGlass Rule Builder has been purchased giving full API access to the database.


Searching Atrenta Infrastructure for Rule-Primitives


Searching Atrenta Infrastructure for Rule-PrimitivesWhen looking to create a new rule, the following steps should be taken:

1. Use the spyexplain utility as follows to search the Atrenta standard policies:

spyexplain -k <keyword> -<language> -<policy-name>

(Where <keyword> is any suitable word or partial word relating to the function of the new rule required).

The above command will search the rule names and short help message fields of all the registered rules and output details of those where a match was found. The search mechanism is case-insensitive and matches partial words so this gives a good chance of finding any existing rules that may be similar to the new one required.

2. While there may not be an exact match from the spyexplain utility search, there may well be rules identified that are similar and can be used as a template for creating the new rule. To determine this, you should look in the current policies to examine the complete rule description (as opposed to the short description on which the spyexplain utility searches).

3. If no similar rule is found, look in the list of standard rule-primitives for one that provides the necessary information.

The Rule-Primitive Description files provide all the necessary information on the rule-primitives, including a description of the rule-primitive, and a list of the arguments and messages handled by the rule-primitive. In some cases, a new Perl routine can then be written, using the arguments and message handling described in the corresponding rule-primitive description files.

When searching the rule-primitive description files, there may be more than one possible rule-primitive that will address the task required. Early rule-primitives were written with one dedicated function in mind (for example, vhNameLength, vhSigName, vhInstName, vhConstName, etc.) but these rule-primitives have




been superseded by more generic functions (for example, vhNames). The later rule-primitives support Perl callback routines with registration arguments to select signals, constants, instances etc. They are therefore more powerful and can cover a number of objects with similar routines.

Adapting Atrenta Standard Rules

Some requirements for a company-specific rule can be met by adapting one of the standard rules supplied by Atrenta. This is particularly true for rules that check items such as line length, name characteristics, etc.

For example, if the company guideline for maximum length of lines in RTL code is set at 80 characters, it is possible to modify the Atrenta rule (which is set to 132 characters or the value of line_max_length rule parameter). By searching the supplied policies (using spyexplain utility with line keyword), the following rule can be found in the OpenMORE policy:

LineLength Verilog+VHDL OpenMORE*Keep line-length consistently to 132 characters or less*Longer lines can be difficult to read on small terminals.The rule parameter "line_max_length" can be used to change the defaultvalue for the maximum allowed line-length.=cut++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++$LineLength_msg = "Line length is more than $line_max_length characters";spyRegisterRule("Verilog", "LineLength", "(OpenMORE 5.2.7.1)", "",

"velexCheckLine", "Guideline", $LineLength_msg, 2,"LineLength $line_max_length", 1);

$LineLength_msg = "Line length is more than $line_max_length characters";spyRegisterRule("vhdl", "LineLength", "(OpenMORE 5.2.7.1)", "",

"vhlexCheckLine", "Guideline", $LineLength_msg, 2,"LineLength $line_max_length", 1);

Now, you want to restrict the users to maximum line length of 80


Searching Atrenta Infrastructure for Rule-Primitives


characters only. Create a new rule named myLineLength as follows:

myLineLength Verilog+VHDL OpenMORE*Keep line-length consistently to 80 characters or less*Company design guidelines require that the RTL code lines shouldnot be longer than 80 characters.Longer lines can be difficult to read on small terminals.=cut+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++$LineLength_msg = "Line length is more than 80 characters";spyRegisterRule("Verilog", "myLineLength", "(OpenMORE 5.2.7.1)", "", "velexCheckLine", "Guideline", $LineLength_msg, 2,

"LineLength 80", 1);

$LineLength_msg = "Line length is more than 80 characters";spyRegisterRule("vhdl", "myLineLength", "(OpenMORE 5.2.7.1)", "", "vhlexCheckLine", "Guideline", $LineLength_msg, 2,

"LineLength 80", 1);

This new myLineLength rule will flag RTL code lines that are longer than 80 characters.

Using SpyGlass Built-In Checks

While analyzing designs, SpyGlass first checks for source code for HDL syntax violations before attempting any rule checks. Any syntax violations detected are reported in the Violation Database as syntax errors (with names STXxxx) or syntax warnings (reported as WRNxxx) where xxx refers to the message number. See the SpyGlass Built-In Messages Reference for more details of these messages.

Spyglass aborts if it encounters any non-recoverable error in any of the design files with the following message:

***Syntax Errors detected - RULE CHECKING ABORTED***.

An STX message means that the design is syntactically wrong and cannot be analyzed further. These messages are reported with severity “Syntax” in the Violation Database. STX error checks are always ON,




that is, they will always be triggered and cannot be waived or ignored to ensure that any fatal and non-recoverable syntax errors will always be reported.

WRN messages do not refer to syntax errors but rather violations of the built-in rule checks.

Most of the WRN messages are mapped to rules in LINT policy. For example, the W442a rule works on the WRN144 built-in message:

=pod++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++W442a Verilog lint*The specified reset sequence is not synthesizable. First statement in block mustbe an if statement*Only certain forms of asynchronous reset are recognized by synthesis tools. The first statement after the sensitivity list on the always block must be an 'if' statement.=cut++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++$msg = "First statement in asynchronous block must be an 'if'";spyRegisterRule("Verilog", "W442a", "", "veBuiltInInit", "", "Warning", $msg, 5, "144", 1);

Thus, you can suppress WRN144 messages by specifying W442a rule with the –ignorerules command-line option. Or, you can limit the number of WRN144 messages by specifying W442a rule with the -lvpr command-line option.

For built-in warning messages not covered, you can create a new rule as follows to control a particular built-in warning message:

SpyRegisterRule (“Verilog”, “myWRNnnn”, “”, “veBuiltInInit”, “”, “Warning”, “Massage for myWRNnnn”, 0, “nnn”, 1);

Where nnn is the Built-in Warning Message number for which you are creating a new rule. Now, you can turn on or off reporting of the WRNnnn as required.

NOTE: For rules based on built-in checks, the initFuncName is veBuiltInInit, there is no exec-function and thus the


Creating New Rules


execFuncName field is empty, and the specific Built-In Warning Message number is the value of argList field.

Now, if –ignorerules myWRNnnn is supplied at the command-line, SpyGlass will not check myWRNnnn; it will also recognize that myWRNnnn is a rename of the default WRNnnn and will also not check that rule, irrespective of whether the myWRNnnn rule is enabled or disabled.

The above method of mapping rules does not hold for STX errors. The alias name and severity of a syntax error cannot be overridden if a matching custom rule is defined using the same Built-In function. Defining a new rule, myRule, using the same Built-In as STX123 say, will force myRule to have an alias of STX123 and a severity of Syntax. When myRule is enabled, it will be checked but STX123 will not (SpyGlass recognizes them as the same check and will only run the user defined one). Attempting to turn off myRule using -ignorerules myRule will disable myRule but SpyGlass will then run the default STX123 rule in its place as it recognizes that syntax checks must always be run.

Creating New RulesThe following example explains the process of creating new rules and registering groups. The aim is to define two new Verilog rules, the first to ensure that all synchronous elements are reset and the second to check that all clock signals are named clock or have names ending in _clk. For both rules, it is assumed for the purpose of the example that no rules already exist to do a similar function (and therefore there are no rules to adapt). We will first define two rules, ResetAll and ClkName, then group those two rules under the name myRuleGroup.

Both rules use built-in rule-primitives. By searching the Rule-Primitive Description files for primitive functions concerning Reset, the veResetLD function is found with the following documentation:

C-PRIMITIVE NAME : veResetLDSUPPORT : Production




LANGUAGE : verilogPURPOSE : Function to check that all storage elements are reset as specifiedDESIGN VIEW : RTLDU (RTL)LIBRARY NAME : libCoreRulesSEARCH KEYWORD LIST : reset related checkSPYGLASS CONSTRAINT INFORMATION : NoneDETAILED DESCRIPTION : This primitive checks that all storage elements are reset as specified. It reports a violation at the assignment statement within edge-triggered block for which signal appears on left-hand side of assignment (ie. location which causes signal to be registered).C-PRIMITIVE ARGUMENTS : Argument Format: <type_list> Argument Description: <type_list>: One or more of the following: any all registered elements must be reset synch all registered elements must be synchronously reset asynch all registered elements must be asynchronously reset globalsynch require synch reset if any come directly from top-level portPERL CALLBACK SUBROUTINE CUSTOMIZATION : NoneOUTPUT MESSAGE ARGUMENTS : (%s) Name of signal that is not reset as specified (%s) Name of the corresponding module, in case of C-PRIMITIVE ARGUMENT "globalsynch"OUTPUT MESSAGE LOCATION : At the assignment statement within edge-triggered block for which signal appears on left-hand side of assignment (ie. location which causes signal to be registered).

OUTPUT SCHEMATIC : Not ApplicableEXAMPLES :


Creating New Rules


1. This example illustrates how to check that all storage elements are reset as specified $msg = "Signal '%s' is not reset as specified"; spyRegisterRule( "verilog", "chkreset", "", "veResetLDInit","veResetLD", "Guideline", $msg, 5, "any", 1); The following Verilog code will give violation in this case: module synctop(d,clk1,async); input d, clk1; output async; reg async; reg a; wire buf_clk = clk1; always @(posedge buf_clk) begin a <= d; end endmodule

REVISION HISTORY : Jan-22-2003/SPYSO 3.3/Spyglass 3.3 : Initial Draft Oct-28-2003/SPYSO 3.4/Spyglass 3.4.1 :

No violation will be reported if all the bits of a vector are reset.

This documentation shows that there is only an execution function (veResetLD) to the rule-primitive (since it lists only veResetLD under the C-PRIMITIVE NAME section).

The possible arguments for use with veResetLD are listed under the C-PRIMITIVE ARGUMENTS section in the documentation, allowing the rule-primitive to be easily used with a variety of different types of design objects. In our example rule, we will choose to use the any argument in order that all registers are checked.

The DETAILED DESCRIPTION section has the description of the rule primitive function. The OUTPUT MESSAGE ARGUMENTS and OUTPUT MESSAGE LOCATION sections list the various arguments




(if any) that are provided by the C rule primitive for inclusion in the error message and the location (in the original HDL source) where the violation message will be generated. We will use the string representing the name of the signal in our error message.

Here is the new ResetAll rule (ignoring the rule documentation in pod/cut):

$msg = “Signal %s is not reset”;spyRegisterRule (“Verilog”, “ResetAll”, “”, “”, “veResetLD”,

“Error”, $msg, 10, “any”, 1);

The rule registration defines, in order:

Verilog - The rule will be registered for Verilog

ResetAll - The rule name.

“” – There is no alias for this rule.

“” – There is no initialization function for this rule

“veResetLD” – The execution function for the rule-primitive that we extracted from the documentation above.

“Error” – We have chosen to give our rule a severity-label of “Error”.

$msg - If the ResetAll rule is violated (that is, veResetLD detects an error on one of the registers in the design), the message to be output in the report file is $msg. The actual content of $msg is defined in the rule registration prior to the rule itself, and will appear in the report as:

Signal %s is not reset”

where %s represents a string and will be replaced by the name of the violating signal as defined in the OUTPUT MESSAGE ARGUMENTS section of the veResetLD documentation listed above. In this case, the rule provides one string argument to your violation message, which names the violating signal when you want to use the any rule argument.

Depending on the specific rule-primitive, there may be none, one or


Creating New Rules


more than one Output Message Arguments provided and these can be used when creating as detailed an error message as required. The error message can obviously be created in a non-English language by changing the $msg statement in the rule registration.

10 – As it has a severity of Error, we have chosen to give the ResetAll rule a weight of 10 (only useful for scoring purposes). These scores are typically used when the –report more or -report score options are used when running SpyGlass (see the SpyGlass Predicitive AnalyzerUser Guide for more details).

“any” – this is the argument for the veResetLD rule-primitive to ensure checks are run on all registered elements in the design (see the C-PRIMITIVE ARGUMENTS section for the full listing of arguments for the primitive).

1 - The final argument to the ResetAll rule enables the registration. If you wanted to keep the code in your policy but temporarily dis-able the registration, you would change this value to 0. This could also be a Perl variable (e.g. $EnableResetAll) that is set to 1 or 0 elsewhere in the policy or via command line options (see Adding Command-line Options to SpyGlass Rules).

The objective of the second rule is to check that clock signal names are all either clock or names that end in _clk.

Again, searching the Rule-Primitive Description files for suitable primitives reveals the veNamesLD primitive with the following information:

C-PRIMITIVE NAME : veNamesLD

SUPPORT : Production

LANGUAGE : verilog

PURPOSE : General purpose function for checking the names and other attributes of various objects.

DESIGN VIEW : RTLDULIST (RTL)




LIBRARY NAME : libCoreRules

SEARCH KEYWORD LIST : naming convention

SPYGLASS CONSTRAINT INFORMATION : None

DETAILED DESCRIPTION : This C-Primitive performs general purpose checks on names of various design construct. It checks the naming conventions for various objects by passing the object to the perl function and depending upon the return value of perl callback, it flags violation.

C-PRIMITIVE ARGUMENTS : Argument Format: <perl-fn> <type-list> [-limitviol <num>] Argument Description: <perl-fn> : A user-defined Perl callback. Name of perl call-back sub-routine. (see section 'PERL CALLBACK SUBROUTINE CUSTOMIZATION' for more detail) <type-list> : A list of any of the following names: activelow all active low signal names (subset of signal). Calls Perl function with args: name of object, "activelow", isCellDefined activelow_orig all active low signal names (subset of signal). This uses old specification to retain back-ward compatibility. Calls Perl function with args: name of object, "activelow", isCellDefined allinstance all module instances and gate instance.Registering a rule with allinstance is equivalent to registering a rule with instance and gateinstance both. Calls Perl function with args: name of object, "instance", name of instance master module or gate type, name of the module containing the instance, isCellDefined bus_port


Creating New Rules


name of all multi-bit ports clock all clock signal names (subset of signal). Calls Perl function with args: name of object, "clock", isCellDefined file all file names. Calls Perl function with args: file-name, "file", name of first module in file file-module all file names. Calls Perl function with args: file-name, "file-module", list of all modules in file function all function names. Calls Perl function with args: name of object, "function", return type, isCellDefined gateinstance all gate instance name. Calls Perl function with args: name of object, "instance", gate type as a string, isCellDefined include all include file names. Calls Perl function with args: include-file-name, "include", name of file containing include input_port input port names. Calls Perl function with args: name of object, "input_port", isCellDefined instance all instance names. Calls Perl function with args: name of object, "instance", name of instance master module, name of the module containing the instance, isCellDefined integer all variable names of type integer. Calls Perl function with args: name of object, "integer", isCellDefined io_port inout port names. Calls Perl function with args: name of object, "io_port", isCellDefined label all labels (named block names). Calls Perl function with args: name of object, "label", isCellDefined macro all macro names. Calls Perl function with args: name of object, "macro"




module all module names. Calls Perl function with args: name of object, "module", isCellDefined topmodule all top module names. Calls Perl function with args: name of object, "topmodule", isCellDefined submodule all sub module names. Calls Perl function with args: name of object, "submodule", isCellDefined ncoutputsignal all unconnected output signals (subset of signal). Calls Perl function with args: name of object, "ncoutputsignal" nextstate all state machine signals (subset of signal). Calls Perl function with args: name of object, "nextstate", isCellDefined non_port names of all non-port signals. The constructs checked by this argument is: wire, reg, real, integer, and time. output_port output port names. Calls Perl function with args: name of object, "output_port", isCellDefined topport all top level port names. Calls Perl function with args: name of object, "topport", isCellDefined parameter all parameter names. Calls Perl function with args: name of object, "parameter", isCellDefined localparameter all local parameter names. Calls Perl function with args: name of object, "localparameter", isCellDefined paramforvar all signals which are parameterized (subset of signal). Calls Perl function with args: name of object, "paramforvar" port all port names. Calls Perl function with args: name of object, "port", isCellDefined real all variable names of type real. Calls Perl function with args: name of object, "real", isCellDefined register


Creating New Rules


all signal names. Calls Perl function with args: name of object, "register", isCellDefined signal all signal names(wire + reg). Calls Perl function with args: name of object, "signal", isCellDefined slatch all synchronous latch names (latch enabled by a clock signal). Does not call the perl function. Simply reports presence of latch task all task names. Calls Perl function with args: name of object, "task", isCellDefined time all variable names of type time. Calls Perl function with args: name of object, "time", isCellDefined tristate all tristate signal names (subset of signal). Calls Perl function with args: name of object, "tristate", isCellDefined udp all user-defined primitive names. Calls Perl function with args: name of object, "udp", isCellDefined variable all variable names (non-signal variable). Calls Perl function with args: name of object, "variable", isCellDefined wire all wire names. Calls Perl function with args: name of object, "wire", isCellDefined -limitviol this requires one argument to follow it, and can be used to limit the number of violations reported in the design. If the next argument is "all", all violations are reported. If it is an integer N, only N violations for the corresponding rule are flagged.

PERL CALLBACK SUBROUTINE CUSTOMIZATION: Arguments passed to perl callback: i Name of the object ii Type of the object iii "1" if the object appears inside a `celldefine and "0" otherwise. iv "1" if top level, "0" otherwise, applicable to only "tristate" argument




v "1" if port net, "0" otherwise, applicable to only "tristate" argument

The Perl function should return 0 for violation case, 1 for no violation.

OUTPUT MESSAGE ARGUMENTS: (%s) Name of the violating object OUTPUT MESSAGE LOCATION: Violation is reported at the place the object is defined, otherwise at the first line of the file. OUTPUT SCHEMATIC: Not Applicable EXAMPLES : 1. This example illustrates how to check naming convention of macros and parameters. sub veConstName { my $name = shift; return 1 if ( $name !~ /^[A-Z][A-Z0-9_]*\$/ and /^.{1,8}\$/ and not /__/); return 0; } $msg = "Constant '%s' does not follow recommended naming convention"; spyRegisterRule( "Verilog", "ConstName", "", "", "veNamesLD", "Guideline", $msg, 2, "veConstName macro parameter", 1); 2. Refer Atrenta Policy : lint, rule W294

REVISION HISTORY : Jan-17-2003/SPYSO 3.3/Spyglass 3.3 : Initial Draft April-12-2003/SPYSO 3.5.0/Spyglass 3.5 : Aded argument localparameter

The veNamesLD rule-primitive uses a Perl callback for checking the


Creating New Rules


names. As listed in the veNamesLD documentation, the rule-primitive takes two mandatory arguments — the name of a Perl function and the object types to be checked with this particular implementation of veNamesLD. It is obviously possible to have many rules in the same policy that use veNamesLD but for checking a different object naming convention due to differing arguments in the <type-list>. In this case, we are looking at clock signal names, so the second argument is “clock”. The first argument defines the name of the Perl callback which will be used to check the clock names.

Thus, the rule registration for ClkName rule is as follows:

sub ck_check {my $name = shift;if ( $name =~ /^clock/ or $name =~ /_clk$/) {

return 1;}else {

return 0;}

}

$msg = "Clock name '%s' does not follow the naming convention”;spyRegisterRule("Verilog", "ClkName", "", "veNames_Init", "veNames", "Guideline", $msg, 2, "ck_check clock", 1);

The first statement in the ck_check function shifts the clock name off the argument stack. The if-else statement tests the name against the two alternatives allowed by the naming convention.

If the name does not meet the objective, the ck_check function returns 0, signalling a violation. If one of the regular expression checks passes, the ck_check function returns 1, signalling no violation.

NOTE: All Perl call-backs must return either 0 or 1. Results are unpredictable if you do not return a value and therefore the success path through the Perl function must always end in “1;”. For example, the following callback will have unpredictable behavior if the $name value does not match any of the conditions:




sub bad_check {my $name = shift;if ( $name =~ /ck/ ) {return 0 if $name != /end$/;

} elseif ( $name =~ /clk/ ) {return 0 if $name != /^start/;

}}

For our ClkName rule, we create the message variable $msg that will include the name of the failing clock signal in place of the %s variable returned by the veNamesLD primitive (and defined in OUTPUT MESSAGE ARGUMENTS section of the documentation).

Finally, having registered the individual rules, we register myRuleGroup, grouping our new rules together:

# myRuleGroup: A group containing ResetAll and ClkNamespyRegisterGroup(“Verilog”,”MyRuleGroup”, “”, “ResetAll ClkName”);

This call simply defines a group called myRuleGroup as a Verilog group and puts rules ResetAll and ClkName into that group. Note that this list of names in a group can itself contain group-names.

Creating Rules by Copying Existing RulesWhile creating your custom policy, you may find that an existing rule in an Atrenta standard policy meets your requirements exactly. However, you may need to create the rule with a different name as per your corporate standards.

One way to create this new rule is to copy the entire description from the Atrenta standard policy file to your custom policy file and rename the registeredname field as required. However, the main drawback of this approach is that any change in the original rule over the SpyGlass releases needs to tracked and manually incorporated.

You can use the Perl API function spyCreateRuleByCopy that links your custom rule to an existing rule in an Atrenta standard policy.


Creating Rules by Copying Existing Rules


The syntax to use the spyCreateRuleByCopy function is as follows:

spyCreateRuleByCopy (<NewRuleName>,<OriginalRulePolicyName>::<OriginalRuleName>

);

Where <NewRuleName> is the name of the rule you are creating, <OriginalRulePolicyName> is the mnemonic of the Atrenta Standard Policy, and <OriginalRuleName> is the name of the Atrenta Standard Policy rule you want to link to.

The spyCreateRuleByCopy function creates a copy of the original rule at the runtime. Therefore, your custom rule will always be in sync with the original rule.

For example, you want to create a rule named ABCDI467 inside your custom policy file named ABCD-policy.pl by linking it to the W467 rule in the Lint policy (controlled by the lint-policy.pl ruledeck). Create the following call in your custom policy file:

spyCreateRuleByCopy(“ABCD467”, “lint::W467”);

The spyCreateRuleByCopy function returns 1 if new rule has been created successfully. Otherwise, it returns 0 (for example, when the names are incorrect or the rule does not exist in the specified policy).

The spyCreateRuleByCopy function works as follows:

1. The spyCreateRuleByCopy function has no effect on the behavior/functioning of the original rule which continues to work in the same manner as before.

2. The new rule can be used in exactly the same manner as any other normal rule. Thus, it can be overloaded to customize its arguments or it can be a part of a rule group. See the SpyGlass Predictive Analyzer User Guide for details of overloading a rule.




3. If the original rule has separate registration for verilog and vhdl language, then the spyCreateRuleByCopy function create separate verilog and vhdl language copies of the original rule.

In the above example, as the W467 rule is registered separately for verilog and vhdl (see the mixedlint.pl file), then there will be two copies of the ABCD467 rule for verilog (same as the W467 verilog registration) and vhdl (same as the W467 vhdl registration). As one copy per language is created, it is the same behavior as the original rule independent of the language.

In case, you want to overload such rules, you need to overload the two versions (the Verilog version and the VHDL version) separately.

4. The new rule requires the following elements from the original rule policy file:

Requires ALL licenses to run the specified Atrenta standard policy

Loads ALL SpyGlass-compatible library files (.spyso files) of the specified Atrenta standard policy.

Runs ALL pre-requisite rules in the specified Atrenta standard policy

ALL rule parameters in the specified Atrenta standard policy are available.

Currently, it is not possible to locate the specific requirements of the original rule. Hence, all requirements for the specified Atrenta standard policy should be available.

5. Recursive calls to the spyCreateRuleByCopy function are allowed.

6. You can also create a rule description section for the new rule (=pod=cut section). Otherwise, the rule description of the original rule is applicable (from spyexplain utility or in the SpyGlass Design Environment).


Adding Command-line Options to SpyGlass Rules


Displaying Original Rule Name

In the SpyGlass Design Environment, the rule messages in the Message/Filter/Waiver Tree only show the new name of the custom rule that was created using the spyCreateRuleByCopy function, as described above. However, to display the name of the original rule alongwith the new name of the custom rule, you can specify “1” as an additional argument (optional) in the spyCreateRuleByCopy function as in the following example:

spyCreateRuleByCopy (my_rule,lint::W18,1

);

The above function creates the “my_rule” rule as a copy of the “W18” rule of the Lint policy and the additional argument 1 enables the display of the original rule name (W18) alongwith the new rule name (my_rule) in Message/Filter/Waiver Tree.

Adding Command-line Options to SpyGlass RulesSpyGlass automatically interprets a number of command-line options — see the summary of command-line options in the SpyGlass Predictive Analyzer User Guide.

When SpyGlass encounters a command-line option that is not a standard command-line option or a rule parameter (registered with spyParameter API function call in the Ruledeck file), SpyGlass creates a Perl (scalar) variable for further use. SpyGlass also issues a warning message for such command-line options.

If the option is in the following form:

-<option-name>

A (scalar) variable with that name, but with an undefined value, will be created. For example, if you provide the option -myoption, a variable called $myoption will be created, with value 'undef'.




If the option is in the following form:

-<option-name>=<option-value> (Note: no spaces!)

A (scalar) variable with the option name will be created and set to the specified option value. For example, if you provide the option -myoption=3, a variable called $myoption will be created, with value 3.

This mechanism provides you a method to arbitrarily extend command-line control. Suppose you want to define 'profiles' for certain types of rule checking. You might have one profile for one type of design and another profile for another type. As a simple example, suppose in the first profile you want to limit line-lengths to 72 characters, but in the second profile, line-lengths up to 80 characters are OK:

You can define this control using an option -profile=type1 or -profile=type2:

if ( !defined $profile ) { $profile = "type1"; }if ( $profile eq "type1" ) { $maxlinelength = 72; }else { $maxlinelength = 80; }...spyRegisterRule("Verilog","LineLength","", "veLineLength_Init","",

"Error","Line too long",10,"$maxlinelength",1);

The first statement provides a default, in case the option was not specified. The subsequent statements set a variable, based on the value of the option. Further on in the file, when we are registering the LineLength rule, we set the parameter for that rule (maximum number of characters) equal to that variable.

Arrays can also be passed as command line options in the same manner. If the command line option -myoption='a b c d' is used with SpyGlass, a scalar, $myoption, will be created with a value ‘a b c d’. The array can be built within a rule using the standard Perl split function:

if ( !defined $myoption ) {@optionlist = split (//.$myoption);

}


Changing SpyGlass Rule Usage information


NOTE: While the method described above is supported, it is recommended that you use the spyParameter API function call in the Ruledeck file to register required command-line options.

Changing SpyGlass Rule Usage informationIf SpyGlass is invoked with incorrect or missing arguments, it will print a "usage" summary of options in a form familiar to Unix users. It is possible to change to the information that is printed in this case. Add a simple text file, called spyglass.hlp, to the <your-inst-dir>/SPYGLASS_HOME/auxi directory. If this file exists, the contents of the file will be printed in all cases where a usage message would normally be printed.

Specifying Obsolete RulesYou can use the spyObsoleteRule API to declare any obsolete rule and specify alternate rule (if any). The syntax of the spyObsoleteRule API is given below:

spyObsoleteRule(“<obsolete_rule>”,“<alternate_rule>”);

OR

spyObsoleteRule(“<obsolete_rule>”, ““);

Where

<obsolete_rule> argument is the name of the old rule that has to be deprecated.

<alternate_rule> is the second argument and specifies the name of the new rule that should be used in place of the old rule. The <alternate_rule> argument is optional, and you may just specify an empty string (““) in place of this argument, so that SpyGlass just ignores the old rule (specified as the first argument).

For example, if you use the spyObsoleteRule API as given below:




spyObsoleteRule(“Clk_Gen12”,””);

Then, specifying the spygalss command as:

spyglass -batch -policy=lint -rule=Clk_Gen12

will display the following warning message:

WARNING [124] Ignoring obsolete 'Clk_Gen12' rule.

Consider another example of using spyObsoleteRule API, where the Clk_Gen16 rule is made obsolete:

spyObsoleteRule(“Clk_gen16”, “SDCPARSE”);

Now specifying the spyglass command as given below:

spyglass -batch -policy=lint -rule=Clk_Gen12

Displays a warning message for the obsolete rule:

WARNING [123] Running 'SDCPARSE' rule instead of obsolete 'Clk_Gen16' rule.


Specifying Obsolete Rules



Creating Custom Reports

OverviewBesides the standard reports, SpyGlass allows you to create your own custom reports.

These custom reports can be any of the following:

Custom reports for Atrenta standard policies

Custom reports for your custom policies.

These custom reports can be based on the message information available in the SpyGlass Violation Database.

Custom Report ConceptsA SpyGlass custom report design typically has the following:

1. A spyRegisterReportGenerator function call that registers your custom report.

2. A Perl function that generates the report.


Custom Report Concepts


The custom report design can be arranged as follows:

Both the spyRegisterReportGenerator function call and the report function in the main policy file

The spyRegisterReportGenerator function call and the report function in a separate Perl file that is “required” in the main policy file.

The above schemes require access to the main policy file and thus are generally applicable when you are creating a custom report for your own custom policy.

The spyRegisterReportGenerator function call and the report function in a separate Perl file that is named in the standard custom policy file naming convention (<report-name>-sgreport.pl).

The above scheme does not require access to the main policy file and thus is generally applicable for all types of custom reports. For example, you want to create a report that checks the information generated by the SpyGlass Lint Policy and the SpyGlass OpenMORE Policy. Then, design your report generator in a file named say, myLOMReport-sgReport.pl. While rule-checking, supply the directory containing this file using the -I command-line option and -report=myLOMReport (if working in the batch mode).

A typical SpyGlass report generator function should read the Violation database and print some form of report. You can create individual custom reports in separate <report-name>-sgreport.pl file, and specify their path using -I option. If multiple reports are specified using multiple -report options, then their respective report generator file is loaded, and corresponding report generator function is called to generate the report.

Alternatively, if a report is needed for a particular custom policy, then you can create custom reports in a single file and load that file in <custom-policy-name>-policy.pl file using the require command.




The spyRegisterReportGenerator functionThe syntax of using the spyRegisterReportGenerator function is as follows:

spyRegisterReportGenerator("<report-name>", "<init-function>","<exec-function>","<output-name>"):

In detail, the arguments are as follows:

<report-name>: This is the name you want to use to select the report using the –report <report-name> SpyGlass option or in the Report menu of the SpyGlass Design Environment.

<init-function>: This is a reserved argument.

<exec-function>: This is the name of the Perl function you have written that actually generates the report.

<output-name>: This is the actual report file name which can be different from the report name.

The following example shows the registration of a report named myReport that is created by the f_myReport function:

spyRegisterReportGenerator("myReport", "", "f_myReport", "");

Creating Report Generator FunctionsSpyGlass Report Generator functions are standard Perl functions with the following arguments:


Reading VDB Rule Message Information


You need to process the Violation Database file which comes as $_[1], and print the report to output file $_[2]. The processing of Violation Database file is described in the next section.

Reading VDB Rule Message InformationWhen SpyGlass analyzes a design, it writes the rule message information to a Violation Database file (.vdb file) in a specific format as in the following examples:

...W120@@@@Warning@@test1.vhd@@21@@11@@10@@The signal ‘signalA’ is not used.W120@@@@Warning@@test1.vhd@@22@@11@@10@@The signal ‘signalB’ is not used.W123@@@@Warning@@test1.vhd@@21@@11@@10@@The signal ‘signalA’ is not set.W123@@@@Warning@@test1.vhd@@22@@11@@10@@The signal ‘signalB’ is not set....

Each rule message line represents one rule message and contains several fields. These fields are separated by VDB delimiter, which is by default @@, unless it has been overridden during SpyGlass run.

For custom reports, refer to Perl variable $::vdb_delimiter, which is set to active VDB delimiter in the current run. The various message fields which are separated by $::vdb_delimiter, appear in the following order:

Name of the rule violated

Alias-name for the rule violated

Severity for the rule violated.

Name of the file in which the rule-violation was found

Variable Name Points to...

$_[0] Reserved

$_[1] Name of the Violation Database file

$_[2] Name of the output report file




Line number in that file at which the rule-violation was found

Column number in that file at which the rule-violation was found (this field is not yet supported)

Rule-weight for the rule violated

Rule Message associated with the rule-violation

You can easily traverse the rule message lines in the Violation Database file as in the following example:

sub myReportFunc {my $vdb = $_[1];open(IN,”<$vdb”) or die “Could not open VDB file $vdb for read \n”;while (<IN>) {

@fields = split(/$::vdb_delimiter/);...do something with fields}

You can also create different named fields for each part of the rule message as in the following example:

sub myReportFunc {my $vdb = $_[1];open(IN,”<$vdb”) or die “Could not open VDB file $vdb for read \n”;while (<IN>) {

{$rule,$alias,$severity,$file,$line,$col,$weight,$msg} = split(/$::vdb_delimiter/);

...do something with fields}

A Report Generator ExampleHere is an example of a simple report that prints information about rules only if they have "Error" severity:

spyRegisterReportGenerator (“OnlyErrors”, ””, ”error_generator”);

sub error_generator { my $vdb = $_[1]; my $out = $_[2]; my $violId = 0;


A Report Generator Example


spyDumpFileHeader($vdb,"Error" ,$out,""); open(IN, $vdb ) or die "Could not open VDB file '$vdb' for reading\n"; open(OUT, ">>$out") || die "Could not open Output file '$out' for writing\n"; select(OUT);

while (<IN>) { next if (/^#/); $violId++; next if spyViolationIsWaived($violId); #skip waived violation

chomp; ($rule,$alias,$severity,$file,$line,$col,$wt,$msg) = split(/$::vdb_delimiter/); next if $severity ne "Error" ; print "rule: $rule, file: $file, error: $msg\n" ; }

close(OUT); select(STDOUT); close(IN);

In this case, we first register the report, then define the report function. The report will be generated when the user invokes SpyGlass with the –report OnlyErrors command line option, and the Perl function called to generate the report is called error_generator.

Among the arguments passed to error_generator, $_[1] contains the name of the violation database. The spyDumpFileHeader($vdb,"error" ,$out,"") function generates a summary header on top of the report. It also generates some internal data structures so that the spyViolationIsWaived API works correctly. The spyDumpFileHeader function takes the following arguments:

VDB filename

Report name

Output filename




The last argument is always an empty string.

The report generator function then opens the VDB file and reads a line at a time. The output file is opened as specified in $_[2] argument, and the select(OUT) command ensures that the generated information is stored in the output file handle OUT.

The statement next if (/^#)skips over lines in the VDB file, which do not represent the rule messages (that is, the lines that start with the # character).

Subsequently, the spyViolationIsWaived API is called, which specifies whether a given message is waived. It takes an integer argument (a running positive number from 1 to the number of messages in VDB file), which is the violation ID. This statement skips over any message that has been waived using the waive command.

The chomp Perl function trims the newline from the end of the line, then the line is split into fields based on $::vdb_delimiter.

The rest of the statements check whether the rule message matches the filtering criteria (that is, whether it is an error or not). Then the messages that meet the criteria are printed.

Please note that a call to print here will print the output in selected file handle, that is OUT (as specified using the select(OUT)function call).

Ensure that you close both the open VDB and output files. Further, the output handle needs to be reset to screen dump before exiting. Therefore, specify the select(STDOUT) function call before exiting.

NOTE: While developing your custom reports, you may like to study the design of Atrenta standard reports available in the <your-inst-dir>/ SPYGLASS_HOME/auxi/reports.pl file.

Please do not directly use the functions present in the <your-inst-dir>/SPYGLASS_HOME/ auxi/reports.pl file as these functions are not checked for backward compatibility during SpyGlass release and may change without prior notification. Instead, identify the functions you want to


A Report Generator Example


use, and replicate them (with changed function names and global variable names) in your custom report generator.


Overloading SpyGlass Policies

IntroductionThe Atrenta® SpyGlass® Predictive Analyzer provides the feature to overload a policy to meet local preferences of user base. This feature is typically required when you want to use an Atrenta-standard policy but with certain customizations such as different severity-labels, short description, long description, alias name, etc.

NOTE: The rule-checking results with overloaded policies may be different from results from normal policies.

There are two overloaded policy features:

Single overload feature

The Single overload feature allows you to create and use a single overload for a policy.

Named overloads feature

You can also create and use multiple named overloads for each policy.


Single Policy Overload Feature



Using the SpyGlass Design Environment

Customizing Rules

To customize rules in the SpyGlass Design Environment, follow these steps:

1. Set the Policy Customization setting to On in the Misc Page of the Tools > Preferences... menu option.

2. Choose the Setup > Policies/Rules/Parameters... menu option.

The Policies/Rules/Parameters Selection window appears.

3. Activate the policy that you want to overload, if not already activated.

4. To overload a rule, right-click on the rule description and select the Customize This Rule... context menu option.

The Rule Customization window appears as in the following example:




FIGURE 1. Rule Customization Window

5. Customize the rule settings using the following:

• Lock Rule

You can select the rule to be always run (Lock On), or never run (Lock Off), or user-selectable (Selectable). By default, all rules are set as user-selectable (Selectable).

When you lock rules or parameters and save your settings as a template, the locked template file should be saved with extension .spc rather than the usual .spq extension. The locked rule information is not saved with templates having .spq extension.

• Alias

You can modify the rule alias.

• Severity

You can modify the rule severity label. Then, messages for this rule will be counted under the new rule severity label.

Use the Severity Label selector to select the new Severity Label




for the rule.

• Weight

You can modify the rule weight.

• Message Label

The message label is a string that is used to identify the different characteristics (such as message, severity, and weight) of a rule having multiple severities.

You can modify a rule to have different messages having same or different severities.

• Condition

You can modify the rule condition.

• Message

You can modify the rule message. However, you should understand the values returned by the corresponding rule-primitive (shown as %s, %d, %1, %2 etc.) to form meaningful messages.

• Short Help and Long Help

You can also modify the rule’s short description and long description as required.

To revert to the rule’s defaults, click Clear Changes.

After you have modified the rule details as required, click Update.

Customizing Policy or Rule Group Severity Label

You can also customize the severity label of all rules in a policy or a rule group in one operation. Right-click on policy name or the rule group name and the Severity Customization dialog appears:




FIGURE 2. Policy or Rule Group Severity Customization Dialog

Select the new severity label and click Update.

Customizing Parameters

Just like rules, you can also customize rule parameters to suit your specific requirements.

To customize rule parameters in the SpyGlass Design Environment, follow these steps:

1. Set the Policy Customization setting to On in the Misc Page of the Tools > Preferences... menu option.

2. Choose the Setup > Policies/Rules/Parameters... menu option.

The Policies/Rules/Parameters Selection window appears.

3. Activate the policy that you want to overload, if not already activated.

4. To customize a rule parameter, click the Customize button next to the rule parameter name.

The Parameter Customization window appears as in the following example:




FIGURE 3. Parameter Customization Window

You can customize the following settings of a parameter:

• Lock Parameter

You can select the parameter to always have the set value (Lock), or user-selectable (Selectable). By default, all parameters are set as user-selectable (Selectable).

A locked parameter is shown in red color in the Parameter Setting Window.

When you lock rules or parameters and save your settings as a template, the locked template file is saved with extension .sqc rather than the usual .spq extension.

• Present Value

Shows the default allowed parameter values as set in the policy or last customized allowed parameter value(s).

• Enter new value

Enter the new allowed parameter value(s).

• Old Description




Shows the default parameter description as set in the policy or last customized parameter description.

• New Description

Enter the new parameter description.

To revert to the parameter’s defaults, click Revert.

After you have modified the parameter details as required, click Update.

Saving Policy Overload Information

When you overload one or more rules/rule-groups/rule parameters of a policy and click the Update button, the overload information is saved in a file named <policy-name>-policy-overload.pl in the current working directory. For example, when you overload one or more rules/rule-groups/rule parameters of the SpyGlass Lint policy, the overload information is saved in a file named lint-policy-overload.pl in the current working directory.

Analyzing with Overloaded Policies

When you analyze a design in the SpyGlass Design Environment, all overload information available in the current working directory and other included directories is used.

Working in the Batch Mode

Under this feature, you need to create another file named <policy-name>-policy-overload.pl where <policy-name> is the name of the original policy you want to overload. Thus, to overload the SpyGlass Lint policy, you need to create a policy file named lint-policy-overload.pl file. The Overloaded policy file is searched by the same file search mechanism (-I mechanism) as searching for custom policy.




The spyOverload API Function

The Policy Overloaded file contains calls to the spyOverload API function in the following syntax:

spyOverload ( RULE => "<rule-name>"{ <keyword> => "<overloaded-value>" });

Separate keywords are available for overloading rules and rule parameters.

The spyOverload API function returns:

1 to indicate successful overload of specified rule or rule parameter description component.

Then, the original rule or rule parameter description component is no longer available for any purpose.

0 to indicate failure due to incorrect specification.

Actual cause of failure is identified by non-VDB error reporting routines. The rule or rule parameter being overloaded remains unchanged.

NOTE: You can also use the standard Perl functions to create multiple overload variations and select the required variation at run-time using rule parameter feature.

Overloading Rules

The following keywords are available for overloading rules using the




spyOverload API function:

Table 1: spyOverload() API Function Arguments for Rule overloading

<keyword> <overloaded-value>

RULE Rulename for which overload is applied.

This rule is expected to belong to the same policy as the one where overload is being applied.

NOTE: This argument must be present in all spyOverload function calls.

LANGUAGE This keyword acts as a filter on what RULE we want to overload i.e spyOverload API function will apply to RULE of given LANGUAGE only.

If this field is NOT used, then "rule name match" is sufficient for identifying which rule to overload.

NOTE: Please note the following points:

• The -overloadrules specification is used in conjunction with the spyOverload specification. However, SpyGlass gives precedence to the -overloadrules specification over the spyOverload specification.

• If a rule is registered in a single language (Verilog or VHDL), and there is no overloadrule specification in the same language (through -overloadrules or through spyOverload) then overloadrules specification with Verilog+VHDL is still applied for backward compatibility purposes. However, this is not a recommended use-model and should not be used.

• Language of the -overloadrules specification should be same as used in the corresponding rule registration. For example, if a rule is registered with Verilog + VHDL language, its -overloadrules specification should also be Verilog + VHDL.

• If you are not sure about the language specification of rule registration, you can omit the language option from overloadrule specification.




ALIASNAME Replaces the originally registered Alias name.

It is recommended that you do not use name (or alias) of some other rule for new overload value, since it may result in ambiguous behavior at time of SpyGlass output review.

SpyGlass, however, does not perform any check on overloaded value.

MESSAGELABEL Replaces the original registered severity of the rule.

This keyword enables a rule to have multiple messages with same/different severities.

If you want to overload severity or message for a multi message rule, it will be mandatory to specify the MESSAGELABEL argument, otherwise SpyGlass will generate an error. For single message rules the MESSAGELABEL argument is not required.

SEVERITY Replaces the originally registered severity-label.

The overloaded severity-label must be pre-registered using spyRegisterSeverity API function. A new severity-label can also be defined within the policy overload scope.

MESSAGETEXT Replaces the originally registered message text.

Though permitted by SpyGlass, this field should be overloaded (if at all necessary) with utmost care. This field serves as (printf-style) format string for final output of the rule (violation) message, and may result in runtime error if mismatching argument type is specified.

Table 1: spyOverload() API Function Arguments for Rule overloading (Continued)





Overloading Rule Parameters

Similar to rule overloading, SpyGlass rule parameters can also be overloaded using the spyOverload API function.

Then, the Policy Overloaded file contains calls to the spyOverload API function in the following syntax:

spyOverload ( PARAMETER => "<parameter-name>",{ <keyword> => "<overloaded-value>" });

WEIGHT Replaces the originally registered weight.

This is typically useful when you want to modify the relative significance of rules belong to the same severity.

NOTE: If you want to overload the weight for a rule, then if the MESSAGELABEL argument is given, the overload value of the weight will be applicable only for the corresponding message. If the MESSAGELABEL argument is not specified, then, it will be applicable to all the messages in the rule.

ORDERING Replaces the originally registered Rule-ordering value.

<pod-cut> description

In addition to the various rule-registration specification, the associated pod-cut text description (also known as, short-help and long-help) can also be overloaded from within the policy overload implementation. Both in the SpyGlass Design Environment and the spyexplain utility, the pod-cut description of the overload file takes precedence over the original pod-cut in the original policy description.

Table 1: spyOverload() API Function Arguments for Rule overloading (Continued)





The available keywords are as follows:

Using Overloaded Policies

The policy overload files are searched using the same -I command-line option mechanism as used for custom policies.

Use of policy overload feature is controlled by the -overloadpolicy command-line option as follows:

Table 2: spyOverload() API Function Arguments for Rule Parameter Overloading


VALUELIST Replaces the originally registered Value list.

NOTE: SpyGlass does not perform any check on overloaded value, for any kind of compatibility with original values.

<param-cut> description The associated param-cut text description can be overloaded from within the policy overload implementation.

Command-line Specification Effect

-overloadpolicy Apply Policy overload on all policy being selected to run. This is subject to policy overload file being found in the specified search path.

-overloadpolicy=noneor not specified

Disables search and loading of overload files.

-overloadpolicy=a,b Apply policy overload to policy named ‘a’ and ‘b’ only (assuming one or more of these policy are selected to run.

-overloadpolicy=all Apply policy overload on all policy selected to run. If policy overload file is not found for any policy, it is considered as an error condition, and (frequently) may be because of incorrect or no ‘-I’ specification.




Named Policy Overloads FeatureSpyGlass supports multiple named overloads for each policy.

Named Policy Overloads in the SpyGlass Design Environment

To create and apply named overloads in the SpyGlass Design Environment, follow these steps:

1. Select the policies you want to overload from the Run > Policies menu option.

2. Select the Setup > Customize Rules... menu option.

The Rule Customization Window appears:

The Rule Customization window has a policy treeview on the left that has all selected policies listed. Policies without overloads are


Named Policy Overloads Feature


shown with a yellow icon ( ). Policies where named overloads are

found in the included paths are shown with a green icon ( ).

The Overload Grid on the right shows all rule names of all selected policies and their overloadable items (alias, message label, severity, weight, condition, message, short help, and long description). Double-click on an item with very large item value (for example, message, short help, and long description items) to view the value in a separate window.

3. To create a named overload of a policy, right-click on the policy name in the policy treeview and select New Overload... The Add New Overload dialog appears:

4. Enter the identifier for the new named overload in Enter Overload Name. Specify the location where the new named overload file is to created in Enter Directory or click Browse and select the location. Click OK.

5. You return to the Rule Customization window where the new named overload file is now added under the policy name.

6. The rule-groups and rules of the policy being overloaded are now displayed in the Rule tree as in the following example:




7. To overload a particular rule, locate the rule in the Rule tree and double-click on it.

The rule is added to the Overload Grid on the top with blank values under the overloadable items.

A rule with multiple severities will have as many entries in the Overload Grid as shown below:

For example, if a rule has two severities with different weight and message strings, then the rule will have two entries for the rule in the Rule Customization window.

To view the default values of the selected rule, right-click on the rule name in the Overload Grid and select View Default... The rule default values are displayed as in the following example:




Click OK to close the window.

8. Enter the new (overload) values under for any overloadable item as required.

For items with very large item values (for example, message, short help, and long description items), double-click in the item row to view/edit value in a separate window.

Click Apply on completion.

9. Continue to enter more rules under the named overload.

10.Similarly, you can create multiple named overloads for each selected policy.

The editable named overload files are shown with a white icon ( ) and the non-editable (read-only files) named overload files are

shown with a red icon ( ).

11.To view the net effect of all named overloads of a policy, double-click on the policy name in the policy treeview. The Overload Grid now shows all rules of the selected policy. For each overloaded rule, the effective overloaded value of an overloadable item is shown in red as in the following example:




You can use the Ctrl+P and Ctrl+N key combinations to go to the previous overloaded rule and the next overloaded rule respectively.

12.To view the policy default, overload values of a rule’s overloadable items under the different named overloads, and the effective overload value, double-click on the rule name in the Overload Grid.

The rule overload details are displayed in the bottom pane as in the following example:

The first line shows the policy defaults, the next lines show the overload values, if any under different named overloads, and the last line shows the effective overload value for each overloadable item of the rule.

NOTE: The last entered overload value of an overloadable item is the effective overload value of that item.

13.If required, you can change the overload values in the last listed named overload to change the effective overload value.

14.On completion, click OK to save the settings and exit.

Now, any SpyGlass analysis run in the current SpyGlass Design Environment session will use the overload values set.




Other Features of the Rule Customization Window

The other features available in the Rule Customization window are as follows:

Named Policy Overloads in the Batch Mode

To create named overloads in the batch mode, you need to create required number of overload files, each named <policy-name>-policy-<name>-overload.pl where <policy-name> is the name of the original policy you want to overload and <name> is the named overload identifier. For example, the lint-policy-CAD-overload.pl is a named overload of the lint policy with identifier CAD.

Context Option Purpose

Main Window Search Rule To find a rule in the Overload Grid or the Rule Tree.

Enter the search string and click Find to search in the Overload Grid or click Find in Rule Tree to search in Rule Tree.

Context-menu for a policy name or a named overload

Add Overload... To add an existing named overload file for a policy.

Select the option. The Open dialog appears. Search your file system to locate the file. Click OK to add.

Context-menu for a named overload

Save Overload As... To save the selected overload with a different name or in a different location.

Select the option. The File Save As dialog appears. Set the new name and/or location and click OK.

Context-menu for a overloaded rule in the Overload Grid

Set Row to Default Sets the value of all overloadable items to the policy defaults.

Set Cell to Default Sets the value of a selected overloadable item to the policy default.

Clear Row Removes the overload values entered till now for the rule

Delete Row Removes the rule entry from the Overload Grid




Each named overload file has the same format as the single (unnamed) overload file. See Working in the Batch Mode for details of creating overload files.

You can supply the named overload files using the -overload command-line option as in the following example:

%> spyglass -batch -verilog -policies=lint-overload='CAD CAD1 METEOR' -I <named-overload-dir> <other-options>

The above specification indicates that you want to apply the lint-policy-CAD-overload.pl, lint-policy-CAD1-overload.pl, and lint-policy-METEOR-overload.pl (in the same order) to the lint policy and the named overload files are available in the <named-overload-dir> directory.

You may not have the same named overloads for each policy that you are specifying. Make sure that all named overload identifiers for all specified policies are indicated with the -overload command-line option. The named overload specification for a policy will be ignored if the corresponding named overload file is not found.





Appendix A: Introduction to Perl

Using PerlIn order to customize SpyGlass, you need to understand Perl. If you are not familiar with Perl, you should find a local expert, or visit your local bookstore. A popular series of books is published by O'Reilly and Associates - www.ora.com. We suggest you start with Learning Perl. If you know how to write shell scripts and are familiar with sed regular expressions or awk programming, you should not find Perl very challenging. We will attempt a very superficial introduction to the language here, solely to help you make simple modifications. We strongly recommend you make the investment to learn Perl - if you are like many engineers and developers, you will find it extremely valuable as a general purpose tool.

Perl similarities to CIf you understand C programming, you will find much in Perl very familiar:


Perl differences from C


Statements are free-format and all statements must end with a semi-colon.

Flow control statements - if, while, for - look just like they do in C

Blocks of code are defined using { and }, for example: if (x) {$a = 1; }

Perl supports pre and post-increment and assignment operators like ++, --, +=, ...

Perl even has functions like printf, sprintf, ...

Perl differences from CSome syntax is unique to Perl:

Top-level code is not declared in a subroutine - this is more like Basic than C

Variable names start with $, @ or %, eg $foo, @bas, %something.

Subroutines are declared without argument lists.

Blocks of code must be bracketed with { and }, even where not required in C

Perl has a number of odd-looking special variables: $_, @_, ...

Defining and using constants and variables in PerlConstants are defined in Perl almost exactly as they are in C: 3, 2.5, 1.7e-3, "a string", "c", 'c'. Either single quotes or double quotes can surround a string constant. There is no concept of a character constant as there is in C.

Perl understands 3 types of variable: scalars, arrays and hashes (also known as associative arrays). Each of these objects can contain any kind of data - Perl does not force a distinction between integers, characters, strings, floats, etc. in storing values. In fact, an array can have its first element as an integer, the second element a string and so




on.

Perl variables can be automatically defined, by being referenced. Alternatively they can be defined as essentially local variables (local to the routine in which they are being defined) using "my". This is probably the most appropriate method for a beginner. Thus you can define a number of scalar variables by:

my $foo = 3;my $bas = 'abc';my $xyz = "def";

Scalar variable names are prefixed by '$'. Also note that strings can be quoted by single quotes or by double quotes: 'c' and "c" are entirely equivalent. There is a difference between single and double quotes in Perl: if a variable name appears in a double quoted string, it will be replaced by the value of the variable (a process known as interpolation). If the string is single quoted, this will not happen.

Array variables are not very complex:

@foo = (3,4,5);@bas = ("abc","def",2);

You can refer to an element of an array much as you would in C. Array indices are 0-based so $foo[1] is 4. Why $foo and not @foo? Because when you refer to an element, you are referring to a scalar value. If you want to dig into this more, please buy a book! Similarly, $bas[0] contains "abc".

Hash variables have no direct equivalent in C and are amazingly useful. A hash variable is like an array except that it is indexed by values which are not necessarily numeric. For each entry, a hash has a key (the index value) and a value. For example:

%days = ('Mon',1,"Tue',2,'Wed',3'Thu',4,'Fri',5,'Sat',6, 'Sun',7);

Once you have defined this hash, you can refer to $days{'Wed'} which has the value 3. (Note again the use of $ since we are referring to a scalar value. Also, note the {} parentheses the hash equivalent of [ ] for arrays).


Using Regular Expressions in Perl


Perl variables can be combined and tested much as you would perform those operations in C. For example:

$x = 1;for ( $i = 0 ; $i<20 ; $i++ ){ $x = $x * $i; }

To print a value, use print (simpler to use than printf):

print "i is $i, x is $x\n";

Remember that variables are substituted in double-quoted strings so this will print: i is 10, x is 20 (for example).

Using Regular Expressions in PerlOne aspect of Perl that makes it unique among scripting languages is that pattern-matching is a built-in feature of the language. We will not even attempt to teach you how to write regular expressions in Perl - only how to recognize where they are being used.

Wherever you see something like:

$a =~ /âbc/ or$a !~ /def$/

you are looking at a pattern match that is comparing the value contained in the variable ($a in this case) against some regular expression (the object on the right hand side).

Some simple regular expression matches are:

Require $a contain exactly the string "abc": $a =~ /âbc$/;

Require $a start with "abc", followed by anything: $a =~ /âbc/;

Require $a end with "abc", preceded by anything: $a =~ /abc$/;

Require $a contain "abc" somewhere in the string: $a =~ /abc/;

Require $a contain only lower case letters: $a =~ /^[a-z]+$/;




Defining and using Subroutines/Functions in PerlSubroutines and functions are defined in Perl in a similar way to the way they are defined in C, except that no argument list is defined. As an example, the following subroutine prints a message:

sub print_a_message {print "Hello world\n";

}

A function looks just like a subroutine, but returns a value:

sub useless_function {print "Hello world\n";return 27;

}

To be useful, the function or subroutine needs to read arguments. Arguments are passed as the special array @_ (one of those odd variables). You can refer to the arguments individually as $_[0], $_[1] and so on, or you can pop them off the array (viewed as a stack, with index 0 at the top) using shift. Thus:

sub add_2_numbers {return $_[0] + $_[1];

}

is equivalent to:

sub also_add_2_numbers {$arg1 = shift;$arg2 = shift;return $arg1 + $arg2;

}

That's all you probably need to get started. When you want to write your own custom report generators, you will probably need to know more Perl than has been covered here. Again, an investment in learning Perl will repay you far beyond its utility in SpyGlass. Many people who used to hack custom scripts using a mixture of shell, sed and other programs have now switched almost completely to Perl to accomplish


Defining and using Subroutines/Functions in Perl


the same objectives much more flexibly and productively.


Documents

SpyGlass® Policy Customization Guide · SpyGlass Rule Definition SpyGlass Rule definition concepts Developing New SpyGlass Rules How to develop custom rules using standard rule-Primitives