SpyGlass® Policy

Customization Guide

Version 4.4.1

October 2010

Atrenta, Inc.
2077 Gateway Place, Suite 300
San Jose, California 95110
1-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.

 SpyGlass® Policy Customization Guide
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 ....................................................................................11
Header Section.................................................................................................................................12
Use Section ......................................................................................................................................12
Policy Registration Section...............................................................................................................13
Library Registration Section .............................................................................................................15
Severity Declaration Section ............................................................................................................16
Require File Section .........................................................................................................................18
Rule Parameter Description Section ................................................................................................19
Using spyObsoleteParameter API ............................................................................................20
Using spyRegisterReportParameter API...................................................................................22
Rule Description Section ..................................................................................................................22
Rule Group Description Section .......................................................................................................23
Report Description Section...............................................................................................................23
End-of-Policy Section .......................................................................................................................23

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

Overview.................................................................................................................................................25
Rule-Primitive Description files ...........................................................................................................27
Understanding Rule Description..........................................................................................................27
Rule Description Section ..................................................................................................................27
Rule Function Section ......................................................................................................................30
Rule Registration Section.................................................................................................................30
Registering Rules ..................................................................................................................................34

Version 4.4.1 October 2010 iii

 SpyGlass® Policy Customization Guide

Table of Contents

Registering Individual Rules .............................................................................................................35

Registering Rule Groups ..................................................................................................................38
Registering 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 ........................................................................44
Adapting Atrenta Standard Rules .....................................................................................................45
Using 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............................................................................................................76
Using the SpyGlass Design Environment.........................................................................................76
Customizing Rules ....................................................................................................................76
Customizing Policy or Rule Group Severity Label.....................................................................78
Customizing Parameters ...........................................................................................................79

iv October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Table of Contents

Saving Policy Overload Information ..........................................................................................81

Analyzing with Overloaded Policies ..........................................................................................81
Working in the Batch Mode ..............................................................................................................81
The spyOverload API Function .................................................................................................82
Overloading Rules.....................................................................................................................82
Overloading Rule Parameters...................................................................................................85
Using Overloaded Policies ........................................................................................................86
Named Policy Overloads Feature ........................................................................................................87
Named Policy Overloads in the SpyGlass Design Environment ......................................................87
Other Features of the Rule Customization Window ..................................................................92
Named 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

 SpyGlass® Policy Customization Guide

Table of Contents

vi October 2010 Version 4.4.1

 Preface

About This Book

The Atrenta® SpyGlass® Policy Customization Guide describes how
to create custom rule policies.

Contents of This Book

The 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

 SpyGlass® Policy Customization Guide
Typographical Conventions

Typographical Conventions
This document uses the following typographical conventions:

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...
The syntax described in this document uses the following convention:

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

Overview
The 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® Policy Customization Guide 9

 SpyGlass® Policy Customization Guide
SpyGlass Custom Rule Development

FIGURE 1. SpyGlass Rule-Checking Environment

Schematic Data

Options

Source Files

SpyGlass SpyGlass Design

Violation Environment
Database
Library Files

Policies

Reports

Rule-Primitive Libraries

SpyGlass Custom Rule Development

SpyGlass 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

10 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
SpyGlass Rule-Checking Environment

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 File

A 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

 SpyGlass® Policy Customization Guide
Structure of a SpyGlass Policy Ruledeck File

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

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

12 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
SpyGlass Rule-Checking Environment

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", "", "", "", "");

Version 4.4.1 October 2010 13

 SpyGlass® Policy Customization Guide
Structure of a SpyGlass Policy Ruledeck File

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 starc
manner.
Used as display-label wherever the policy name is
required to be reported.
<policy-version> Specifies the policy version. 1.6.6
Printed from -version (and -policies=<policy-name>)
command-line option
<policy-description> (Optional) Specifies the short policy description to SpyGlass rules that check
guide users about the policy purpose HDL designs for IP Reuse
guidelines compiled by
STARC.
<SpyGlass-min-version> Specifies the minimum SpyGlass Version required 3.3.0
for running the this version (<policy-version>) of the
policy.
<policy-help-file> (Optional) Specifies the policy help file (in ASCII Nothing
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.
<Policy-Start-Func> (Optional) Specifies a Perl function that will be run Nothing
before init functions of any rules of the policy are
run.

14 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
SpyGlass Rule-Checking Environment

Variable Purpose Value in STARC Example

<Policy-End-Func> (Optional) Specifies a Perl function that will be run Nothing
after exec/exit functions of all registered rules of the
policy are run.
<high-profile-rule-list> (Optional) Specified a space-separated list of high- Nothing
profile rules that should be reported first in
SpyGlass reports and in the Policy Tab of the
Message Window of the SpyGlass Design
Environment
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

Version 4.4.1 October 2010 15

 SpyGlass® Policy Customization Guide
Structure of a SpyGlass Policy Ruledeck File

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.

16 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
SpyGlass Rule-Checking Environment

<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.

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

Predefined Severity-Labels Severity-Class

Fatal FATAL
Error ERROR
Warning WARNING
Info INFO
Data DATA
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

Version 4.4.1 October 2010 17

 SpyGlass® Policy Customization Guide
Structure of a SpyGlass Policy Ruledeck File

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

18 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
SpyGlass Rule-Checking Environment

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"]);

Version 4.4.1 October 2010 19

 SpyGlass® Policy Customization Guide
Structure of a SpyGlass Policy Ruledeck File

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

20 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
SpyGlass Rule-Checking Environment

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. Instead
setting new parameter '-drive_cells_list' to specified
value '1'

Version 4.4.1 October 2010 21

 SpyGlass® Policy Customization Guide
Structure of a SpyGlass Policy Ruledeck File

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.

22 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
SpyGlass Rule-Checking Environment

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;

Version 4.4.1 October 2010 23

 SpyGlass® Policy Customization Guide
Structure of a SpyGlass Policy Ruledeck File

24 October 2010 Version 4.4.1

 SpyGlass Rule Definition

Overview
At 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

SpyGlass® Policy Customization Guide 25

 SpyGlass® Policy Customization Guide
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.

26 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
SpyGlass Rule Definition

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 files

The 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 Description

Each SpyGlass rule is described in the following sections:
 Rule Description Section
 Rule Function Section
 Rule Registration Section

Rule Description 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

Version 4.4.1 October 2010 27

 SpyGlass® Policy Customization Guide
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:

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)

