edu.byu.ece.edif.core
Class EdifNet

java.lang.Object
  edu.byu.ece.edif.core.NamedPropertyObject
      edu.byu.ece.edif.core.EdifNet

All Implemented Interfaces:

EdifOut, Properties, Trimable, java.io.Serializable

public class EdifNet
extends NamedPropertyObject
implements EdifOut, Trimable

Represents an EDIF signal net. A net within EDIF is defined by a collection of edif port references. Specifically, the net is connected to each edif port reference in the collection. This implementation of EdifNet contains contains a reference to the EdifCell that contains this net. This class also contains an array of EdifPortRef objects that attach to the net.

Sample EDIF code for an EdifNet:

  (net sgn_exp 
  (joined
  (portRef (member sgn_exp 0))
  (portRef DI (instanceRef L_3_U2))
  (portRef I1 (instanceRef L_3_l_4))
  )
  )
 

To Do:

• Provide some form of a clone method
• We need a better way of handling the toString method for all classes. What is the purpose of this method?
• Why have EdifNet's toEdif method write EdifPortRef's EDIF data? Have: EdifPortRef do the toEdif method.
• TMR - is there a way that the EdifNet can keep track of which EdifPortRef objects refer to a parent, and which connect only to EdifCellInstances? a method such as connectedToEdifCell(), which returns a boolean
• TMR - Could we add 2 methods - connectedToTopLevelInput() and connectedToTopLevelOutput() - this would add storage of only 2 booleans per EdifNet, and should be relatively easy to keep track of when a net is created and connections are added. It would most likely result in a great speed-up to the TMR stuff.

Version:

$Id:EdifNet.java 198 2008-04-16 21:14:21Z jamesfcarroll $

See Also:

EdifPortRef, Serialized Form

Field Summary

private java.util.ArrayList<EdifPortRef>	_attachedPortRefs List of EdifPortRef objects that this net is connected to.
private EdifCell	_parent The reference to the parent EdifCell

Constructor Summary

EdifNet(EdifNameable name)
Construct an empty, parentless, named EdifNet Object.

EdifNet(EdifNameable name, EdifCell parent)
Construct an empty, named EdifNet Object with the specified parent.

EdifNet(java.lang.String name)
Construct an empty, parentless, named EdifNet Object.

EdifNet(java.lang.String name, EdifCell parent)
Construct an empty, named EdifNet Object with the specified parent.

Method Summary

