hades.models
Class Design

java.lang.Object
  hades.simulator.SimObject
      hades.models.Design

All Implemented Interfaces:

java.lang.Cloneable, ContextToolTip, java.io.Serializable, Simulatable

public class Design

extends SimObject

implements java.io.Serializable

Design: a SimObject that represents a circuit built from a collection of other simulation models.

A Design may have a graphical representation (schematic) and may contain other Design objects, thereby allowing hierarchy. Usually, only the top-level Design object has a schematic. A Design has a reference to a simulator and the editor.

See Also:

Serialized Form

Field Summary

Fields inherited from class hades.simulator.SimObject

classloader, console, debug, editor, name, ports, propertySheet, symbol, visible

Constructor Summary

Design()

Design(Design parent, SimKernel simulator, java.lang.String name)
Construct a Design object called 'name' as a subdesign of 'parent'

Method Summary

void	addComponent(SimObject simobj) add a SimObject (a 'component') to this Design, using its own name.
void	addComponent(SimObject simobj, java.lang.String name) add a SimObject (a 'component') called 'name' to this Design If 'name' is already used in this Design, we automatically create a new unique name for the component.
void	addSignal(Signal signal) add a Signal under its own name to this Design
void	addSignal(Signal signal, java.lang.String name) add a Signal called 'name' to this Design
java.lang.String	changeComponentName(SimObject obj, java.lang.String newName) change a component's name.
int	checkDesign(boolean highlightErrors) check the current Design for typical errors and return the number of errors.
void	configure() create and display a 'ConfigDialog' to set the parameters for a SimObject.
java.lang.String	constructUniqueComponentName(java.lang.String name) construct a unique component name from given argument 'name'.
java.lang.String	constructUniqueSignalName(java.lang.String name) construct a unique signal name from given argument 'name'.
SimObject	copy() get a copy of the current Design.
Symbol	createSymbol() create a default Symbol for the current Design object.
void	deleteComponent(SimObject tmp) delete the SimObject 'tmp' from this Design.
void	deleteComponent(java.lang.String name) delete the SimObject (a 'component') called 'name' from this Design.
void	deleteSignal(Signal tmp) delete the Signal 'tmp' from this Design.
void	deleteSignal(java.lang.String name)
void	elaborate(java.lang.Object arg) elaborate(): This method is called by the simulation engine to initialize the simulation object.
SimObject	getComponent(java.lang.String name) get a reference to a component (SimObject) of this Design object via the components (short) name.
java.util.Enumeration	getComponents() get an Enumeration of all components of this Design
java.lang.String	getEscapedResourceName() return an encoded version of the resource name for this Design.
java.lang.String[]	getExternalResources() return a String[] array of length 1 with our current Hades design name
Port	getPort(java.lang.String name) get a reference to a port called 'name' if any
Port[]	getPorts() get a list of Ports on this SimObject
java.io.InputStream	getResourceAsStream(java.lang.String s) for Design, we want a slightly different algorithm to find resources.
java.lang.String	getResourceName()
Signal	getSignal(java.lang.String name) get a reference to a signal called 'name' in this Design
java.util.Enumeration	getSignals() get an Enumeration of all signals in this Design
SimKernel	getSimulator() return a reference to our simulation engine
java.lang.String	getSymbolResourceName() get the .sym Symbol resource name for this Design.
static Design	getTestDesign(int n_inverters)
java.lang.String	getToolTip(java.awt.Point position, long millis) construct a (short) tool tip message for a SimObject.
long	getVersionId()
boolean	initialize(java.lang.String s) initialize a (Sub)Design from a String.
static void	main(java.lang.String[] argv) main(): simple self test with inverter chain
boolean	needsExternalResources() we use one external resource: the Hades file to initialize us.
void	printAllComponents(java.lang.String indent)
void	printAllSignals(java.lang.String indent)
void	printComponents()
void	printToplevelSignals(java.lang.String indent)
void	read() read a Design object with subdesigns and components and signals from an InputStream.
void	setDesign(Design parent) set a new parent Design (together with it's SimKernel)
void	setDesignName(java.lang.String name) set a new name for this Design
void	setEditor(Editor editor) set the Editor for this Design
void	setResourceName(java.lang.String _name)
void	setSimulator(SimKernel simulator) set a new simulation engine for this Design
void	setSymbol(Symbol tmp) set a new Symbol for this Design
void	tearDown() tearDown(): called at the end of a simulation to clear up all references held by the SimObject.
java.lang.String	toString() toString() - the usual info method
java.lang.StringBuffer	toStringComponents(java.lang.StringBuffer sb, java.lang.String indent)
static void	usage() usage(): explain the parameters for main().
void	write(java.io.PrintWriter ps) write a Design object to a PrintWriter

Methods inherited from class hades.simulator.SimObject

constructDynamicSymbol, evaluate, getBindkey, getClassLoader, getDebug, getEditor, getFullName, getName, getParent, getPropertySheet, getSymbol, isVisible, keyPressed, message, mousePressed, needsDynamicSymbol, setClassLoader, setConsole, setDebug, setName, setParent, setPorts, setVersionId, setVisible

Methods inherited from class java.lang.Object

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

Constructor Detail

Design

public Design(Design parent,
              SimKernel simulator,
              java.lang.String name)

Construct a Design object called 'name' as a subdesign of 'parent'

Design

public Design()

Method Detail

needsExternalResources

public boolean needsExternalResources()

we use one external resource: the Hades file to initialize us.

Overrides:

needsExternalResources in class SimObject

getExternalResources

public java.lang.String[] getExternalResources()

return a String[] array of length 1 with our current Hades design name

Overrides:

getExternalResources in class SimObject

getResourceAsStream

public java.io.InputStream getResourceAsStream(java.lang.String s)

for Design, we want a slightly different algorithm to find resources. If the resourcename starts with a '/', we interpret it as a Java 1.1 resource name. Otherwise, things are not so clear. We should probably look for a file in the directory where we are.

Overrides:

getResourceAsStream in class SimObject

initialize

public boolean initialize(java.lang.String s)

initialize a (Sub)Design from a String. The String is expected to contain either of the following things:

instancename xpos ypos versionid resourcename

resourcename

The method returns true once all required data has been read.

Overrides:

initialize in class SimObject

configure

public void configure()

Description copied from class: SimObject

create and display a 'ConfigDialog' to set the parameters for a SimObject. The default ConfigDialog for the base class (SimObject) itself is empty except for the 'instance name' of the SimObject.

Overrides:

configure in class SimObject

setDesign

public void setDesign(Design parent)

set a new parent Design (together with it's SimKernel)

getSimulator

public final SimKernel getSimulator()

return a reference to our simulation engine

Overrides:

getSimulator in class SimObject

setSimulator

public void setSimulator(SimKernel simulator)

set a new simulation engine for this Design

Overrides:

setSimulator in class SimObject

setEditor

public void setEditor(Editor editor)

set the Editor for this Design

Overrides:

setEditor in class SimObject

setDesignName

public void setDesignName(java.lang.String name)

set a new name for this Design

setSymbol

public void setSymbol(Symbol tmp)

set a new Symbol for this Design

Overrides:

setSymbol in class SimObject

getVersionId

public long getVersionId()

Overrides:

getVersionId in class SimObject

getSymbolResourceName

public java.lang.String getSymbolResourceName()

get the .sym Symbol resource name for this Design. The current implementation of this method get the .hds resource name for the Design and replaces the extension from .hds to .sym. We need to override the method from hades.simulator.SimObject, because that implementation just uses the class name.

Overrides:

getSymbolResourceName in class SimObject

getResourceName

public java.lang.String getResourceName()

setResourceName

public void setResourceName(java.lang.String _name)

getEscapedResourceName

public java.lang.String getEscapedResourceName()

return an encoded version of the resource name for this Design.

While the resource name, as a standard Java string, may contain any Unicode characters, several parsers inside of HADES don't like special chars like spaces, tabs, etc. To avoid rewriting all those parsers, this method returns a 'Unicode escape' version of the resource Name, e.g. ' ' is replaced by ' '.

elaborate

public void elaborate(java.lang.Object arg)

Description copied from class: SimObject

elaborate(): This method is called by the simulation engine to initialize the simulation object.

Specified by:

elaborate in interface Simulatable

Overrides:

elaborate in class SimObject

addComponent

public void addComponent(SimObject simobj)

add a SimObject (a 'component') to this Design, using its own name. If 'name' is already used in this Design, we automatically create a new unique name for the component.

addComponent

public void addComponent(SimObject simobj,
                         java.lang.String name)

add a SimObject (a 'component') called 'name' to this Design If 'name' is already used in this Design, we automatically create a new unique name for the component.

constructUniqueComponentName

public java.lang.String constructUniqueComponentName(java.lang.String name)

construct a unique component name from given argument 'name'. This method tries to append a (small) integer ID to 'name', until the resulting String is unique.

changeComponentName

public java.lang.String changeComponentName(SimObject obj,
                                            java.lang.String newName)

change a component's name.

This is not so easy as it might seem, because this method is also called by SimObject.setName(), to avoid duplicate component names.

In order to avoid endless calling sequences between SimObject.setName() and changeComponentName(), we do the construction of an unique name and the deletion/insertion into the componentTable of this Design by hand (instead of caling addComponent).

deleteComponent

public void deleteComponent(java.lang.String name)

delete the SimObject (a 'component') called 'name' from this Design. This command also disconnects the component from all Signals, to keep our data structures consistent.

deleteComponent

public void deleteComponent(SimObject tmp)

delete the SimObject 'tmp' from this Design.

getComponent

public SimObject getComponent(java.lang.String name)

get a reference to a component (SimObject) of this Design object via the components (short) name.

getComponents

public java.util.Enumeration getComponents()

get an Enumeration of all components of this Design

addSignal

public void addSignal(Signal signal)

add a Signal under its own name to this Design

addSignal

public void addSignal(Signal signal,
                      java.lang.String name)

add a Signal called 'name' to this Design

constructUniqueSignalName

public java.lang.String constructUniqueSignalName(java.lang.String name)

construct a unique signal name from given argument 'name'. This method tries to append a (small) integer ID to 'name', until the resulting String is unique.

deleteSignal

public void deleteSignal(java.lang.String name)

deleteSignal

public void deleteSignal(Signal tmp)

delete the Signal 'tmp' from this Design.

getSignal

public Signal getSignal(java.lang.String name)

get a reference to a signal called 'name' in this Design

getSignals

public java.util.Enumeration getSignals()

get an Enumeration of all signals in this Design

getPorts

public Port[] getPorts()

Description copied from class: SimObject

get a list of Ports on this SimObject

Overrides:

getPorts in class SimObject

getPort

public Port getPort(java.lang.String name)

Description copied from class: SimObject

get a reference to a port called 'name' if any

Overrides:

getPort in class SimObject

printComponents

public void printComponents()

printAllComponents

public void printAllComponents(java.lang.String indent)

toStringComponents

public java.lang.StringBuffer toStringComponents(java.lang.StringBuffer sb,
                                                 java.lang.String indent)

printToplevelSignals

public void printToplevelSignals(java.lang.String indent)

printAllSignals

public void printAllSignals(java.lang.String indent)

checkDesign

public int checkDesign(boolean highlightErrors)

check the current Design for typical errors and return the number of errors. A protocol of all errors and warnings is written to the Console. Note that some errors printed by this method may be intentional; e.g. this method will mark buses with multiple drivers as having an error. If the "highlightErrors" flag is set, we try to highlight all components and signals that have errors.

tearDown

public void tearDown()

Description copied from class: SimObject

tearDown(): called at the end of a simulation to clear up all references held by the SimObject. Unfortunately, this is required as the garbage collector often fails to clean up the cyclic interdependencies between objects, signals, simulator and GUI fast enough. Note that the SimObject cannot be used after this method has been called. Should be overridden by subclasses as needed.

Overrides:

tearDown in class SimObject

read

public void read()

read a Design object with subdesigns and components and signals from an InputStream. The netlist format is very simple:

      // comment
      [hades.models.Design] TheNameOfThisDesign
      [components]
      hades.models.Design subdesignName pos_x pos_y
      ...
      hades.models.gates.Inv inverterName pos_x pos_y
      ...
      [end components]
      [signals]

      [end signals]
      ... [reserved]

      [end]
     

Nested designs/models use indentation.

write

public void write(java.io.PrintWriter ps)

write a Design object to a PrintWriter

Overrides:

write in class SimObject

copy

public SimObject copy()

get a copy of the current Design.

Overrides:

copy in class SimObject

createSymbol

public Symbol createSymbol()

create a default Symbol for the current Design object. We just step through the componentTable and create input Ports for all Ipin instances and output Ports for all Opin instances.

getToolTip

public java.lang.String getToolTip(java.awt.Point position,
                                   long millis)

construct a (short) tool tip message for a SimObject. This method should be overridden as needed.

Specified by:

getToolTip in interface ContextToolTip

Overrides:

getToolTip in class SimObject

toString

public java.lang.String toString()

toString() - the usual info method

Overrides:

toString in class SimObject

usage

public static void usage()

usage(): explain the parameters for main().

main

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

main(): simple self test with inverter chain

getTestDesign

public static Design getTestDesign(int n_inverters)