<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

28 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
SpyGlass Rule Definition

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:

Version 4.4.1 October 2010 29

 SpyGlass® Policy Customization Guide
Understanding Rule Description

Rule Name
Rule Language Short Help
Policy Name Long Help

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;

30 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
SpyGlass Rule Definition

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

Version 4.4.1 October 2010 31

 SpyGlass® Policy Customization Guide
Understanding Rule Description

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

32 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
SpyGlass Rule Definition

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

Version 4.4.1 October 2010 33

 SpyGlass® Policy Customization Guide
Registering Rules

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

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.

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 Rules
In 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:

34 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
SpyGlass Rule Definition

FIGURE 1. Rule Hierarchy

Multiple
Rule Decks

Rule Deck A Rule Deck B Rule Deck C

Rule Group A Rule Group B Rule 5

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

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.

Version 4.4.1 October 2010 35

 SpyGlass® Policy Customization Guide
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):

36 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
SpyGlass Rule Definition

$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);

Version 4.4.1 October 2010 37

 SpyGlass® Policy Customization Guide
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

38 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
SpyGlass Rule Definition

<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.

Version 4.4.1 October 2010 39

 SpyGlass® Policy Customization Guide
Registering Rules

The multiple messages/severities of rules are registered using the

spyRegisterRuleMessage API function as follows:
spyRegisterRuleMessage
LANGUAGE=><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

40 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
SpyGlass Rule Definition

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.

Version 4.4.1 October 2010 41

 SpyGlass® Policy Customization Guide
Registering Rules

42 October 2010 Version 4.4.1

 Developing New
SpyGlass Rules

General Methodology on Developing New Rules

One 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.

SpyGlass® Policy Customization Guide 43

 SpyGlass® Policy Customization Guide
Searching Atrenta Infrastructure for Rule-Primitives

Searching Atrenta Infrastructure for Rule-Primitives

When 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

44 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Developing New SpyGlass Rules

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 default
value 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

Version 4.4.1 October 2010 45

 SpyGlass® Policy Customization Guide
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 should
not 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,

46 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Developing New SpyGlass Rules

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 must
be 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

Version 4.4.1 October 2010 47

 SpyGlass® Policy Customization Guide
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 Rules

The 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 : veResetLD
SUPPORT : Production

48 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Developing New SpyGlass Rules

LANGUAGE verilog:
PURPOSE :
Function to check that all storage elements are
reset as specified
DESIGN VIEW : RTLDU (RTL)
LIBRARY NAME : libCoreRules
SEARCH KEYWORD LIST : reset related check
SPYGLASS CONSTRAINT INFORMATION :
None
DETAILED 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
port
PERL CALLBACK SUBROUTINE CUSTOMIZATION :
None
OUTPUT 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 Applicable
EXAMPLES :

Version 4.4.1 October 2010 49

 SpyGlass® Policy Customization Guide
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

50 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Developing New SpyGlass Rules

(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

Version 4.4.1 October 2010 51

 SpyGlass® Policy Customization Guide
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)

52 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Developing New SpyGlass Rules

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

Version 4.4.1 October 2010 53

 SpyGlass® Policy Customization Guide
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"

54 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Developing New SpyGlass Rules

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

Version 4.4.1 October 2010 55

 SpyGlass® Policy Customization Guide
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

56 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Developing New SpyGlass Rules

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

Version 4.4.1 October 2010 57

 SpyGlass® Policy Customization Guide
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:

58 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Developing New SpyGlass Rules

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 ClkName
spyRegisterGroup(“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 Rules

While 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.

Version 4.4.1 October 2010 59

 SpyGlass® Policy Customization Guide
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.

60 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Developing New SpyGlass Rules

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).

