byucc.edif.tools.merge
Class EdifMergeParser

java.lang.Object
  byucc.edif.tools.merge.EdifMergeParser

public class EdifMergeParser
extends java.lang.Object

Provides Edif parsing capability as well as the ability to "merge" edif definitions from more than one edif file. This class contains a number of static methods that are used together to provide the merging capability.

TODO: Describe the control flow for "matching" (i.e. the order the methods are called).

TODO: This class is probably mis-named. It is not a parser but a set of classes that are used to match. A better name might be EdifCellMatching.

Version:

$Id: EdifMergeParser.java,v 1.56 2007/02/20 23:31:09 jonjohn Exp $

See Also:

EdifParser

Field Summary

static boolean	DEBUG
static java.lang.String[]	EDIF_EXTENSIONS The types of acceptable extensions for EDIF files.

Constructor Summary

EdifMergeParser()

Method Summary

static boolean	containsArgument(java.lang.String[] args, java.lang.String arg)
static EdifCell	copyCellDeep(EdifCell cellToCopy, EdifLibrary targetLib, EdifLibraryManager elm, EdifMergingPolicy mergingPolicy) Recursively copy an EdifCell from one EdifLibraryManager to another.
static java.util.Set<java.lang.String>	createDefaultDirs() Create a Collection of "default" directories that should be searched for black box definitions.
static EdifCell	findMatchingCell(EdifCell blackBox, EdifEnvironment env) Searches for a matching EdifCell definition in an existing, unrelated EdifEnvironment object.
static EdifCell	findMatchingCellInDir(EdifCell blackBox, java.lang.String dir, java.io.PrintStream outstream) Searches a given directory for an Edif file with a name that is the same as the Cell name.
static EdifCell	findMatchingCellInFile(EdifCell blackBox, java.lang.String filename, java.io.PrintStream outstream) Searches for a matching EdifCell definition in an external file.
static EdifCell	findMatchingEdifCellInterface(EdifLibrary lib, EdifCell cell) Searches for an EdifCell object in a given library whose interface matches the interface of the EdifCell parameter.
static EdifCell	findMatchingEdifCellInterface(EdifLibraryManager elm, EdifCell cell) Searches the EdifLibraryManager parameter for an EdifCell that matches the EdifCell parameter.
static EdifLibrary	findMatchingLibrary(EdifLibrary inputLibrary, EdifLibraryManager elm) This method will investigate all EdifCell objects found within each library in the group and compare it with the passed in library (the passed in library is not necessarily a member of the manager).
static java.util.Collection<EdifPort>	getMatchingBusPorts(EdifCellInterface cellInt, EdifPort port) Returns an unordered Collection of EdifPorts in the cellInt interface that match the multi-bit bus port "port".
static java.util.Map	getMatchingMultiBitPorts(EdifCellInterface ref, EdifCellInterface compare) The key of the Map is a multi-bit EdifPort in "ref" and the value is a Collection of single-bit EdifPort objects in "compare" that match the "ref" multi-bit EdifPort.
static EdifEnvironment	getMergedEdifEnvironment(java.lang.String filename, java.util.Collection<java.lang.String> dirs, java.util.Collection<java.lang.String> files, EdifLibrary primLib, java.io.PrintStream outstream, java.util.Map<java.lang.String,EdifEnvironment> fileNameToEnv) Parse an edif file and recursively merge in all black boxes encountered.
static EdifEnvironment	getMergedEdifEnvironment(java.lang.String filename, java.lang.String[] args) This static method will parse the top-level Edif file and merge the appropriate EdifFiles into this object.
static java.util.Map<EdifPort,java.util.Collection<EdifPort>>	getOneToManyPortMatches(EdifCell c1, EdifCell c2) This method will compare the cell interfaces of c1 and c2 to see if there are any multi-bit ports in C1 that match a group of single-bit ports in C2.
static java.util.Map	getOneToOnePortMatches(EdifCell c1, EdifCell c2) Returns a Map between matching ports in the two different EdifCell objects.
static void	main(java.lang.String[] args) Sample "main" to demonstrate the merging of edif files.
static boolean	matchingCellInterfaceBusExpansion(EdifCell cell1, EdifCell cell2) Performs a comparison between the port interfaces of two EdifCell objects.
static void	modifyPortRefsEqualize(EdifCellInstance eci, java.util.Map definitionExpandedPorts, java.util.Map blackBoxExpandedPorts, java.util.Map oneToOnePorts, java.io.PrintStream outstream) This method will modify all of the port refs to the black box to properly reflect the change in the interface of the definition.
static EdifEnvironment	parseAndMerge(java.lang.String[] args, EdifLibrary primLib) This method will parse a given Edif filename and merge any appropriate EDIF files as specified by arguments in the args parameter.
static EdifEnvironment	parseAndMergeEdif(java.lang.String topFilename, java.util.Collection<java.lang.String> dirs, java.util.Collection files, EdifLibrary primLib, java.io.PrintStream outstream) This method will parse a given Edif filename and merge any appropriate EDIF files if necessary.
static java.util.Set<java.lang.String>	parseArguments(java.lang.String[] args, java.lang.String flag) A simple method for parsing arguments.
static java.util.Set	parseArguments(java.lang.String[] args, java.lang.String flag, int numValues)
static void	replaceBlackBox(EdifCell blackBox, EdifCell definition, java.io.PrintStream outstream, EdifMergingPolicy mergingPolicy) This method will replace the "blackBox" EdifCell object with the "definition" EdifCell object.

