 |
|
|
|
Synopsys::Collection - An interface to the Synopsys shell collection idiom
|
|
|
use Synopsys;
$all_cells = $shell->get_cells("-h *");
$num_cells = $all_cells->size;
$one_cell = $all_cells->index(23);
|
|
|
|
|
|
The Synopsys::Collection module is an auxiliary module to SPP which maps
the Tcl based collection idiom into perl. This module is usually not included directly. Its use is
automatically enabled when using SPP.
The reader is directed to the Synopsys documentation to learn about what a
collection is and how they are used.
The methods provided in the package are based on the functionality provided
by collections in pt_shell. Please note that not all the methods are supported in all Synopsys
shells. For example, the sort_collection method is unsupported in dc_shell and its derivatives.
The methods in this package come in two basic varieties, methods that
create new collections and methods that operate on existing collections.
|
|
|
This sections describes the methods that emulate the common collection
manipulation Tcl commands. Each can be called as either a method of a SPP
object or a method of an already existing Collection object.
In some cases, there are no differences between the Tcl commands and the
Perl methods. In some cases, there are differences in whether the base
collection is modified or not. The Perl methods were written in the way
that I thought was most appropriate, not necessarily in a way to be most
compatible with the like Tcl command.
Many of the methods described below can take one or more collection objects
themselves as arguments. As a convenience to the user, will automatically
expand any Collection object into Tcl equivalent. For example:
$collection1 = $shell->get_cells("A*");
$collection2 = $shell->get_cells("B*");
$collection3 = $shell->get_cells("C*");
$collection4 = $shell->add_to_collection($col1, $col2, $col3);
What this means is that anywhere the Tcl documentation specifies that an
object argument is appropriate, a perl Collection object can be used in
it's place.
- Adding to a Collection
-
Usage:
$shell->add_to_collection($base_collection,
<object_spec>,
['-unique']);
$base_collection->add(<object_spec>, ['-unique']);
add_to_collection behaves identically to the like named Tcl command. The
$base_collection is not modified. The method add is different from both the Tcl command and add_to_collection in that the calling object is modified.
In either case, a Collection object is returned that is the sum of the
$base_collection and the collections specified in object_spec or returns undef on error.
- Comparing Collections
-
Usage:
$shell->compare_collections($collection1,
$collection2,
[-order_dependent]);
$collection1->compare($collection2, [-order_dependent]);
Each of these methods behaves identically to the like named Tcl command.
Returns 0 when $collection1 equals $collection2
modulo the -order_dependent
flag. Retuns non-zero when they are unequal and returns undef on error.
- Copying Collections
-
Usage:
$shell->copy_collection($collection);
$collection->copy;
Each of these methods behaves identically to the like named Tcl command.
Returns a new Collection object that is copy of $collection on
success and returns undef on error. The original collection is unchanged in
either case.
- Filtering Collections
-
Usage:
$shell->filter_collection($collection,
<expression>,
[-regexp], [-nocase]);
$collection->filter(<expression>,
[-regexp], [-nocase]);
filter_collection behaves identically to the like named Tcl command. The
$collection is not modified. The method filter is different from both the Tcl command and filter_collection in that the calling object is modified.
In either case, a Collection object is returned that is the filtered result
of the collection or returns undef on error.
- Indexing a Collection
-
Usage:
$shell->index_collection($collection, $index);
$collection->index($index);
Each of these methods behaves identically to the like named Tcl command.
Returns a new Collection object that is the $index index of
$collection on success and returns undef on failure.
- Sizeof a Collection
-
Usage:
$shell->sizeof_collection($collection);
$collection->size;
Each of these methods behaves identically to the like named Tcl command.
Returns a new Collection object that is the $index index of
$collection on success and returns undef on failure.
- Removing from a Collection
-
Usage:
$shell->remove_from_collection($collection, <object_spec>);
$collection->remove(<object_spec>);
remove_from_collection behaves identically to the like named Tcl command. The
$collection is not modified. The method remove is different from both the Tcl command and remove_from_collection in that the calling object is modified.
In either case, a Collection object is returned that is result of removing
<object_spec> from $collection and returns undef on
error.
- Sorting a Collection
-
Usage:
$shell->sort_collection($collection,
['-descending'], <criteria>);
$collection->remove(['-descending'], <criteria>);
sort_collection behaves identically to the like named Tcl command. The
$collection is not modified. The method sort is different from both the Tcl command and sort_collection in that the calling object is modified.
In either case, a Collection object is returned that is result of sorting
the $collection based on <criteria> and returns undef on
error.
- Querying a Collection
-
Usage:
$shell->query_objects(<object_spec>,
[-verbose],
[-class class_name],
[-truncate elem_count])
$collection->query([-verbose],
[-class class_name],
[-truncate elem_count]);
Each of these methods behaves identically to the like named Tcl command.
Returns a string that lists the names (and classes) of all the elements in
<object_spec> and returns undef on failure.
If a -truncate argument is not provided, an elem_count of zero is assumed, which returns
the entire list. This is different from the default behavior in Tcl where
only the first 100 elements are returned if -truncate is not specified.
- get_cells( ... )
-
- get_clocks( ... )
-
- get_designs( ... )
-
- get_lib_cells( ... )
-
- get_lib_pins( ... )
-
- get_libs( ... )
-
- get_nets( ... )
-
- get_pins( ... )
-
- get_ports( ... )
-
- current_design( ... )
-
Usage:
$shell->get_cells( ... )
$shell->get_libs( ... )
Each of the above methods return a new Collection object or sucess or undef
on error. The functionality of each is identical to that of the like named
Tcl command. The reader is directed to the Synopsys documentation for
further information.
|
|
|
Below is a description of the instance methods that can be called on a
collection after it's created.
- shell()
-
Returns the SPP object associated with the collection.
- pvar()
-
Whenever a collection is created, the output of the Tcl command that
created the object needs to be saved in a variable or Tcl will implicitly
destroy the object. Each collection has a auto-generated Tcl variable
associated with it. This method returns that string which will take the
form:
_pvar[1-9]\d+
For example, the code:
$a = $shell->get_cells("*");
translates into the Tcl command:
set _pvar34 [get_cells "*"]
_pvar stands for perl variable. The integer for each pvar is auto-generated and starts at 1. _pvar0 is
reserved for internal use. This method is generally not needed but is
provided that so users can enter commands manually using the _pvar variable
if necessary for debugging.
- tvar()
-
Closely related to the pvar() method, tvar()
returns the string that pvar() would evaluate to if it were
dereferenced in Tcl. For example, given that a collection was created that
had a pvar() of _pvar34, the tvar might be:
_sel1045
which is really equal to:
$_pvar34
in Tcl notation. The _sel notation is a Synopsys creation and completely arbitrary. This method is
generally not needed and only provided for debugging.
- class()
-
Returns the class of the first element in the collection. This is generally used on
collections of size one. A call to this method translates into the Tcl
code:
query_objects -verbose _pvar34
where _pvar34 is an example Tcl variable associated with each collection object. If the
collection in question were a cell, the output of this command would be:
{"cell:U1019"}
and the method would return the string cell.
Please note that different Synopsys shells yield different results with
this method. dc_shell doesn't have the correct notion of classes yet, so it
always returns the string object for every element. Contrast this to pt_shell, which gives correct results.
- name()
-
Returns the full_name attribute for a collection with one element. This method is just a synonym
for the full_name attribute which can also be retrieved using the collection attributes
functionality.
Internally, name() uses the get_object_name Tcl command.
- all_elements()
-
Returns a list collection objects that are all the elements in the object's
collection. This can be used to iterate over a collection. This method can be time-consuming and resource consuming
if the collection has many elements (thousands).
|
|
|
Any collection that has a size of one can retrieve a named attribute by
using the name of the attribute as the method name. For example, if a
collection object is created that contains a cell element, the ref_name attribute associated with it could be accessed with this code:
$cell->ref_name;
This will return a string that is the reference name for that cell.
It is an error to attempt to retrieve an attribute using a collection
object that contains more than one object.
It is also an error to retrieve a non-existent attribute.
In all cases, the empty string is returned on failure and the attribute
value is returned on success.
It is up to the user to know attributes exist on what types of collection
classes (cells, nets, pins, etc). The reader is directed to the Tcl
command:
list_attributes -application -class <class>
to print out a list of available attributes for a given collection class.
|
|
|
A common operation is iterating over the elements in a collection. While
Synopsys' Tcl provides a foreach_in_collection command, there is no such command in perl. The same effect can be
accomplished using either the
index or the
all_elements. The following two code snippets are functionally the same:
my $size = $collection->size;
for(my $i=0; $i<$size; $i++) {
my $element = $collection->index($i);
...
}
foreach my $element ($collection->all_elements) {
...
}
Overall, each code snippet takes about the same time to execute and
produces the same results. The first snippet uses less memory (for both
Perl and Tcl) because the allocation of collection objects (for both Perl
and Tcl) is done over the course of the loop. One collection object is
allocated and deallocated each time through. Contrast this with the second
snippet which first builds a list of collection objects and then iterates
over them.
So while the second method may be stylistically cleaner, it is less
preferable because it consumes more memory.
|
|
|
Everytime a collection is created, a Tcl variable (pvar) is set in the Synopsys shell. Using Perl's automatic garbage collection
facility, the Tcl variables will automatically be unset when the perl
Collection object is undef'ed or goes out of scope.
This happens automatically and requires no intervention from the user.
|
|
|
Add support for these Tcl commands:
get_lib_timing_arcs
get_path_groups
get_generated_clocks
get_qtm_ports
get_timing_arcs
get_timing_paths
all_clocks
all_inputs
all_outputs
all_registers
all_instances
all_connected
all_fanin
all_fanout
|
|
|
Synopsys, synopsys_shell
|
|
|
Jeff Solomon <jsolomon@vlsi.stanford.edu>
|
|
|
|
|