oaInstTerm Class Reference

Inheritance diagram for oaInstTerm:

oaBlockObject oaDesignObject oaObject


Public Methods

void destroy ()
void hide ()
oaInstTerm * getBit (oaUInt4 bitIndex) const
oaNet * getNet (oaBoolean preferred=false) const
oaInst * getInst () const
oaTerm * getTerm () const
void getTermName (oaName &name) const
void getTermName (const oaNameSpace &ns, oaString &name) const
oaUInt4 getTermPosition () const
oaUInt4 getNumBits () const
oaRouteMethod getRouteMethod () const
oaBoolean isBound () const
oaBoolean isImplicit () const
oaBoolean usesTermPosition () const
void addToNet (oaNet *net)
void removeFromNet ()
void setRouteMethod (oaRouteMethod routeMethod)
void scalarize ()
oaOccInstTerm * getOccInstTerm () const
oaCollection< oaRoute, oaInstTerm > getConnRoutes () const
oaCollection< oaOccInstTerm, oaInstTerm > getOccInstTerms (const oaOccurrence *top) const

Static Public Methods

oaInstTerm * create (oaNet *net, oaInst *inst, oaTerm *term, oaBlockDomainVisibility view=oacInheritFromTopBlock)
oaInstTerm * create (oaNet *net, oaInst *inst, const oaName &termName, oaBlockDomainVisibility view=oacInheritFromTopBlock)
oaInstTerm * create (oaNet *net, oaInst *inst, oaUInt4 termPosition, oaBlockDomainVisibility view=oacInheritFromTopBlock)
void create (oaInst *inst, const oaNetTermArray &connData, oaBlockDomainVisibility view=oacInheritFromTopBlock)
void create (oaInst *inst, const oaNetTermNameArray &connData, oaBlockDomainVisibility view=oacInheritFromTopBlock)
void create (oaInst *inst, const oaNetTermPosArray &connData, oaBlockDomainVisibility view=oacInheritFromTopBlock)
oaInstTerm * find (const oaInst *inst, const oaTerm *term)
oaInstTerm * find (const oaInst *inst, const oaName &termName)
oaInstTerm * find (const oaInst *inst, oaUInt4 termPosition)

Public Types

enum  { dtIndex = oacInstTermDataType }

Detailed Description

The oaInstTerm class represents a connection between a net and a terminal in the master of an instance. The connection is proper if the number of bits in the net is equal to the number of bits implied by the instTerm's terminal name. In the case of oaVectorInsts, the net width must be multiplied by the number of bits represented by the instance name.

InstTerms can exist that do not have a proper corresponding terminal in the master of the instance. This allows instTerms to be created when the instance master is not read in, and it allows changes to instTerms that happen before the master is updated. The traversal from an instTerm to its corresponding terminal will not succeed unless a terminal with an exactly matching name or position is present in the master.

When an instTerm is created by specifying a terminal or terminal name, the instTerm is said to connect by name. Binding is done to the named terminal if it exists in the instance master. The width of the connection must match the width of the associated net. When an instTerm is created by specifying a terminal position, the instTerm is said to connect by position. Binding is to the terminal in the master that is assigned to the position and if the resulting connection width matches the width of the corresponding net. To avoid confusion, the instTerms associated with a particular instance must either all be connected by name or all by connected by position.

oaInstTerm objects are always in the block domain. oaInstTerms can be physical-only instTerms that are only in the block hierarchy, or they can be cross-domain instTerms that directly correspond to an oaModInstTerm in the module domain and one or more oaOccInstTerm instances in the occurrence domain.

The oaInstTerm class can be observed by deriving from oaObserver<oaInstTerm>.

Member Function Documentation

void oaInstTerm::addToNet (  oaNet *    net ) 
 

This function adds this instTerm to the specified net. If this instTerm is already connected to another net, it detaches first.

Parameters:
net The new net to which to attach the instTerm
Exceptions:
oacNetAndInstNotInSameDesign 
oacNetInstTermWidthMismatchForInstTerm 
oacCannotModifyImplicitInstTerm 
oacInstTermInstMustBeInUniqueOccHier 
oacInstTermNetMustBeInUniqueOccHier 
oacInstTermMustBeInUniqueModule 
oacPhysOnlyInstTermNetMustBeInSameOcc 