Methods inherited from class java.lang.Object

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

Field Detail

EDIF_EXTENSIONS

public static final java.lang.String[] EDIF_EXTENSIONS

The types of acceptable extensions for EDIF files. *

DEBUG

public static final boolean DEBUG

See Also:

Constant Field Values

Constructor Detail

EdifMergeParser

public EdifMergeParser()

Method Detail

copyCellDeep

public static EdifCell copyCellDeep(EdifCell cellToCopy,
                                    EdifLibrary targetLib,
                                    EdifLibraryManager elm,
                                    EdifMergingPolicy mergingPolicy)

Recursively copy an EdifCell from one EdifLibraryManager to another. During the copy, cells (instanced by the cell to be copied) may be added to other libraries within the EdifLibraryManager.

Parameters:

cellToCopy - the EdifCell object to copy

targetLib - the EdifLibrary to copy the cell into. If no EdifLibrary is specified (null), the EdifCell will be placed in an EdifLibrary with the same name (or a new unique name if there is a clash) as it's old EdifLibrary

elm - the EdifLibraryManager to copy the cell into

Returns:

a reference to the new copy of the EdifCell object

getOneToOnePortMatches

public static java.util.Map getOneToOnePortMatches(EdifCell c1,
                                                   EdifCell c2)

Returns a Map between matching ports in the two different EdifCell objects. In order for these ports to match, it is first checked if they return true on a call to the method EdifPort.equals(EdifPort). This is a strict match between the two ports. If false is returned, there may still be a match if the names of the two different EdifPorts differ slightly. For example, a port named "port0" will match a port named "port_0_". The key of the Map is a Port from c1 and the value is a Port from c2.

getOneToManyPortMatches

public static java.util.Map<EdifPort,java.util.Collection<EdifPort>> getOneToManyPortMatches(EdifCell c1,
                                                                                             EdifCell c2)

This method will compare the cell interfaces of c1 and c2 to see if there are any multi-bit ports in C1 that match a group of single-bit ports in C2.

Returns:

A map whose key is an EdifPort in c1 and whose value is a Collection of EdifPort objects in c2 that match.

getMatchingBusPorts

public static java.util.Collection<EdifPort> getMatchingBusPorts(EdifCellInterface cellInt,
                                                                 EdifPort port)

Returns an unordered Collection of EdifPorts in the cellInt interface that match the multi-bit bus port "port". The goal is to try and find a set of single-bit ports in this interface that can be combined to match a reference multi-bit port. In order for a match to occur, there must be N single-bit ports whose basenames match the multi-bit port. The multi-bit port width must be N. If no match can be found, a null will be returned.

Parameters:

port - The multi-bit edif port used for the reference

policy - The naming policy used to perform the match

Returns:

A collection of EdifPort objects that when combined will match the given EdifPort object. Returns a null if no match is found

getMatchingMultiBitPorts

public static java.util.Map getMatchingMultiBitPorts(EdifCellInterface ref,
                                                     EdifCellInterface compare)

The key of the Map is a multi-bit EdifPort in "ref" and the value is a Collection of single-bit EdifPort objects in "compare" that match the "ref" multi-bit EdifPort. Note: This method is not currently used by any other method in this class.

findMatchingEdifCellInterface

public static EdifCell findMatchingEdifCellInterface(EdifLibrary lib,
                                                     EdifCell cell)

Searches for an EdifCell object in a given library whose interface matches the interface of the EdifCell parameter. In order for this method to return a matching EdifCell object, the following conditions must hold:

1. The name of the EdifCell in the library must match the name of the EdifCell parameter
2. The port interface of the EdifCell must match the port interface of the parameter. Note that two different methods will be used to check this interface. First, EdifCell.equalsInterface(EdifCell) will be called to perform an exact match on the ports. If this fails, matchingCellInterfaceBusExpansion(EdifCell, EdifCell) will be called to see if the interfaces match when busses are expanded in either of the cells.

Parameters:

lib - EdifLibrary in which to search for a match

cell - EdifCell to match

Returns:

