edu.byu.ece.edif.core
Class EdifLibraryManager

java.lang.Object
  edu.byu.ece.edif.core.EdifLibraryManager

All Implemented Interfaces:

EdifOut, Trimable, java.io.Serializable

public class EdifLibraryManager
extends java.lang.Object
implements Trimable, EdifOut, java.io.Serializable

Represents and manages a list of related EDIF libraries (EdifLibrary). This object has a parent EdifEnvironment object and a list of EdifLibrary objects. Each library must have a unique name and the uniqueness of the names is managed by a ArrayListNameSpaceResolver object.

The libraries within this object are related and must be managed according to the "define before use" rules of EDIF. This means that any EdifCell object instanced within a parent EdifCell object must be defined before the parent EdifCell is defined.

This object manages the ordering of EdifCell objects within libraries and the ordering of the libraries. Major issues:

addLibrary

• The purpose of this method is to add a library that is currently not a part of this manager and link it into this manager correctly.

1. throws NameDuplicationException if there is a name conflict
2. do not rename! A valid name must be given.
3. Do we need to go through and validate the references of cells

• in the added library to those libraries that have already been added? It seems like we should go through all of the previously defined libraries and match by name those library elements that are referenced by the cells in the library we are adding.

EdifLibrary.findInstancedLibraryCells(EdifCell)

• Should add a parameter that says whether to find instances by name or find instances by reference.

addLeafCell

• Used by only addCellDeep
• This method doesn't seem to make sense here. This class can be used to help find the appropriate library, but most of the method should be performed somewhere else. It would probably best fit in the EdifMergeParser class.

addCellDeep

• used by EdifMergeParser. Move to this class

EdifLibrary containsCell(EdifCell)

• change to "getLibraryContainingCell".
• Return null if there is no library that contains the cell. This method performs a search based on reference, not name. Note that the "boolean EdifLibrary.containsCell(EdifCell)" method called by this method does not need a name change.

deleteCell

• Get rid of this method. Call the EdifLibrary version as needed.
• We need a better way of managing the deletion of cells in the libraries. It is possible that a cell is deleted but there are still references to the cell. We would want to generate an exception when this occurs ("ReferencedCell deletion exception").
• The delete code would need to check all successor libraries to see if the cell was referenced and if it was, generate an exception.

findBlackBoxes

• keep.
• Methods in EdifLibraryManager may look much the same as EdifLibrary

findCellInstancesOf

• OK.
• Bad name (should be findInstancesOf(EdifCell)) however, there are similar methods: EdifLibrary.findCellInstancesOf(EdifCell) EdifCell.findCellInstancesOf(EdifCell) (This is worth doing at some point)
• Only findEarliestPositionToAdd is used by any method (addLibrary). All of these methods can be removed so long as the "library ordering" problem is solved. This ordering is needed by "addLibrary" to make sure a library is added at the proper time (this goes under the addLibrary issue).

findEarliestLibraryToAdd

findEarliestPositionToAdd

findLatestLibraryToAdd

findLastestPositionToAdd

findEarliestPositionToAdd

1. calls EdifLibrary.findInstancedLibraryCells(EdifLibrary)
2. calls EdifLibrary.findInstancedLibraryCells(EdifCell)
   • Uses reference matching to see if the cell uses the library.
   • It should use name matching.

findNonReferencedCells()

• keep this method.

getCell(String)

• this method has problems as it is possible to have more than one EdifCell with the same name but in different libraries. Need to use "getCells" method and fix all references to this method.

getCells()

• ok

getCells(String)

• ok

getFirstPrimitiveLibrary

• this is an awkward method. Perhaps there should be a different class that manages primitive libraries. I suppose it is ok here.

getLibraries()

• ok

getLibrary(String)

• need to fix for lower case name compare

nameClash()

• keep this method but modify it so that it conforms to some interface. Give a EdifNameable as a parameter.

pruneNonReferencedCells()

• keep method (useful). Update as necessary.
• Don't call delete method as a part of this class. Instead, do the following for each EdifCell object that you get from the findNonReferencedCells:
  • call deleteCell on the library in which the cell resides.

tagLeafCellsAsPrimitives()

• awkward. Need to have a special package that handles all of this primitive handling. I think the best place for this would be byucc.edif.libraries (although primitives would be a better name). Why would you want to tag all libraries as primitives? This makes no sense (used by EdifRandomCircuit).

tagPrimitives()

• move to the new Primitive handling classes.

toEdif

toString

trimToSize

validateOrder

• this is awkward. The data structure should always be valid. Track down when and how this is used and remove this method.

Primitive handling:

1. create new class byucc.edif.libraries.PrimitiveHandling
2. tagLeafCellsAsPrimitives method for tagging

Version:

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

See Also:

EdifLibrary, Serialized Form

Field Summary

private EdifEnvironment	_edifEnvironment The EdifEnvironment that points to this library manager.
private EdifNameSpaceList<EdifLibrary>	_libraries The EdifLibrary objects of this file.

Constructor Summary

EdifLibraryManager(EdifEnvironment edifFile)
Construct an EdifLibraryManager Object with the specified EdifEnvironment.

Method Summary

void	addLibraries(java.util.Collection<EdifLibrary> libraries)
boolean	addLibrary(EdifLibrary library) Add a library to this library manager, and sets its library manager to 'this'
EdifLibrary	containsCell(EdifCell cell) Search for the given cell among all libraries.
boolean	containsLibrary(EdifLibrary lib) This function only checks the library using the Object.equals() method.
boolean	containsLibrary(java.lang.String libraryName) This version of the function will check the library's name against library names of those it already contains.
boolean	deleteCell(EdifCell cell, boolean force) Delete a cell from the library manager, and return whether or not the delete was successful.
java.util.Collection<EdifCell>	findBlackBoxes() This method will search through all EdifCells in the current Manager and determine which cells are not defined.
java.util.Collection<EdifCellInstance>	findCellInstancesOf(EdifCell cell) This method will return a list of EdifCellInstances in the entire libraryManager that reference the passed in cell.
EdifLibrary	findEarliestLibraryToAdd(EdifCell cell, boolean addToPrimitiveLibraryOK) This method returns the earliest library that this cell can be added to.
int	findEarliestPositionToAdd(EdifLibrary add) Return the earliest position to add the library within the collection of libraries, so as to avoid violating the define before use rule.
EdifLibrary	findLatestLibraryToAdd(EdifCell cell, boolean addToPrimitiveLibraryOK) This method returns the latest library that this cell can be added to.
int	findLatestPositionToAdd(EdifLibrary add) Return the latest position to add the library within the collection of libraries, so as to avoid violating the define before use rule.
java.util.Collection<EdifCell>	findNonReferencedCells(EdifCell topCell) Starting at the top cell, find all cells referenced by it either directly or indirectly through recursion and return a Collection of EdifCells that are not referenced.
EdifCell	getCell(java.lang.String name) Return the first cell whose name matches the give String.
java.util.List<EdifCell>	getCells() This method will return a List of all cells in the library manager.
java.util.Collection<EdifCell>	getCells(java.lang.String name) Return all the EdifCell objects whose name matches the give String.
java.util.List<java.util.List<EdifLibrary>>	getDFSForest()
EdifEnvironment	getEdifEnvironment() Return the file pointing to this library manager.
EdifLibrary	getFirstPrimitiveLibrary() Return the first primitive library in the collection of libraries.
java.util.List<EdifLibrary>	getLibraries() Return the libraries contained by this library manager.
EdifLibrary	getLibrary(java.lang.String lib) Return the library based on the string lib.
EdifNameable	getUniqueLibraryNameable(EdifLibrary lib)
EdifNameable	getUniqueLibraryNameable(EdifNameable en)
java.util.List<EdifLibrary>	getValidLibraryOrder()
java.util.Iterator<EdifLibrary>	iterator() Return iterator of the EdifLibrary objects contained within this object.
boolean	nameClash(EdifLibrary lib) Return true if the library can be added to the library name space, otherwise false.
void	pruneNonReferencedCells() Prune cells that are not referenced (recursively) by the top cell.
void	pruneNonReferencedCells(EdifCell topCell) Prune cells that are not referenced (recursively) by the top cell.
void	toEdif(EdifPrintWriter epw) Print the Edif equivalent of this EdifLibraryManager.
java.lang.String	toString()
void	trimToSize() Trim to size all Trimmable objects in this library manager.
private void	visitCell(EdifCell cell, java.util.Set<EdifCell> visited)
private void	visitLib(EdifLibrary lib, java.util.List<EdifLibrary> currentTree, java.util.List<EdifLibrary> unvisitedLibs, java.util.List<EdifLibrary> finishedLibs) Visit a library during the depth first search topological sort.

Methods inherited from class java.lang.Object

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

Field Detail

_edifEnvironment

private EdifEnvironment _edifEnvironment

The EdifEnvironment that points to this library manager.

_libraries

private EdifNameSpaceList<EdifLibrary> _libraries

The EdifLibrary objects of this file. Note that the order of libraries within this list matters - there is a partial order between libraries (i.e. sub-cells must be defined previous to the instance of the sub-cell).

