byucc.jhdl.base
Class HWSystem

java.lang.Object
  byucc.jhdl.base.Nameable
      byucc.jhdl.base.Node
          byucc.jhdl.base.HWSystem

All Implemented Interfaces:

BooleanFlags, TreeListable

Direct Known Subclasses:

HardwareSystem

public class HWSystem

extends Node

This class defines a the top-level node for a circuit. All circuit-level issues, such as stepping and cycling, are taken care of in this class.

Field Summary

static HWSystem	_hws
static int	CLOCK_DOMAIN
static int	EVENT_DRIVEN
static int	HARDWARE_READBACK
static int	SINGLE_CLOCK
static int	SOFTWARE_CHECKPOINT

Fields inherited from interface byucc.jhdl.base.BooleanFlags

ANTECEDANT_IS_BEHAVIORALLY_MODELED, ASYNC_PORT, ASYNCHRONOUS_RESOLVED, ATOMICALLY_PLACEABLE, ATOMICALLY_UNMAPPABLE, BEHAVIORALLY_MODELED_BRANCH, CLK_PORT, CLOCK_METHOD_IMPLEMENTED_BY_USER, CLOCK_METHOD_IS_DISABLED, CLOCKABLE_IS_SCHEDULED, DANGLING_IS_OK, DELETE_MARK, FATAL_BUILD_ERROR_OCCURED, HAS_BEEN_TRACED, HAS_USER_SPECIFIED_NAME, HWUPDATE, IMPLICIT_PORT, IN_CLK_PORT, IN_PORT, INOUT_PORT, IO_TYPE_FLAGS, IS_BEHAVIORALLY_MODELED, IS_ON_BUILD_STACK, IS_ON_PROP_LIST, IS_PLACED, METHODS_IMPLEMENTED_BY_USER, NETLISTABLE, ORIG_WIRE_IS_ATOMIC, OUT_PORT, PLACEMENT_IS_LOCKED, PROPAGATE_METHOD_IMPLEMENTED_BY_USER, PROPAGATE_METHOD_IS_DISABLED, RECURSION_FLAG, RESET_METHOD_IMPLEMENTED_BY_USER, SIMULATEABLE, SOURCELESS_IS_OK, SYNC_PORT, VISIBLE

Constructor Summary

HWSystem()
Creates a nameless HWSystem.

HWSystem(int simulator)
Unnamed constructor, used to pick a registered Simulator

HWSystem(byucc.jhdl.base.Simulator sim)
Unnamed constructor for unregistered Simulators

HWSystem(java.lang.String name)
Used build the default HWSystem with a name.

HWSystem(java.lang.String name, int simulator)
Used to pick a registered Simulator.

HWSystem(java.lang.String name, int simulator, byucc.jhdl.base.Simulator sim)
Creates a named system

HWSystem(java.lang.String name, byucc.jhdl.base.Simulator sim)
Constructor for passing a non-registered Simulator.

Method Summary