The matching EdifCell object. This method will return a null if no match is found.

findMatchingEdifCellInterface

public static EdifCell findMatchingEdifCellInterface(EdifLibraryManager elm,
                                                     EdifCell cell)

Searches the EdifLibraryManager parameter for an EdifCell that matches the EdifCell parameter. This method calls findMatchingEdifCellInterface(EdifLibrary, EdifCell) to perform this search.

Parameters:

elm - EdifLibraryManager to search.

cell - EdifCell to match

Returns:

The matching EdifCell object. This method will return a null if no match is found.

findMatchingCell

public static EdifCell findMatchingCell(EdifCell blackBox,
                                        EdifEnvironment env)

Searches for a matching EdifCell definition in an existing, unrelated EdifEnvironment object. This method will call findMatchingEdifCellInterface(EdifLibraryManager, EdifCell) to perform this search.

Parameters:

blackBox -

env -

Returns:

The matching EdifCell object. This method will return a null if no match is found.

findMatchingCellInFile

public static EdifCell findMatchingCellInFile(EdifCell blackBox,
                                              java.lang.String filename,
                                              java.io.PrintStream outstream)

Searches for a matching EdifCell definition in an external file. This method will call findMatchingCell(EdifCell,EdifEnvironment) to perform this search.

Parameters:

blackBox - EdifCell object that this method is trying to match

filename - The filename to open and search for a matching EdifCell.

Returns:

The EdifCell object found within this file that matches the blackBox EdifCell parameter. This method returns a null if no match is found.

findMatchingCellInDir

public static EdifCell findMatchingCellInDir(EdifCell blackBox,
                                             java.lang.String dir,
                                             java.io.PrintStream outstream)

Searches a given directory for an Edif file with a name that is the same as the Cell name. Multiple extensions will be searched if necessary.

findMatchingLibrary

public static EdifLibrary findMatchingLibrary(EdifLibrary inputLibrary,
                                              EdifLibraryManager elm)

This method will investigate all EdifCell objects found within each library in the group and compare it with the passed in library (the passed in library is not necessarily a member of the manager). This method will return the library within the manager that contains the most number of matches with the library that was passed in.

Returns:

The matching library

replaceBlackBox

public static void replaceBlackBox(EdifCell blackBox,
                                   EdifCell definition,
                                   java.io.PrintStream outstream,
                                   EdifMergingPolicy mergingPolicy)

This method will replace the "blackBox" EdifCell object with the "definition" EdifCell object. Port interfaces will be equalized if necessary.

Parameters:

blackBox - The "blackBox" EdifCell object that will be replaced. This EdifCell should contain NO contents.

definition - The EdifCell object that provides a "definition" for the black Box EdifCell. This EdifCell MUST contain contents.

modifyPortRefsEqualize

public static void modifyPortRefsEqualize(EdifCellInstance eci,
                                          java.util.Map definitionExpandedPorts,
                                          java.util.Map blackBoxExpandedPorts,
                                          java.util.Map oneToOnePorts,
                                          java.io.PrintStream outstream)

This method will modify all of the port refs to the black box to properly reflect the change in the interface of the definition.

Parameters:

eci - EdifCellInstance

blackBox - EdifCell to be modified

definition -

matchingCellInterfaceBusExpansion

public static boolean matchingCellInterfaceBusExpansion(EdifCell cell1,
                                                        EdifCell cell2)

Performs a comparison between the port interfaces of two EdifCell objects. Unlike the strict EdifCell.equalsInterface(EdifCell) method, this method will perform a match while allowing busses in one EdifCell interface to be expanded into individual bits and remain as a complete bus in the original EdifCell.

Parameters:

cell1 -

cell2 -

Returns:

true if the cell interfaces of the two cells match. False if there is no match.

parseAndMerge

public static EdifEnvironment parseAndMerge(java.lang.String[] args,
                                            EdifLibrary primLib)

This method will parse a given Edif filename and merge any appropriate EDIF files as specified by arguments in the args parameter. This method can be used by main methods to parse arguments and provide an EdifEnvironment in return. The following invocation of this method demonstrates the use of appropriate arguments:

        java <main class> <EDIF filename> -L <search dir #1> -L <search dir #2> \
                      -f <external EDIF filename>
 

The arguments are interpreted as follows:

• args[0] - original EDIF filename.
• Search directories - this method needs to search multiple directories in an attempt to find matching edif files. To add a search directories, use the "-L" flag (one external directory for each invokation of "-L").
• A specific edif filename can be specified for merging using the "-f" flag. Only one external filename should be specified for each external edif file.

Once the arguments have been parsed, this method will call parseAndMergeEdif(String, Collection, Collection, EdifLibrary, PrintStream). If there are any errors, this method will exit rather than throwing an exception.