Constructor Detail

EdifLibraryManager

public EdifLibraryManager(EdifEnvironment edifFile)

Construct an EdifLibraryManager Object with the specified EdifEnvironment.

Parameters:

edifFile - The EdifEnvironment that contains this EdifLibraryManager

Method Detail

addLibrary

public boolean addLibrary(EdifLibrary library)
                   throws EdifNameConflictException

Add a library to this library manager, and sets its library manager to 'this'

TODO: should this method even exist?

Parameters:

library - The library to add into this manager, defaulted to add at the earliest position

Returns:

True if the library was added

Throws:

EdifNameConflictException

See Also:

findLatestPositionToAdd(EdifLibrary)

addLibraries

public void addLibraries(java.util.Collection<EdifLibrary> libraries)
                  throws EdifNameConflictException

Throws:

EdifNameConflictException

containsCell

public EdifLibrary containsCell(EdifCell cell)

Search for the given cell among all libraries. If the EdifCell exists in a library, it returns the given library. Otherwise, it returns null.

containsLibrary

public boolean containsLibrary(EdifLibrary lib)

This function only checks the library using the Object.equals() method.

Parameters:

lib -

Returns:

containsLibrary

public boolean containsLibrary(java.lang.String libraryName)

This version of the function will check the library's name against library names of those it already contains.

Parameters:

libraryName - name of the library to be checked

Returns:

true if the library name is already contained in this Library Manager, false if not.

deleteCell

public boolean deleteCell(EdifCell cell,
                          boolean force)

Delete a cell from the library manager, and return whether or not the delete was successful.

Parameters:

cell - The cell to be deleted.

force - Forces the cell to be deleted even if it's still referenced within the library manager.

Returns:

True if the cell was deleted.

See Also:

EdifLibrary.deleteCell(EdifCell,boolean)

findBlackBoxes

public java.util.Collection<EdifCell> findBlackBoxes()

This method will search through all EdifCells in the current Manager and determine which cells are not defined.

The purpose of this method is to identify those EdifCell objects that are "undefined". This may be used to search for other Edif files that describe the given black box.

Returns:

A collection of EdifCells that are Black boxes, or undefined, and non-primitive

See Also:

EdifLibrary.findBlackBoxes()

findCellInstancesOf

public java.util.Collection<EdifCellInstance> findCellInstancesOf(EdifCell cell)

This method will return a list of EdifCellInstances in the entire libraryManager that reference the passed in cell. This method will return null if no EdifCellInstances are found.

Parameters:

cell - The cell to check references for

Returns:

A collection of EdifCellInstance Objects in this library manager that refer to the passed-in cell

See Also:

EdifLibrary.findCellInstancesOf(EdifCell)

findEarliestLibraryToAdd

public EdifLibrary findEarliestLibraryToAdd(EdifCell cell,
                                            boolean addToPrimitiveLibraryOK)

This method returns the earliest library that this cell can be added to. All of the passed in EdifCell's EdifCellInstances must instance cells declared inside or after the library it will get added to.

Parameters:

cell - The cell to be added into which library.

addToPrimitiveLibraryOK - Specifies whether or not it is ok to add the cell to a primitive library.

Returns:

The earliest library to add the cell in.

See Also:

findEarliestPositionToAdd(EdifLibrary)

findEarliestPositionToAdd

public int findEarliestPositionToAdd(EdifLibrary add)

Return the earliest position to add the library within the collection of libraries, so as to avoid violating the define before use rule.

Parameters:

add - The library to add to the earliest position

Returns:

The exact position to add this library to

See Also:

findEarliestPositionToAdd(EdifLibrary)

findLatestLibraryToAdd

public EdifLibrary findLatestLibraryToAdd(EdifCell cell,
                                          boolean addToPrimitiveLibraryOK)

This method returns the latest library that this cell can be added to. If the passed in EdifCell is referenced in a library then it has to be added to the position at or before the referring library.

Parameters:

cell - The cell to be added into which library.

addToPrimitiveLibraryOK - Specifies whether or not it is ok to add the cell to a primitive library.

Returns:

The latest library to add the cell in.

See Also:

findLatestPositionToAdd(EdifLibrary)

findLatestPositionToAdd

public int findLatestPositionToAdd(EdifLibrary add)

Return the latest position to add the library within the collection of libraries, so as to avoid violating the define before use rule.

Parameters:

add - The library to add to the latest position

Returns:

The exact position to add this library to

See Also:

EdifLibraryManager#findPositionToAdd

findNonReferencedCells

public java.util.Collection<EdifCell> findNonReferencedCells(EdifCell topCell)