void oaInstTerm::create (  oaInst *    inst,
const oaNetTermPosArray &    connData,
oaBlockDomainVisibility    view = oacInheritFromTopBlock
)  [static]
 

This function creates a set of instTerms, connecting terminals of the specified instance to the specified nets. The specifications for which terminals are connected to which nets are stored in an oaNetTermPosArray that associates net pointers with term positions.

Important: This function is intended for use by performance-sensitive applications that create connectivity that is "correct by construction." This function can have undesirable side effects if this expectation is violated and the specified connectivity is inconsistent: If a duplicate oaTerm position is encountered in the array during the execution of this function, all the oaInstTerms created before the duplicate oaTerm position was encountered are destroyed, but the design is still tagged as modified and undo records are created. If changes are then rolled back with an undo operation, the application will receive observer notifications for both the creation and the destruction of those oaInstTerms.

Exceptions are thrown if:

  • Any net and the given instance are not in the same design
  • Any net is an implicit net
  • Any terminal is not in the instance master design
  • An instance of any terminal already exists where the net is not NULL
  • A connection width does not match the specified number of bits in the net

Parameters:
inst The instance on which the instTerms are created
connData An array of instTerm specifications; where ach entry in the array describes a specification that is used to create a single instTerm
view Specifies the visibility of each instTerm to the module domain
Exceptions:
oacInstTermBatchCreateHasInstTerms 
oacNetInstTermWidthMismatchForInstTerm 

void oaInstTerm::create (  oaInst *    inst,
const oaNetTermNameArray &    connData,
oaBlockDomainVisibility    view = oacInheritFromTopBlock
)  [static]
 

This function creates a set of instTerms, connecting terminals of the specified instance to the specified nets. The specifications for which terminals are connected to which nets are stored in an oaNetTermNameArray that associates net pointers with term names.

Important: This function is intended for use by performance-sensitive applications that create connectivity that is "correct by construction." This function can have undesirable side effects if this expectation is violated and the specified connectivity is inconsistent: If a duplicate oaTerm name is encountered in the array during the execution of this function, all the oaInstTerms created before the duplicate oaTerm name was encountered are destroyed, but the design is still tagged as modified and undo records are created. If changes are then rolled back with an undo operation, the application will receive observer notifications for both the creation and the destruction of those oaInstTerms.

Exceptions are thrown if:

  • Any net and the given instance are not in the same design
  • Any net is an implicit net
  • Any terminal is not in the instance master design
  • An instance of any terminal already exists where the net is not NULL
  • A connection width does not match the specified number of bits in the net

Parameters:
inst The instance on which the instTerms are created
connData An array of instTerm specifications; where each entry in the array describes a specification that is used to create a single instTerm
view Specifies the visibility of each instTerm to the module domain
Exceptions:
oacInstTermBatchCreateHasInstTerms 

void oaInstTerm::create (  oaInst *    inst,
const oaNetTermArray &    connData,
oaBlockDomainVisibility    view = oacInheritFromTopBlock
)  [static]
 

This function creates a set of instTerms, connecting the specified instance's terminals to the specified nets. The specifications for which terminals are connected to which nets are stored in an oaNetTermArray that associates net and term pointers.

Important: This function is intended for use by performance-sensitive applications that create connectivity that is "correct by construction." This function can have undesirable side effects if this expectation is violated and the specified connectivity is inconsistent. If a duplicate oaTerm pointer is encountered in the array during the execution of this function, all the oaInstTerms created before the duplicate oaTerm pointer was encountered are destroyed, but the design is still tagged as modified and undo records are created. If changes are then rolled back with an undo operation, the application receives observer notifications for both the creation and the destruction of those oaInstTerms.

Exceptions are thrown if:

  • Any net and the given instance are not in the same design
  • Any net is an implicit net
  • Any terminal is not in the instance master design
  • An instance of any terminal already exists where the net is not NULL
  • A connection width does not match the number of specified bits in the net