Version 4.4.1 October 2010 61

 SpyGlass® Policy Customization Guide
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 Rules

SpyGlass 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'.

62 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Developing New SpyGlass Rules

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);
}

Version 4.4.1 October 2010 63

 SpyGlass® Policy Customization Guide
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 information

If 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 Rules

You 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:

64 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Developing New SpyGlass Rules

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.

Version 4.4.1 October 2010 65

 SpyGlass® Policy Customization Guide
Specifying Obsolete Rules

66 October 2010 Version 4.4.1

 Creating Custom Reports

Overview
Besides 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 Concepts

A 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.

SpyGlass® Policy Customization Guide 67

 SpyGlass® Policy Customization Guide
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.

68 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Creating Custom Reports

The spyRegisterReportGenerator function

The 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 Functions

SpyGlass Report Generator functions are standard Perl functions with
the following arguments:

Version 4.4.1 October 2010 69

 SpyGlass® Policy Customization Guide
Reading VDB Rule Message Information

Variable Name Points to...

$_[0] Reserved
$_[1] Name of the Violation Database file
$_[2] Name of the output report file

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 Information

When 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

70 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Creating Custom Reports

 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 Example

Here 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;

Version 4.4.1 October 2010 71

 SpyGlass® Policy Customization Guide
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

72 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Creating Custom Reports

 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

Version 4.4.1 October 2010 73

 SpyGlass® Policy Customization Guide
A Report Generator Example

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

74 October 2010 Version 4.4.1

 Overloading SpyGlass
Policies

Introduction
The 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.

SpyGlass® Policy Customization Guide 75

 SpyGlass® Policy Customization Guide
Single Policy Overload Feature

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:

76 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Overloading SpyGlass Policies

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

Version 4.4.1 October 2010 77

 SpyGlass® Policy Customization Guide
Single Policy Overload Feature

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:

78 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Overloading SpyGlass Policies

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:

Version 4.4.1 October 2010 79

 SpyGlass® Policy Customization Guide
Single Policy Overload Feature

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

80 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Overloading SpyGlass Policies

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.

Version 4.4.1 October 2010 81

 SpyGlass® Policy Customization Guide
Single Policy Overload Feature

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

82 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Overloading SpyGlass Policies

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.

Version 4.4.1 October 2010 83

 SpyGlass® Policy Customization Guide
Single Policy Overload Feature

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

<keyword> <overloaded-value>
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.

84 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Overloading SpyGlass Policies

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

<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> In addition to the various rule-registration specification, the
description 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.

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>" }
);

Version 4.4.1 October 2010 85

 SpyGlass® Policy Customization Guide
Single Policy Overload Feature

The available keywords are as follows:

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

<keyword> <overloaded-value>
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.

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:

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=none Disables search and loading of overload files.
or not specified
-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.

86 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Overloading SpyGlass Policies

Named Policy Overloads Feature

SpyGlass 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

Version 4.4.1 October 2010 87

 SpyGlass® Policy Customization Guide
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:

88 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Overloading SpyGlass Policies

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:

Version 4.4.1 October 2010 89

 SpyGlass® Policy Customization Guide
Named Policy Overloads Feature

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:

90 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Overloading SpyGlass Policies

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.

Version 4.4.1 October 2010 91

 SpyGlass® Policy Customization Guide
Named Policy Overloads Feature

Other Features of the Rule Customization Window

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

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 Add Overload... To add an existing named overload file for a policy.
name or a named Select the option. The Open dialog appears. Search your
overload file system to locate the file. Click OK to add.
Context-menu for a Save Overload As... To save the selected overload with a different name or in a
named overload 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 Set Row to Default Sets the value of all overloadable items to the policy
overloaded rule in the defaults.
Overload Grid 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

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.

92 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Overloading SpyGlass Policies

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.

Version 4.4.1 October 2010 93

 SpyGlass® Policy Customization Guide
Named Policy Overloads Feature

94 October 2010 Version 4.4.1

 Appendix A: Introduction
to Perl

Using Perl
In 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 C
If you understand C programming, you will find much in Perl very
familiar:

SpyGlass® Policy Customization Guide 95

 SpyGlass® Policy Customization Guide
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 C

Some 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 Perl

Constants 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

96 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Appendix A: Introduction to Perl

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).

Version 4.4.1 October 2010 97

 SpyGlass® Policy Customization Guide
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 Perl

One 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 =~ /^abc/ 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 =~ /^abc$/;
 Require $a start with "abc", followed by anything: $a =~ /^abc/;
 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]+$/;

98 October 2010 Version 4.4.1

 SpyGlass® Policy Customization Guide
Appendix A: Introduction to Perl

Defining and using Subroutines/Functions in Perl

Subroutines 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

Version 4.4.1 October 2010 99

 SpyGlass® Policy Customization Guide
Defining and using Subroutines/Functions in Perl

the same objectives much more flexibly and productively.

100 October 2010 Version 4.4.1