edu.byu.ece.edif.core
Class EdifLibraryManager

java.lang.Object
  extended by 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

  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

EdifLibrary.findInstancedLibraryCells(EdifCell)


addLeafCell


addCellDeep


EdifLibrary containsCell(EdifCell)


deleteCell


findBlackBoxes


findCellInstancesOf


findEarliestLibraryToAdd


findEarliestPositionToAdd


findLatestLibraryToAdd


findLastestPositionToAdd


findEarliestPositionToAdd

  1. calls EdifLibrary.findInstancedLibraryCells(EdifLibrary)
  2. calls EdifLibrary.findInstancedLibraryCells(EdifCell)

findNonReferencedCells()


getCell(String)


getCells()


getCells(String)


getFirstPrimitiveLibrary


getLibraries()


getLibrary(String)


nameClash()


pruneNonReferencedCells()


tagLeafCellsAsPrimitives()


tagPrimitives()


toEdif


toString


trimToSize


validateOrder


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)