EdifPortRef	addPortConnection(EdifCellInstance eci, EdifPort p) TODO: Remove this method and force the caller to create a new EdifPortRef() and then add that using addPortConnection(EdifPortRef epr) -B
EdifPortRef	addPortConnection(EdifCellInstance eci, EdifPort p, int busMember) Deprecated. Remove this method. Force the caller to create the EdifPortRef first and use the method addPortConnection(EdifPortRef epr)
EdifPortRef	addPortConnection(EdifCellInstance eci, java.lang.String portName) Add a port connection to the given port on the given instance onto this net.
EdifPortRef	addPortConnection(EdifCellInstance eci, java.lang.String portName, int busMember) Deprecated. This method should be removed.
EdifPortRef	addPortConnection(EdifPortRef portref) Add a pre-defined EdifPortRef port connection to the net.
EdifPortRef	addTopLevelPortConnection(EdifPort port) Deprecated. Remove this method. The caller should create a new EdifPortRef and use the constructor addPortConnection(EdifPortRef epr)
EdifPortRef	addTopLevelPortConnection(java.lang.String portName) Deprecated. We should remove this method. We should force the caller to find the Port rather than doing this here. There is too much opportunity for run-time errors with this method.
EdifNet	copy(EdifCell parent) Return a deep copy of this Object.
boolean	deletePortConnection(EdifPortRef delete) Detach an EdifPortRef from this EdifNet.
EdifPortRef	getAttachedPortRef(EdifCellInstance cell, EdifPort port) Return the EdifPortRef on this EdifNet that references the given EdifPort/EdifCellInstance combination or null if no EdifPortRef on this EdifNet references the given combination.
java.util.Collection<EdifPortRef>	getAttachedPortRefs(EdifCellInstance cell) This method will return a list of all EdifPortRef objects attached to the given EdifCellInstance.
java.util.Collection<EdifPortRef>	getConnectedPortRefs() Return a list of EdifPortRef objects which are attached to this net.
EdifPortRef	getEdifPortRef(EdifCellInstance inst, EdifSingleBitPort singlePort) Return the EdifPortRef object attached to the given instance and single bit port.
java.util.Collection<EdifPortRef>	getInOutPortRefs() This method will return all EdifPortRef in this EdifNet object that are connected to ports of type "inout".
java.util.Collection<EdifPort>	getInOutPorts() Provide a Colletion of EdifPortRef objects that are attached to this EdifNet and connected to tri-state ports (inout).
java.util.Collection<EdifPortRef>	getInputPortRefs() This method will return all EdifPortRef in this EdifNet object that are connected to ports of type "input".
java.util.Collection	getNetDriven() Deprecated. Use getSinkPortRefs(boolean, boolean) in place of this method.
java.util.Collection	getNetDrivers() Deprecated. Use getSourcePortRefs(boolean, boolean) in place of this method.
java.util.Collection<EdifPortRef>	getOutputPortRefs() This method will return all EdifPortRef in this EdifNet object that are connected to ports of type "output".
java.util.Collection<EdifPort>	getOutputPorts() Provide a Colletion of EdifPortRef objects that are attached to this EdifNet and connected to true output ports.
EdifCell	getParent() Return a reference to the parent EdifCell (owner of net).
java.util.Iterator	getPortRefIterator() Create an iterator for the EdifPortRef objects owned by this net.
java.util.List<EdifPortRef>	getPortRefList()
java.util.Collection<EdifPortRef>	getSinkPortRefs(boolean tristate, boolean includeTopPorts) Return all EdifPortRef objects in this EdifNet object that are "sinks".
java.util.Collection<EdifPortRef>	getSourcePortRefs(boolean tristate, boolean includeTopPorts) This method will return all EdifPortRef objects in this EdifNet object that are "sources".
boolean	hasTopLevelPortConnection() This method will determine whether or not the given net connects to at least one top-level port.
boolean	isAttached(EdifCellInstance cell) This method will examine the EdifPortRef objects connected to this net and determine whether the given EdifCellInstance is connected or not to the given EdifNet.
boolean	isAttached(EdifCellInstance cell, EdifPort port) This method will return true if the given EdifPort/EdifCellInstance combination are attached to the given EdifNet.
boolean	isAttached(EdifCellInstance cell, EdifSingleBitPort singlePort) Determine if this EdifNet object is connected to the given instance and single-bit port.
boolean	samePorts(EdifNet net) This method does a deep compare on the current net with the passed-in net.
(package private) void	setParent(EdifCell cell) Set the reference to the parent EdifCell.
void	toEdif(EdifPrintWriter epw) Convert this object to EDIF format and write it to the passed-in EdifPrintWriter Object.
java.lang.String	toString() String representation of the EdifNet with detailed information.
void	trimToSize() Trim to size this object and all contained Trimmable Objects.

Methods inherited from class edu.byu.ece.edif.core.NamedPropertyObject

addProperty, addProperty, addPropertyList, copyProperties, equals, equalsProperties, getEdifNameable, getName, getOldName, getProperty, getPropertyList, rename, rename, rename

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

_attachedPortRefs

private java.util.ArrayList<EdifPortRef> _attachedPortRefs

List of EdifPortRef objects that this net is connected to. Limit the size initial List so that we don't waste memory on unused list elements.

_parent

private EdifCell _parent

The reference to the parent EdifCell

Constructor Detail

EdifNet

public EdifNet(java.lang.String name)
        throws InvalidEdifNameException

Construct an empty, parentless, named EdifNet Object.

Parameters:

name - The name of this EdifNet Object

Throws:

InvalidEdifNameException

EdifNet

public EdifNet(EdifNameable name)

Construct an empty, parentless, named EdifNet Object.

Parameters:

name - The Object that contains name information about this object

EdifNet

public EdifNet(java.lang.String name,
               EdifCell parent)
        throws InvalidEdifNameException

Construct an empty, named EdifNet Object with the specified parent.

Parameters:

name - The name of this EdifNet Object

parent - The parent EdifCell Object of this EdifNet

Throws:

InvalidEdifNameException

EdifNet

public EdifNet(EdifNameable name,
               EdifCell parent)

Construct an empty, named EdifNet Object with the specified parent.

Parameters:

name - The Object that contains name information about this object

parent - The parent EdifCell Object of this EdifNet

Method Detail

addPortConnection

public EdifPortRef addPortConnection(EdifPortRef portref)

Add a pre-defined EdifPortRef port connection to the net. The EdifPortRef object must be created before calling this method. This method makes the following assumptions (these assumptions are not checked):

• The EdifCellInstance referred by the port ref is owned by the same EdifCell that owns this EdifNet.
• The EdifNet referred by the port ref is "this".