Parameters:
inst The instance on which the instTerms are created
connData An array of instTerm specifications; where each entry in the array describes a specification that is used to create a single instTerm
view Specifies the visibility of each instTerm to the module domain
Exceptions:
oacInstTermBatchCreateHasInstTerms 

oaInstTerm * oaInstTerm::create (  oaNet *    net,
oaInst *    inst,
oaUInt4    termPosition,
oaBlockDomainVisibility    view = oacInheritFromTopBlock
)  [static]
 

This function creates an instTerm connecting a terminal at the specified position in the master of the given instance to the specified net. You may specify a NULL net value.

The instTerms associated with the instance must all be connected either by name or by position.

Parameters:
net The net to use for the connection; it may be NULL.
inst The instance to make the connection to.
termPosition The position of a terminal in the instance master to connect to.
view Specifies the visibility of the instTerm to the module domain.
Exceptions:
oacNetAndInstNotInSameDesign 
oacInstTermAlreadyExists 
oacInstTermInstMustBeInUniqueOccHier 
oacInstTermNetMustBeInUniqueOccHier 
oacPhysOnlyInstTermNetMustBeInSameOcc 

oaInstTerm * oaInstTerm::create (  oaNet *    net,
oaInst *    inst,
const oaName &    termName,
oaBlockDomainVisibility    view = oacInheritFromTopBlock
)  [static]
 

This function creates an instTerm connecting the named terminal in the master of the given instance to the specified net. You can specify a NULL net value. InstTerms can be created with names of terminals that do not exist in the instance master; these instTerms are unbound until the named terminal is created in the instance master.

The instTerms associated with the instance must all be connected either by name or by position. An oacInstTermNetMismatchInRepeatedMembers exception is thrown if repeated bundle instTerm bits connect to different nets.

Parameters:
net The net to use for the connection; it may be NULL.
inst The instance to make the connection to.
termName The name of the terminal in the instance master to connect to.
view Specifies the visibility of the instTerm to the module domain.
Exceptions:
oacNetAndInstNotInSameDesign 
oacInstTermAlreadyExists 
oacNetInstTermWidthMismatchForInstTerm 
oacInstTermMustBeByPosition 
oacInstTermInstMustBeInUniqueOccHier 
oacInstTermNetMustBeInUniqueOccHier 
oacInstTermNetMismatchInRepeatedMembers 
oacPhysOnlyInstTermNetMustBeInSameOcc 

oaInstTerm * oaInstTerm::create (  oaNet *    net,
oaInst *    inst,
oaTerm *    term,
oaBlockDomainVisibility    view = oacInheritFromTopBlock
)  [static]
 

This function creates an instTerm connecting the specified terminal in the master of the given instance to the specified net. You may specify a NULL net value.

The instTerms associated with the instance must all be connected either by name or by position. An oacInstTermNetMismatchInRepeatedMembers exception is thrown if repeated bundle instTerm bits connect to different nets.

Parameters:
net The net to use for the connection; it may be NULL.
inst The instance to make the connection to.
term The terminal in the instance master to connect to.
view Specifies the visibility of the instTerm to the module domain.
Returns:
A pointer to the instTerm created.
Exceptions:
oacNetAndInstNotInSameDesign 
oacTermNotInInstMasterForInstTerm 
oacInstTermAlreadyExists 
oacNetInstTermWidthMismatchForInstTerm 
oacInstTermMustBeByPosition 
oacInstTermInstMustBeInUniqueOccHier 
oacInstTermNetMustBeInUniqueOccHier 
oacInstTermNetMismatchInRepeatedMembers 
oacPhysOnlyInstTermNetMustBeInSameOcc 

void oaInstTerm::destroy (    ) 
 

This function destroys this instTerm, removing it from the database. The reference for the instTerm is removed from the corresponding net.

Exceptions:
oacCannotDestroyImplicitInstTerm 
oacCannotModifyInstTermInNonUniqueHier 

oaInstTerm * oaInstTerm::find (  const oaInst *    inst,
oaUInt4    termPosition
)  [static]
 