void	addObservable(Observable obs) Adds an Observable to the circuit.
void	addSimulatorCallback(SimulatorCallback sc) Adds a SimulatorCallback to the circuit.
protected boolean	check() Returns true if this node was valid.
boolean	collectTransitionCountEnabled() This method returns true if transition counts have been enabled, false if they have not been set.
boolean	collectTransitionCountEnabled(boolean flag) This method enables (true) or disables (false) the transition counts in the current HWSystem.
void	cycle(int no_clocks) This method is invoked to advance the simulator by no_clocks.
boolean	cycleHardware(int no_steps) Runs a hardware platform, provided the system is in hardware mode and the root node implements HardwareInterface.
Wire	declareExternalClock(Wire clock_wire) This declares a wire to be an external clock.
void	disableAllHWUpdate() As a matter of convenience, this will disable all HWUpdating of all Clockable cells returning to pure simulation.
void	enableProgrammaticTestBench() Called by Jab (or somebody) if we want to use programmatic testbenches.
Nameable	findNamed(java.lang.String name) Used to search the circuit graph for a node or wire by name.
boolean	findPropagated(Wire w) Finds the propagated wire in the global schedule
void	forceSimulatorCallbackRefresh() This method can be used to force a call to the sim_update of all SimulatorCallbacks and Observables.
void	forceSimulatorInitialize() Forces a simulator (re)initialization
boolean	forceUniquify() Returns the status of system-wide uniquification.
boolean	forceUniquify(boolean flag) Sets the status of system-wide uniquification.
Checkpointable[]	getCheckpointableCells() Method to get the list of all CheckpointableCells
int	getClockValue(Wire clock) Convenient for getting the current clock value.
int	getClockValue(Wire clock, int future_step) This function exists to allow the user access to the values of the clock schedule.
int	getCurrentStepCount() Gets the current step count
java.lang.String	getDefaultClockSchedule() In some cases, users may want to see what the current schedule is for the default clock.
ExternallyUpdateable[]	getExternallyUpdateableCells() Method to get the list of ExternallyUpdateableCells
boolean	getHardwareMode() Whether the simulator is in hardware mode
LargeExternallyUpdateable[]	getLargeExternallyUpdateableCells() Method to get the list of all LargeExternallyUpdateableCells
int	getLastClockValue(Wire clock) Convenient for getting the prior clock value.
int	getNextClockValue(Wire clock) Convenient for getting the next clock value.
int	getSimulationErrorCount() This returns the number of floating or multiple driver errors on the last simulation run.
int	getStepsPerClock() Returns the number of steps per clock
Cell	getTestBench() A HWSystem should have only one child and it should be a test bench, based on constructors.
int	getTotalClockCount() Simple accessor.
CellList	getUnscheduledSourceCells() Returns the unscheduled cells
boolean	getUsingImplicitClock() Gets the usingImplicitClock flag.
void	haltSimulator()
boolean	hardwareModeSane() Whether the simulator is in hardware mode & a valid hardware interface exists
void	initialize() This will force an initialize of all of the internal data structures of the HWSystem at the appropriate time (it may not happen immediately.
boolean	isRoot() Returns true, as the HWSystem is the root.
boolean	isSimulatorInitialized() Whether the simulator is initialized
void	libraryDefaultClock() This should only be called by libraries.
boolean	multiClockModeEnabled() Whether the circuit is in multi-clock mode.
boolean	multiClockModeEnabled(boolean flag) Deprecated. flag is completely ignored; this will just return multiClockModeEnabled().
boolean	netlistCheck() Checks that the circuit is valid for netlisting
void	optimizeForSimulation() Optimizes the circuit for simulation
void	printSimulatorInternals(java.io.OutputStream output_stream) Prints the status of the simulator
long	printTransitionCounts(java.io.OutputStream os) This will print out all of the transition counts for every wire in the current testbench and it's corresponding children.
long	printTransitionCounts(java.io.OutputStream os, Cell c) This will print out all of the transition counts for every wire in the target Cell and it's children.
void	readSystemState(java.io.InputStream is) This is to cause the ExternalUpdate Manager to load the state of system from the State object corresponding to the given cycle count
void	readSystemState(int cycle, int step) This is to cause the ExternalUpdate Manager to load the state of system from the State object corresponding to the given cycle count
void	readSystemState(java.lang.String name, int cycle, int step) This is to cause the ExternalUpdate Manager to load the state of system from the State object corresponding to the given cycle count
void	removeSimulatorCallback(SimulatorCallback sc) Adds a SimulatorCallback to the circuit.
void	reset() This will reset the simulation.
void	setDefaultClockSchedule(java.lang.String schedule) Allows users to modify the current default clock schedule.
java.lang.String	setHardwareMode(boolean value) This tells that simulator that you will or will not be using the hardware versus the simulator.
void	setUsingImplicitClock() Sets the usingImplicitClock flag.
void	skip(int no_steps) This method is invoked to advance the simulator by no_clocks.
void	step(int no_steps) This method is invoked to advance the simulator by no_steps.
void	updateHardware() Performs a hardware readback without stepping the hardware clock.
void	useHWUpdate(Clockable cell, boolean flag) This tells the simulator that you will use HWUpdate mode to update the state of the Clockable cell you pass as the argument.
void	writeSystemState() This is to cause the ExternalUpdate Manager to dump the current state of the system to a StateObject...
void	writeSystemState(java.io.OutputStream os) This is to cause the ExternalUpdate Manager to dump the current state of the system to a StateObject...
void	writeSystemState(java.lang.String name) This is to cause the ExternalUpdate Manager to dump the current state of the system to a StateObject...
void	writeSystemStateToHardware() Writes the simulator system state to hardware, if the current loaded model allows it

Methods inherited from class byucc.jhdl.base.Node

checkAll, delete, getBuildingFlag, getChildren, getChildrenEnumeration, getDefaultClock, getInstanceName, getParent, getParentCell, getRelatives, getSystem, getWires, optimize, orphanAllowed, postorderCheck, preorderCheck, printAllChildren, printTree, setDefaultClock, subClassDelete, toString

Methods inherited from class byucc.jhdl.base.Nameable

caseSensitivity, caseSensitivity, disableNameClashChecking, getFullName, getFullNameNoTestBench, getHierNameNoTestBench, getInstanceNo, getInstanceNumber, getLeafName, getLeafName, getRelativeName, getUserName, getUserName, hasUserSpecifiedName, isDescendantOf, setInstanceNumber

Methods inherited from class java.lang.Object

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

Field Detail

SINGLE_CLOCK

public static final int SINGLE_CLOCK

See Also:

Constant Field Values

CLOCK_DOMAIN

public static final int CLOCK_DOMAIN

See Also:

Constant Field Values

HARDWARE_READBACK

public static final int HARDWARE_READBACK

See Also:

Constant Field Values

SOFTWARE_CHECKPOINT

public static final int SOFTWARE_CHECKPOINT

See Also:

Constant Field Values

EVENT_DRIVEN

public static final int EVENT_DRIVEN

See Also:

Constant Field Values

_hws

public static HWSystem _hws

Constructor Detail

HWSystem

public HWSystem(java.lang.String name,
                int simulator,
                byucc.jhdl.base.Simulator sim)

Creates a named system

Parameters:

name - the name of the system

HWSystem

public HWSystem()

Creates a nameless HWSystem.

HWSystem

public HWSystem(java.lang.String name)

Used build the default HWSystem with a name.

Parameters:

name - Name of HWSystem

HWSystem

public HWSystem(java.lang.String name,
                int simulator)

Used to pick a registered Simulator.

Parameters:

name - Name of HWSystem

simulator - Number of the registered Simulator

HWSystem

public HWSystem(int simulator)

Unnamed constructor, used to pick a registered Simulator

Parameters:

simulator - Number of the registered Simulator

HWSystem

public HWSystem(java.lang.String name,
                byucc.jhdl.base.Simulator sim)

Constructor for passing a non-registered Simulator.

Parameters:

name - HWSystem name

sim - a Simulator

HWSystem

public HWSystem(byucc.jhdl.base.Simulator sim)

Unnamed constructor for unregistered Simulators

Parameters:

sim - a Simulator

Method Detail

initialize

public void initialize()

This will force an initialize of all of the internal data structures of the HWSystem at the appropriate time (it may not happen immediately.

forceUniquify

public final boolean forceUniquify()

Returns the status of system-wide uniquification. If this is true, then all cells created will be uniquified in netlists and elsewhere, overriding any designation by Cell.cellInterfaceDeterminesUniqueNetlistStructure(). Defaults to false.

Returns:

the system-wide uniquification status

forceUniquify

public final boolean forceUniquify(boolean flag)

Sets the status of system-wide uniquification. If this is true, then all cells created will be uniquified in netlists and elsewhere, overriding any designation by Cell.cellInterfaceDeterminesUniqueNetlistStructure(). Defaults to false.

Parameters:

flag - the new value of the flag

Returns:

the prior value of the flag

getExternallyUpdateableCells

public ExternallyUpdateable[] getExternallyUpdateableCells()

Method to get the list of ExternallyUpdateableCells

Returns:

List of ExternallyUpdateableCells

getLargeExternallyUpdateableCells

public LargeExternallyUpdateable[] getLargeExternallyUpdateableCells()

Method to get the list of all LargeExternallyUpdateableCells

Returns:

List of LargeExternallyUpdateableCells

getCheckpointableCells

public Checkpointable[] getCheckpointableCells()

Method to get the list of all CheckpointableCells

Returns:

List of CheckpointableCells

isRoot

public boolean isRoot()

Returns true, as the HWSystem is the root.

Returns:

true, because a system can only be a root.

check

protected boolean check()

Returns true if this node was valid. For now, this is assumed to always be the case.

Returns:

true if valid.

getTestBench

public Cell getTestBench()

A HWSystem should have only one child and it should be a test bench, based on constructors.

Returns:

the TestBench child of this system (null if not declared yet)

addObservable

public void addObservable(Observable obs)

Adds an Observable to the circuit. This allows the use of Observerables that are not cells. Any object that implements the Observable interface may be added. - MJW

Overrides:

addObservable in class Node

Parameters:

obs - the observable to add

addSimulatorCallback

public void addSimulatorCallback(SimulatorCallback sc)

Adds a SimulatorCallback to the circuit.

Overrides:

addSimulatorCallback in class Node

Parameters:

sc - the SimulatorCallback to add

removeSimulatorCallback

public void removeSimulatorCallback(SimulatorCallback sc)

Adds a SimulatorCallback to the circuit.

Overrides:

removeSimulatorCallback in class Node

Parameters:

sc - the SimulatorCallback to add

getTotalClockCount

public int getTotalClockCount()

Simple accessor. Get the total number of clock cycles executed in the simulator up to this point.

Returns:

the total number of clock cycles up to this point.

getCurrentStepCount

public int getCurrentStepCount()

Gets the current step count

Returns:

the current step count within a cycle

getStepsPerClock

public int getStepsPerClock()

Returns the number of steps per clock

Returns:

the number of steps per clock

getClockValue

public int getClockValue(Wire clock,
                         int future_step)

This function exists to allow the user access to the values of the clock schedule. The user should be able to ignore what they set the schedule to and interpret all values from these functions.

Functions requires current_step, total_steps, total_clock_count, a list of all the clock drivers.

Parameters:

clock - the clock to look at

future_step - how far to extrapolate the schedule

Returns:

the clockdriver's value at current_step + future_step

getClockValue

public int getClockValue(Wire clock)

Convenient for getting the current clock value.

Parameters:

clock - the clock to look at

Returns:

the clockdriver's value at current_step

See Also:

getClockValue(Wire, int)

getNextClockValue

public int getNextClockValue(Wire clock)

Convenient for getting the next clock value.

Parameters:

clock - the clock to look at

Returns:

the clockdriver's value at current_step + 1

See Also:

getClockValue(Wire, int)

getLastClockValue

public int getLastClockValue(Wire clock)

Convenient for getting the prior clock value.

Parameters:

clock - the clock to look at

Returns:

the clockdriver's value at current_step - 1

See Also:

getClockValue(Wire, int)

optimizeForSimulation

public void optimizeForSimulation()

Optimizes the circuit for simulation

netlistCheck

public boolean netlistCheck()

Checks that the circuit is valid for netlisting

Returns:

true if it checks out

getUnscheduledSourceCells

public CellList getUnscheduledSourceCells()

Returns the unscheduled cells

Returns:

a list of unscheduled cells

findNamed

public Nameable findNamed(java.lang.String name)

Used to search the circuit graph for a node or wire by name.

Parameters:

name - the full, hierarchical name of the object you are searching for.

Returns:

the Nameable object if found, null otherwise.

updateHardware

public void updateHardware()

Performs a hardware readback without stepping the hardware clock. This is useful for stopping a free-running clock and hardware breakpoints.

cycleHardware

public boolean cycleHardware(int no_steps)

Runs a hardware platform, provided the system is in hardware mode and the root node implements HardwareInterface. (Note that this is in steps, not in cycles.)

Parameters:

no_steps - the number of steps to take.

cycle

public void cycle(int no_clocks)

This method is invoked to advance the simulator by no_clocks. This routine blocks until the simulator has finished the requested number of clock cycles.

Parameters:

no_clocks - the number of clocks to run the simulator.

step

public void step(int no_steps)

This method is invoked to advance the simulator by no_steps. This routine blocks until the simulator has finished the requested number of clock steps.

Parameters:

no_steps - the number of steps to run the simulator

skip

public void skip(int no_steps)

This method is invoked to advance the simulator by no_clocks. This routine blocks until the simulator has finished the requested number of clock cycles. This differentiates itself from step in that the observers are not updated and makes it possible to have correlating commands in hardware and simulation modes.

forceSimulatorCallbackRefresh

public void forceSimulatorCallbackRefresh()

This method can be used to force a call to the sim_update of all SimulatorCallbacks and Observables.

forceSimulatorInitialize

public void forceSimulatorInitialize()

Forces a simulator (re)initialization

reset

public void reset()

This will reset the simulation.

useHWUpdate

public void useHWUpdate(Clockable cell,
                        boolean flag)

This tells the simulator that you will use HWUpdate mode to update the state of the Clockable cell you pass as the argument. An exception is thrown if the cell cannot be found as a Clockable cell in the simulator.

Parameters:

cell - the clockable cell to update

flag - the new state of the cells HWUpdate flag

setHardwareMode

public java.lang.String setHardwareMode(boolean value)

This tells that simulator that you will or will not be using the hardware versus the simulator.

Parameters:

value - the new value of the flag

Returns:

any error message, or null if ok

getHardwareMode

public boolean getHardwareMode()

Whether the simulator is in hardware mode

Returns:

true if the simulator is in hardware mode

hardwareModeSane

public boolean hardwareModeSane()

Whether the simulator is in hardware mode & a valid hardware interface exists

Returns:

true if hardware mode enable & hardware interface valid

disableAllHWUpdate

public void disableAllHWUpdate()

As a matter of convenience, this will disable all HWUpdating of all Clockable cells returning to pure simulation.

getSimulationErrorCount

public int getSimulationErrorCount()

This returns the number of floating or multiple driver errors on the last simulation run.

Returns:

number of non-fatal errors on last run of the simulator

writeSystemState

public void writeSystemState()

This is to cause the ExternalUpdate Manager to dump the current state of the system to a StateObject... dump a checkpoint

writeSystemState

public void writeSystemState(java.lang.String name)

This is to cause the ExternalUpdate Manager to dump the current state of the system to a StateObject... dump a checkpoint

Parameters:

name - the filename to dump to

writeSystemState

public void writeSystemState(java.io.OutputStream os)

This is to cause the ExternalUpdate Manager to dump the current state of the system to a StateObject... dump a checkpoint

Parameters:

os - the outputStream to use

writeSystemStateToHardware

public void writeSystemStateToHardware()

Writes the simulator system state to hardware, if the current loaded model allows it

readSystemState

public void readSystemState(int cycle,
                            int step)

This is to cause the ExternalUpdate Manager to load the state of system from the State object corresponding to the given cycle count

readSystemState

public void readSystemState(java.lang.String name,
                            int cycle,
                            int step)

This is to cause the ExternalUpdate Manager to load the state of system from the State object corresponding to the given cycle count

Parameters:

name - the file to read

readSystemState

public void readSystemState(java.io.InputStream is)

This is to cause the ExternalUpdate Manager to load the state of system from the State object corresponding to the given cycle count

Parameters:

is - the input stream to read

libraryDefaultClock

public void libraryDefaultClock()

This should only be called by libraries. Calling this before creating and registering an external clock and its corresponding clock driver sets a flag so that the method declareExternalClock(Wire) can register the single default library clock allowed per system. Thus, if a user has already created a clock, then this method will fail with an exception.

Throws:

BuildException - If there is already a user-defined clock.

declareExternalClock

public Wire declareExternalClock(Wire clock_wire)

This declares a wire to be an external clock. If the method libraryDefaultClock() was called previously by the library, then this clock will be the single library default clock allowed for the system. A library default clock cannot be created after a user has created a clock; and if the user creates a clock, the library default is discarded. An exception is thrown if the library default had sink cells when it is discarded. All declared clocks must have a single ClockDriver as their source, and must end up with a clock schedule of the same length before simulation.

This method does nothing if the clock has already been declared.

Parameters:

clock_wire - the wire to declare as external - must have a ClockDriver as its source

Returns:

the wire passed in

Throws:

BuildException - If an attempt is made to declare a wire that is not driven by a ClockDriver; if an attempt is made to declare a library default clock after a user clock has been defined; if two clocks have schedules of different lengths.

setUsingImplicitClock

public void setUsingImplicitClock()

Sets the usingImplicitClock flag.

getUsingImplicitClock

public boolean getUsingImplicitClock()

Gets the usingImplicitClock flag. Used to prevent clock mixing

getDefaultClockSchedule

public java.lang.String getDefaultClockSchedule()

In some cases, users may want to see what the current schedule is for the default clock.

Returns:

the schedule for the default clock

setDefaultClockSchedule

public void setDefaultClockSchedule(java.lang.String schedule)

Allows users to modify the current default clock schedule. This will always force a reinitialization of the simulator (to ensure the new schedule is incorporated into the simulator).

Parameters:

schedule - the new default schedule

multiClockModeEnabled

public boolean multiClockModeEnabled()

Whether the circuit is in multi-clock mode. This name is a bit misleading; as multi-clock mode may apply to a circuit with a single clock. It is the mode where each cycle of any clock can have multiple steps

Returns:

true if in multi-clock mode

multiClockModeEnabled

public boolean multiClockModeEnabled(boolean flag)

Deprecated. flag is completely ignored; this will just return multiClockModeEnabled().

Sets whether the circuit is in multi-clock mode. This name is a bit misleading; as a circuit with multiple clocks for netlisting can still be run on the old style simulator with only one step per clock

Parameters:

flag - the new value of the multi-clock mode state

Returns:

the same flag

collectTransitionCountEnabled

public boolean collectTransitionCountEnabled()

This method returns true if transition counts have been enabled, false if they have not been set.

Returns:

true if transition counting was enabled

collectTransitionCountEnabled

public boolean collectTransitionCountEnabled(boolean flag)

This method enables (true) or disables (false) the transition counts in the current HWSystem. It returns the current value. In order to enable transition counts, however, this function MUST be called *before* the target circuit's constructor is called.

Parameters:

flag - the new value of transition counting

Returns:

the same flag

printTransitionCounts

public long printTransitionCounts(java.io.OutputStream os)

This will print out all of the transition counts for every wire in the current testbench and it's corresponding children.

Parameters:

os - where to direct output

Returns:

the number of transition counts

printTransitionCounts

public long printTransitionCounts(java.io.OutputStream os,
                                  Cell c)

This will print out all of the transition counts for every wire in the target Cell and it's children.

Parameters:

os - where to direct output

c - the top cell to gather counts from

Returns:

the number of transition counts

printSimulatorInternals

public void printSimulatorInternals(java.io.OutputStream output_stream)

Prints the status of the simulator

Parameters:

output_stream - where to direct the output

findPropagated

public boolean findPropagated(Wire w)

Finds the propagated wire in the global schedule

Parameters:

w - the wire to find

Returns:

true if it is found

isSimulatorInitialized

public boolean isSimulatorInitialized()

Whether the simulator is initialized

Returns:

ture if initialized

enableProgrammaticTestBench

public void enableProgrammaticTestBench()

Called by Jab (or somebody) if we want to use programmatic testbenches.

haltSimulator

public void haltSimulator()