If any of these assumptions are violated, an incoherent data structure will result.

TODO: Should we check these assumptions?

Parameters:

portref - The EdifPortRef to connect to the net.

addPortConnection

public EdifPortRef addPortConnection(EdifCellInstance eci,
                                     java.lang.String portName)

Add a port connection to the given port on the given instance onto this net.

TODO: We should remove this method. We should force the caller to find the Port rather than doing this here. There is too much opportunity for run-time errors with this method.

This is only referenced in halflatch and TMR -B

Parameters:

eci - The EdifCellInstance whose parent contains the port referred to by the passed-in portName

portName - The name of the port contained by the parent to the passed-in EdifCellInstance Object

addPortConnection

public EdifPortRef addPortConnection(EdifCellInstance eci,
                                     EdifPort p)

TODO: Remove this method and force the caller to create a new EdifPortRef() and then add that using addPortConnection(EdifPortRef epr) -B

Parameters:

eci -

p -

addPortConnection

public EdifPortRef addPortConnection(EdifCellInstance eci,
                                     java.lang.String portName,
                                     int busMember)

Deprecated. This method should be removed.

Add a port connection to the net.

TODO: Remove this method. What happens if the string parameter for the port name fails to match in the method getPort?

This method is never used -B

Parameters:

eci - The EdifCellInstance whose parent contains the port referred to by the passed-in portName

portName - The name of the port contained by the parent to the passed-in EdifCellInstance Object

addPortConnection

public EdifPortRef addPortConnection(EdifCellInstance eci,
                                     EdifPort p,
                                     int busMember)

Deprecated. Remove this method. Force the caller to create the EdifPortRef first and use the method addPortConnection(EdifPortRef epr)

Add a port connection to the net.

TODO: Remove this method. Force the caller to create the EdifPortRef first and use the method addPortConnection(EdifPortRef epr)

Parameters:

eci - The EdifCellInstance whose parent contains the port referred to by the passed-in portName

p - The port contained by the parent to the passed-in EdifCellInstance Object

addTopLevelPortConnection

public EdifPortRef addTopLevelPortConnection(java.lang.String portName)

Deprecated. We should remove this method. We should force the caller to find the Port rather than doing this here. There is too much opportunity for run-time errors with this method.

TODO: We should remove this method. We should force the caller to find the Port rather than doing this here. There is too much opportunity for run-time errors with this method.

This is only referenced in halflatch -B

addTopLevelPortConnection

public EdifPortRef addTopLevelPortConnection(EdifPort port)

Deprecated. Remove this method. The caller should create a new EdifPortRef and use the constructor addPortConnection(EdifPortRef epr)

TODO: Remove this method. The caller should create a new EdifPortRef and use the constructor addPortConnection(EdifPortRef epr)

This is never used -B

Parameters:

port -

copy

public EdifNet copy(EdifCell parent)

Return a deep copy of this Object. No Object, except String, is copied over using '='. All are done using the 'new' statement, copying all the insides verbatim.

Parameters:

parent - The EdifCell Object that will become the parent of the copied EdifNet

Returns:

An EdifNet 'copy' of this Object, having the passed-in EdifCell as its parent

deletePortConnection

public boolean deletePortConnection(EdifPortRef delete)

Detach an EdifPortRef from this EdifNet.

Parameters:

delete - The EdifPortRef to remove from this EdifNet Objects list of EdifPortRefs

Returns:

True if the EdifPortRef was found and deleted

getAttachedPortRef

public EdifPortRef getAttachedPortRef(EdifCellInstance cell,
                                      EdifPort port)

Return the EdifPortRef on this EdifNet that references the given EdifPort/EdifCellInstance combination or null if no EdifPortRef on this EdifNet references the given combination.

Parameters:

cell - An EdifCellInstance Object to check if one of the EdifPortRefs in this EdifNet Object connect to a port of that instance

port - An EdifPort Object to check if one of the EdifPortRefs in this EdifNet Object refer to that port

Returns:

an EdifPortRef if this EdifNet is attached to the passed-in EdifPort/EdifCellInstance combination

getAttachedPortRefs

public java.util.Collection<EdifPortRef> getAttachedPortRefs(EdifCellInstance cell)

This method will return a list of all EdifPortRef objects attached to the given EdifCellInstance.

This method is only used by EdifCellInstance. Shouldn't EdifCellInstance then be responsible for the work of this method? EdifCellInstance could do the work by first getting the iterator using the getPortRefIterator() method. -B

TODO: better name for method