This function searches all of the instTerms associated with the specified instance and returns the one that makes a connection to the specified terminal position. NULL is returned if no terminal exists in the instance master at the specified position.

Parameters:
inst The instance whose instTerms are searched.
termPosition The terminal position used in the search.
Exceptions:
oacInstTermInstUsesTermName 

oaInstTerm * oaInstTerm::find (  const oaInst *    inst,
const oaName &    termName
)  [static]
 

This function searches all of the instTerms associated with the specified instance and returns the one that makes a connection to the named terminal. NULL is returned if no such terminal exists on the instance.

Parameters:
inst The instance whose instTerms are searched.
termName The terminal name to use in the search.
Exceptions:
oacInstTermInstUsesTermPosition 

oaInstTerm * oaInstTerm::find (  const oaInst *    inst,
const oaTerm *    term
)  [static]
 

This function searches all of the instTerms associated with the specified instance and returns the one that is associated with the specified terminal. NULL is returned if no such terminal exists on the instance.

Parameters:
inst The instance whose instTerms are searched.
term The terminal to use in the search.
Exceptions:
oacTermNotInInstMasterForInstTerm 
oacInstTermInstUsesTermPosition 

oaInstTerm * oaInstTerm::getBit (  oaUInt4    bitIndex )  const
 

This function returns a pointer to the instTerm that corresponds to the specified bitIndex bit of this instTerm. For single-bit instTerms, this function returns this instTerm if the bitIndex value is zero.

Exceptions:
oacInvalidInstTermBitIndex 

oaCollection oaInstTerm::getConnRoutes (    )  const
 

This function returns a collection of routes connected to this instTerm. Each route in the collection has this instTerm as either its startConn, endConn, or both.

oaInst * oaInstTerm::getInst (    )  const
 

This function returns a pointer to the instance associated with this instTerm.

oaNet * oaInstTerm::getNet (  oaBoolean    preferred = false )  const
 

This function returns the net associated with this instTerm. NULL is returned if the instTerm was created with a NULL net or if the instTerm was disconnected from the net. If preferred is true, the preferred equivalent net associated with the net will be returned instead.

Parameters:
preferred indicates whether to return the preferred equivalent
Returns:
A pointer to an oaNet

oaUInt4 oaInstTerm::getNumBits (    )  const
 

This function returns the number of bits for this instTerm. This value is equal to the number of bits in the associated net. If the instTerm has no net, the value is calculated from the number of bits in the corresponding terminal multiplied by the number of bits in the corresponding instance. If the terminal is not bound, the number of bits for the terminal is derived from the terminal name. If the terminal is not bound and the instTerm connects by position, the number of bits cannot be determined if there is no net and a value of zero is returned.

oaOccInstTerm oaInstTerm::getOccInstTerm (    )  const
 

This function returns the occurrence instTerm that is the reflection of this block instTerm in the context of the top occurrence of the design that contains the instTerm.

oaCollection oaInstTerm::getOccInstTerms (  const oaOccurrence *    top )  const
 

This function returns a collection of occInstTerms that represent this instTerm in the occurrence hierarchy specified by top.

Parameters:
top The top occurrence

oaRouteMethod oaInstTerm::getRouteMethod (    )  const
 

This function returns the route method of this instTerm.

oaTerm * oaInstTerm::getTerm (    )  const
 

This function returns the terminal associated with this instTerm. An attempt is made to bind the master if the instTerm is unbound. NULL is returned if the instance is unbound or the terminal is not found in the master.

void oaInstTerm::getTermName (  const oaNameSpace &    ns,
oaString &    name
)  const
 

This function returns the name of the terminal associated with this instTerm in the nameSpace specified. A name is returned even if the instTerm is not bound. The existence of a terminal name does not necessarily guarantee that the corresponding terminal exists in the instance master.

Parameters:
ns The nameSpace for processing the name
name The string that the terminal name is returned in
Exceptions:
oacInstTermConnectsByPosition 

void oaInstTerm::getTermName (  oaName &    name )  const
 

This function returns the name of the terminal associated with this instTerm in the given name argument. A name is returned even if the instTerm is not bound. The existence of a terminal name does not guarantee that the terminal exists in the corresponding instance master.