Starting at the top cell, find all cells referenced by it either directly or indirectly through recursion and return a Collection of EdifCells that are not referenced.

Returns:

a Collection not referenced (recursively) - this means that a cell returned in the collection could be referenced by another cell, but it is part of a different tree than the main tree

getCell

public EdifCell getCell(java.lang.String name)

Return the first cell whose name matches the give String.

This method is awkward and likely to cause errors. There may be many cells within a set of libraries of a given name and it doesn't seem safe to have a method that only returns the first element of a given name. Other approachecs should be used and this method should be removed. The user of this method includes: - XilinxLibrary.findOrAddXilinxPrimitive (used to find a Xilinx primitive in the manager) (This method is used by many other methods) - LUTReplace.logicLutRam.Replace (this method should call the xilinx verion).

Parameters:

name - The name of the cell to return

Returns:

An EdifCell whose name matches the given String

See Also:

EdifLibrary.getCell(String)

getCells

public java.util.List<EdifCell> getCells()

This method will return a List of all cells in the library manager. The cells will be returned in proper order (from lowest to highest).

Returns:

A List Object of all the cells in the entire library manager.

getCells

public java.util.Collection<EdifCell> getCells(java.lang.String name)

Return all the EdifCell objects whose name matches the give String.

Parameters:

name - The name of the cell to return

Returns:

A Collection of EdifCell objects

See Also:

EdifLibrary.getCell(String)

getDFSForest

public java.util.List<java.util.List<EdifLibrary>> getDFSForest()

Returns:

a List of EdifLibrary objects in a valid order according to the define before use rule. The order is computed using a topological sort.

getEdifEnvironment

public EdifEnvironment getEdifEnvironment()

Return the file pointing to this library manager.

Returns:

The EdifEnvironment that contains this library manager.

getFirstPrimitiveLibrary

public EdifLibrary getFirstPrimitiveLibrary()

Return the first primitive library in the collection of libraries. Useful when a primitive must be added to a primitive library.

Returns:

The first Primitive Library

getLibraries

public java.util.List<EdifLibrary> getLibraries()

Return the libraries contained by this library manager.

Returns:

A List of the EdifLibrary objects within this library manager.

getLibrary

public EdifLibrary getLibrary(java.lang.String lib)

Return the library based on the string lib.

TODO: lower case compare?

Parameters:

lib - The String that will be used to find the library

Returns:

The EdifLibrary whose name matches lib

getValidLibraryOrder

public java.util.List<EdifLibrary> getValidLibraryOrder()

Returns:

a List of EdifLibrary objects in a valid order according to the define before use rule. The order is computed using a topological sort.

iterator

public java.util.Iterator<EdifLibrary> iterator()

Return iterator of the EdifLibrary objects contained within this object.

Returns:

An Iterator Object of the libraries within this library manager.

nameClash

public boolean nameClash(EdifLibrary lib)

Return true if the library can be added to the library name space, otherwise false.

Parameters:

lib - The library to chech to see if there is a name clash with this libraries of this library manager

Returns:

True if there is a clash, false if not

pruneNonReferencedCells

public void pruneNonReferencedCells(EdifCell topCell)

Prune cells that are not referenced (recursively) by the top cell.

Parameters:

topCell - the design's top cell

pruneNonReferencedCells

public void pruneNonReferencedCells()

Prune cells that are not referenced (recursively) by the top cell.

getUniqueLibraryNameable

public EdifNameable getUniqueLibraryNameable(EdifNameable en)

getUniqueLibraryNameable

public EdifNameable getUniqueLibraryNameable(EdifLibrary lib)

toEdif

public void toEdif(EdifPrintWriter epw)

Print the Edif equivalent of this EdifLibraryManager.

Specified by:

toEdif in interface EdifOut

Parameters:

epw - The EdifPrintWriter Object that the interfacing Object will write EDIF data to

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

trimToSize

public void trimToSize()

Trim to size all Trimmable objects in this library manager.

Specified by:

trimToSize in interface Trimable

visitLib

private void visitLib(EdifLibrary lib,
                      java.util.List<EdifLibrary> currentTree,
                      java.util.List<EdifLibrary> unvisitedLibs,
                      java.util.List<EdifLibrary> finishedLibs)

Visit a library during the depth first search topological sort.

Parameters:

lib - The EdifLibrary to visit

currentLib - A List of libraries to add libraries to

unvisitedLibs - A List of unvisited libraries

finishedLibs - A List of finished libraries

visitCell

private void visitCell(EdifCell cell,
                       java.util.Set<EdifCell> visited)