TODO: remove this method

Parameters:

cell - The instance to find port refs of this EdifNet that attach to this instance

Returns:

A Collection of EdifPortRef Objects that attach to the passed-in EdifCellInstance

getConnectedPortRefs

public java.util.Collection<EdifPortRef> getConnectedPortRefs()

Return a list of EdifPortRef objects which are attached to this net.

Returns:

A safe copy of the Collection of EdifPortRef objects attached to this net.

getEdifPortRef

public EdifPortRef getEdifPortRef(EdifCellInstance inst,
                                  EdifSingleBitPort singlePort)

Return the EdifPortRef object attached to the given instance and single bit port.

Parameters:

inst - The EdifCellInstance reference attached to this EdifNet

singlePort - The single-bit port within the instance type attached to the net.

Returns:

The EdifPortRef object that connects the net to the port of the instance.

getInOutPortRefs

public java.util.Collection<EdifPortRef> getInOutPortRefs()

This method will return all EdifPortRef in this EdifNet object that are connected to ports of type "inout". This method does not distinguish between EdifPortRefs that are connected to top-level ports versus those connected to instances.

Returns:

A Collection of EdifPortRef Objects that are connected to inout ports.

getInOutPorts

public java.util.Collection<EdifPort> getInOutPorts()

Provide a Colletion of EdifPortRef objects that are attached to this EdifNet and connected to tri-state ports (inout).

Returns:

A Collection of EdifPort Objects that are connected to this EdifNet Object

getInputPortRefs

public java.util.Collection<EdifPortRef> getInputPortRefs()

This method will return all EdifPortRef in this EdifNet object that are connected to ports of type "input".

Note that this does NOT provide a list of "sink" EdifPortRefs as it returns the top-level input port refs that are actually "sources". Use getSinkPortRefs(boolean, boolean) to obtain all "sink" EdifPortRefs.

Returns:

A Collection of EdifPortRef objects that are connected to this EdifNet Object and attached to a port that is of type Input.

getNetDriven

@Deprecated
public java.util.Collection getNetDriven()

Deprecated. Use getSinkPortRefs(boolean, boolean) in place of this method.

This method will return all portrefs that can be driven on the current net. This will return all EdifPortRef objects that are associated with EdifCellInstances (i.e. EdifPortRef.getCellInstance() returns a non-null) and are inputs. This method will also return EdifPortRef objects that are associated with an EdifCell (i.e. EdifPortRef.getCellInstance() returns null) and is an output. These EdifPortRef objects refer to top-level output ports that can be driven by the given net.

Returns:

A Collection of EdifPortRefs that are driven by this EdifNet Object

getNetDrivers

@Deprecated
public java.util.Collection getNetDrivers()

Deprecated. Use getSourcePortRefs(boolean, boolean) in place of this method.

This method will return all portrefs that can drive on the current net.

Returns:

A Collection of EdifPortRef Objects that can drive this EdifNet Object

getOutputPortRefs

public java.util.Collection<EdifPortRef> getOutputPortRefs()

This method will return all EdifPortRef in this EdifNet object that are connected to ports of type "output".

Note that this does NOT provide a list of "Source" EdifPortRefs as it returns the top-level output ports that are actually "sinks". Use getSourcePortRefs(boolean, boolean) to obtain the edif port refs that are sources.

Returns:

A Collection of EdifPortRef objects that are connected to this EdifNet Object and attached to a port that is of type OUTPUT.

getOutputPorts

public java.util.Collection<EdifPort> getOutputPorts()

Provide a Colletion of EdifPortRef objects that are attached to this EdifNet and connected to true output ports.

Returns:

A Collection of Output EdifPort Objects that are connected to this EdifNet Object

getParent

public EdifCell getParent()

Return a reference to the parent EdifCell (owner of net).

Returns:

The parent EdifCell object

getPortRefIterator

public java.util.Iterator getPortRefIterator()

Create an iterator for the EdifPortRef objects owned by this net. An safe empty Iterator will be returned if there are no attached port refs.

getPortRefList

public java.util.List<EdifPortRef> getPortRefList()

Returns:

An ArrayList of all the EdifPortRef objects associated with this EdifNet.

getSinkPortRefs

public java.util.Collection<EdifPortRef> getSinkPortRefs(boolean tristate,
                                                         boolean includeTopPorts)

Return all EdifPortRef objects in this EdifNet object that are "sinks". This includes those EdifPortRef objects connected to input ports of EdifCellInstances and EdifPortRef objects connected to top-level output ports.