Parameters:
name The name object to return the terminal name in
Exceptions:
oacInstTermConnectsByPosition 

oaUInt4 oaInstTerm::getTermPosition (    )  const
 

This function returns the terminal position that this instTerm connects to.

Exceptions:
oacInstTermConnectsByName 

void oaInstTerm::hide (    ) 
 

This function removes the instTerm from the block domain. A hidden instTerm does not appear in any block domain collections, and it is not returned by any find() functions. This function does not produce the same result as destroy since the corresponding instTerms in the module domain are unaffected by hide().

An instTerm must be explicit to be hidden, it must correspond to an instTerm in a unique occurrence hierarchy (see oaOccurrence::uniquify()), and it must have a corresponding instTerm in the module domain. Hiding a multi-bit instTerm also causes all the member instTerms to be hidden. Hiding an explicit single-bit member of a scalarized multi-bit instTerm hides all the multi-bit owners of the instTerm as well as all the member bits of those instTerms.

When you call this function, one or more checks are done to ensure the hide operation is valid for the specified instTerm. An instTerm that is implicit, or in a non-unique hierarchy, or not reflected in the module domain cannot be hidden. The checks are performed in a particular order, and if the instTerm cannot be hidden, an exception is thrown as follows:

  1. Check whether the instTerm is implicit, and if it is, throw oacCannotHideImplicitInstTerm.
  2. Check whether the instTerm is in a non-unique hierarchy, and if it is, throw oacCannotModifyInstTermInNonUniqueHier.
  3. Check whether the instTerm is reflected in the module domain, and if not, throw oacCannotHideBlockOnlyInstTerm.

Exceptions:
oacCannotHideBlockOnlyInstTerm 
oacCannotHideImplicitInstTerm 
oacCannotModifyInstTermInNonUniqueHier 
oacCannotBlockOverrideNonScalarizedDesign 
oacCannotBlockOverrideNetSignalType 

oaBoolean oaInstTerm::isBound (    )  const
 

This function returns a boolean value indicating whether the instance associated with this instTerm is bound and if the associated terminal exists in the instance master.

oaBoolean oaInstTerm::isImplicit (    )  const
 

This function returns a boolean value indicating whether this instTerm is implicit, having been created as a result of the creation of a multi-bit instTerm.

void oaInstTerm::removeFromNet (    ) 
 

This function removes this instTerm from the net to which it is attached. If this instTerm is not attached to a net, this function does nothing.

Exceptions:
oacCannotModifyImplicitInstTerm 
oacCannotModifyInstTermInNonUniqueHier 

void oaInstTerm::scalarize (    ) 
 

This function ensures that the bits associated with the connection formed by this instTerm are explicit and available to support implementation data.

If this instTerm represents a multibit connection, this function scalarizes all corresponding single-bit connections. That is, for each bit of the connection, the implicit instTerm and its associated bitNet are made explicit. After processing all of the bits in the connection, the instTerm is made implicit. This ensures that no implementation data such as routes, parasitics, or other annotation can be added to the instTerm. If the instTerm becomes implicit, any associated impmentation data is removed from it.

Exceptions:
oacCannotScalarizeImplicitInstTerm 
oacCannotModifyInstTermInNonUniqueHier 

void oaInstTerm::setRouteMethod (  oaRouteMethod    routeMethod ) 
 

This function changes the route method for this instTerm.

Parameters:
routeMethod The new routeMethod value for this instTerm
Exceptions:
oacCannotModifyImplicitInstTerm 

oaBoolean oaInstTerm::usesTermPosition (    )  const
 

This function returns a boolean indicating whether this instTerm was created to connect to a terminal position. This function returns 'true' if this instTerm binds to a particular terminal position. It returns 'false' if this instTerm binds to a terminal by name.

Member Enumeration Documentation

anonymous enum
 

Enumeration values:
dtIndex 

The documentation for this class was generated from the following files:

Return to top of page




Copyright © 2002 - 2010 Cadence Design Systems, Inc.
All Rights Reserved.