Parameters:

args - String arguments that contain the filename, libraries, and external files needed for parsing.

primLib - Primitive library to use for primitive tagging. If the library is null, do not tag library elements for primitives

Returns:

The merged EdifEnvironment

parseAndMergeEdif

public static EdifEnvironment parseAndMergeEdif(java.lang.String topFilename,
                                                java.util.Collection<java.lang.String> dirs,
                                                java.util.Collection files,
                                                EdifLibrary primLib,
                                                java.io.PrintStream outstream)
                                         throws ParseException,
                                                java.io.FileNotFoundException

This method will parse a given Edif filename and merge any appropriate EDIF files if necessary. If successful, the result is returned as an EdifEnvironment object. The files to be merged are found in the directories contained by the dirs parameter, as well as the files contained in the files parameter. This task is accomplished by:

• Parse the top level EDIF design
• Parse all edif files in the files collection. This generates an EdifEnvironment for each edif file.
• Blackboxes are identified by a call to EdifLibraryManager.findBlackBoxes()
• The blackBoxes are iterated over, and each is compared to the EdifEnvironments generated from parsing the files on the command line. Matches are identified by a call to findMatchingCell(EdifCell, EdifEnvironment).
• If a match is not found, a call to findMatchingCellInDir(EdifCell, String, PrintStream) will search the directory specified by the string parameter for an edif file that matches the blackbox.
• After searching for blackbox matches, all successful matches are merged by a call to replaceBlackBox(EdifCell, EdifCell, PrintStream, EdifMergingPolicy).

This method can be used by main methods to parse arguments and provide an EdifEnvironment in return. TODO: - Use Javadoc "link" and "see" tags to highlight the key methods called from this method.

Parameters:

topFilename - Filename of "top" edif environment

dirs - A Collection of String directory names used to search for black box definitions. If this is null, no directories will be searched.

files - A Collection of String filenames that contain EdifCell definitions. These files will be parsed and searched when black box definitions are found.

primLib - Primitive library to use for primitive tagging. If the library is null, do not tag library elements for primitives

outstream - PrintStream to which output during the merge process should be directed.

Returns:

The merged EdifEnvironment

Throws:

ParseException

java.io.FileNotFoundException

createDefaultDirs

public static java.util.Set<java.lang.String> createDefaultDirs()

Create a Collection of "default" directories that should be searched for black box definitions. This method will include the directory "."

Returns:

parseArguments

public static java.util.Set<java.lang.String> parseArguments(java.lang.String[] args,
                                                             java.lang.String flag)

A simple method for parsing arguments. This method will search for arguments in the form . Each time the flag is used, the successor is added to a Collection of Strings. A null will be returned if no parsed arguments are found. This method uses a TreeSet to make sure that copies of the argument are not included in the set.

parseArguments

public static java.util.Set parseArguments(java.lang.String[] args,
                                           java.lang.String flag,
                                           int numValues)

Parameters:

args - An array of String objects, the arguments to be parsed

flag -

numValues -

Returns:

A Set of List values

containsArgument

public static boolean containsArgument(java.lang.String[] args,
                                       java.lang.String arg)

getMergedEdifEnvironment

public static EdifEnvironment getMergedEdifEnvironment(java.lang.String filename,
                                                       java.lang.String[] args)

This static method will parse the top-level Edif file and merge the appropriate EdifFiles into this object. This method will support a search path as well as the parsing of specific auxilliary edif files. This particular method is currently hard coded to expect the XilinxLibrary.

Parameters:

filename - Filename of the top-level EDIF file

args - The command line arguments (looking for -L directory searches and -f file searches

Returns:

The merged EdifEnvironment object.

getMergedEdifEnvironment

public static EdifEnvironment getMergedEdifEnvironment(java.lang.String filename,
                                                       java.util.Collection<java.lang.String> dirs,
                                                       java.util.Collection<java.lang.String> files,
                                                       EdifLibrary primLib,
                                                       java.io.PrintStream outstream,
                                                       java.util.Map<java.lang.String,EdifEnvironment> fileNameToEnv)
                                                throws java.io.FileNotFoundException,
                                                       ParseException

Parse an edif file and recursively merge in all black boxes encountered.

Parameters:

filename - Filename of the EDIF file

dirs - A collection of directories to search for black boxes

files - A collection of files to search for black boxes

primLib - A primitive library to use for tagging all primitives in the design. Leave null for no primitive tagging.

outstream - A PrintStream to direct output to.

fileNameToEnv - A map of filenames to parsed EdifEnvironments used for recursive processing. Leave null for the top-level file.

Returns:

The merged EdifEnvironment object.

Throws:

java.io.FileNotFoundException

ParseException

main

public static void main(java.lang.String[] args)

Sample "main" to demonstrate the merging of edif files.