This method is different than the getInputPortRefs() method in that this method distinguishes between input ports that are sinks and those that are sources (top-level input ports are sources).

Parameters:

tristate - Indicates whether tristate ports should be included (true indicates that tri-state ports should not be included; false indicates that tristate ports should be ignored).

includeTopPorts - Indicates whether connections to top-level ports should be included (true indicates that port refs to top-level ports should be included, false indicates that these port refs should be ignored).

Returns:

A Collection of EdifPortRef objects that are sinks on the net. If there are no sink ports, this method will return an empty but valid Collection.

See Also:

EdifPort.isOutput(boolean).

getSourcePortRefs

public java.util.Collection<EdifPortRef> getSourcePortRefs(boolean tristate,
                                                           boolean includeTopPorts)

This method will return all EdifPortRef objects in this EdifNet object that are "sources". This includes those EdifPortRef objects connected to output ports of EdifCellInstances and EdifPortRef objects connected to top-level input ports.

This method is different than the getOutputPortRefs() method in that this method distinguishes between output ports that are sources and those that are sinks (top-level output ports are sinks).

Parameters:

tristate - Indicates whether tristate ports should be included or not (true indicates that tri-state ports should be considered as "sources" and thus include corresponding port refs in the collection. False indicates that tri-state ports should not be considered as sources and thus ignore port refs to these connections).

includeTopPorts - Indicates whether connections to top-level ports should be included (true indicates that port refs to top-level ports should be included, false indicates that these port refs should be ignored).

Returns:

A Collection of EdifPortRef objects that are sources on the net. If there are no source ports, this method will return an empty but valid Collection.

See Also:

EdifPort.isOutput(boolean)

hasTopLevelPortConnection

public boolean hasTopLevelPortConnection()

This method will determine whether or not the given net connects to at least one top-level port. This occurs when any owned EdifPortRef object has a "null" for its EdifCellInstance object.

Returns:

true if the current EdifNet connects to at least one top-level port, false if the current EdifNet has no connections to a top-level port.

isAttached

public boolean isAttached(EdifCellInstance cell)

This method will examine the EdifPortRef objects connected to this net and determine whether the given EdifCellInstance is connected or not to the given EdifNet.

Parameters:

cell - The EdifCellInstance Object that will be tested to see if it connects to this EdifNet Object

Returns:

True if this EdifNet Object is attached to the passed-in EdifCellInstance Object

isAttached

public boolean isAttached(EdifCellInstance cell,
                          EdifPort port)

This method will return true if the given EdifPort/EdifCellInstance combination are attached to the given EdifNet.

Parameters:

cell - An EdifCellInstance Object to check if one of the EdifPortRefs in this EdifNet Object connect to a port of that instance

port - An EdifPort Object to check if one of the EdifPortRefs in this EdifNet Object refer to that port

Returns:

True if this EdifNet is attached to the passed-in EdifPort/EdifCellInstance combination

isAttached

public boolean isAttached(EdifCellInstance cell,
                          EdifSingleBitPort singlePort)

Determine if this EdifNet object is connected to the given instance and single-bit port.

Parameters:

cell - Instance object to search for

singlePort - The single-bit port to search for

See Also:

getEdifPortRef(edu.byu.ece.edif.core.EdifCellInstance, edu.byu.ece.edif.core.EdifSingleBitPort)

samePorts

public boolean samePorts(EdifNet net)

This method does a deep compare on the current net with the passed-in net. The two nets must have the same name, same number of connected ports, and a port connected to one net must match the name of a port connected to the other net.

Parameters:

net - The net to compare to this net

Returns:

True if both nets have the same structure, false otherwise.

toEdif

public void toEdif(EdifPrintWriter epw)

Convert this object to EDIF format and write it to the passed-in EdifPrintWriter Object.

Specified by:

toEdif in interface EdifOut

Parameters:

epw - The EdifPrintWriter Object that the EDIF data will be written to

toString

public java.lang.String toString()

String representation of the EdifNet with detailed information.

Overrides:

toString in class java.lang.Object

Returns:

a String value representing this Object and its EdifPortRefs

trimToSize

public void trimToSize()

Trim to size this object and all contained Trimmable Objects.

TODO: Why do we frist test to see if the ArrayList is Trimmable? shoulden't this always be true? -B

Specified by:

trimToSize in interface Trimable

setParent

void setParent(EdifCell cell)

Set the reference to the parent EdifCell. Note: Adding this net to a cell will set the parent of this net to that cell.

Parameters:

cell - an EdifCell value that will become the new parent cell of this EdifNet