.\" @(#)overall	1.4 11/28/92
.VR 
.TI "Thor Domain"
.ds DO "Thor
.AU
Seungjun Lee
Anders Wass
.AE
.EQ
delim off
.EN
.H1 "Introduction"
.lp
\fBWarning:\fR  As of Ptolemy release 0.3, this is still an experimental
domain.  It has been included in this release for demonstration 
purposes only.
.pp
\fIThor\fR domain implements the \fIThor\fR simulator which is a functional
simulator written by \fBVLSI/CAD Group\fR at \fBStanford University\fR.  
\fIThor\fR was developed to provide hardware designers with an interactive,
efficient simulation tool.  It supports the simulation of the circuits
with abstraction levels from gate level to behavioral level.
For more details about \fIThor\fR simulator, refer to [1].  
.H1 "Overview of Thor Simulator"
.H2 "Functional Simulator"
.pp
A functional simulator is a tool for verifying a hardware design
by exercising it on a computer.  Usually, the hardware descriptions
are supplied to the simulator with the description of input stimuli,
then the simulator exercises it and gives the result.
.pp
\fIThor\fR is a mixed level simulator with which one can simulate hardware
at the behavior level, register transfer level, and/or gate level.
It provides all the features required for functional simulation,
including generation of input stimuli, monitoring output results,
modeling capability, and interactive simulation control.  
.pp
In the \fIThor\fR system, internal network states are represented by four
values: 0 (logical Low), 1 (logical High), U (Undefined), and Z 
(Floating or High Impedence).
.H2 "Functional Model"
.pp
For simulation the user should supply the circuit description, input
stimuli, and monitor to the \fIThor\fR simulator.  The circuit description
consists of the models of circuit elements and their interconnections.
Input stimuli and monitors are usually modeled as circuit elements
called \fIgenerator\fR elements and \fImonitor\fR elements, respectively.
.pp
A model describes the behavior of a primitive \fIfunctional\fR element.  
Each model can be used in more than one place in the circuit.  In the
\fIThor\fR system, models are written in a language called \fICHDL\fR (C Hardware
Description Language).  \fICHDL\fR is based on the C programming language with
added features for hardware modeling.  Besides the behavior of a functional
element, other description can be included in a functional model, such as
post description and initialization routines.  \fIGenerator\fR and \fImonitor\fR
elements can also be modeled in the same way as other \fIfunctional\fR 
elements.
.pp
Many models are provided in the \fIThor\fR library, which include generic logic
gates(NAND, OR, XOR gates, etc.), various TTL parts, \fIgenerator\fR elements
(Up/Down Binary Counters, Clocks with variable period and phases, etc.),
and \fImonitor\fR elements.
.H1 "Thor Simulation in Ptolemy"
.pp
\fIThor\fR domain implements the \fIThor\fR simulator in \*(PT.  
Most features of the simulator are directly available - modeling capability,
generation of input stimuli and monitoring output results.
The interactive simulation control can be handled by \*(PT
.c interpreter 
or 
.c pigi 
graphical interface.  Furthermore \fIThor\fR 
.c wormhole s 
are provided for 
mixed-domain simulation.
.H2 "Thor Star
.pp
Functional models of the \fIThor\fR simulator are encapsulated in 
.c star s 
of \fIThor\fR 
domain.  Ptolemy stars are generated automatically from the models 
described in \fICHDL\fR by 
.c pepp , 
 a preprocessor for \fIThor\fR domain.  
.H3 "CHDL"
.pp
The \fIThor\fR modeling language, \fICHDL\fR, is based on the C programming language
but has constructs that have been added to make modeling easier.
Any statements in C can be used to model the behavior of an element
in \fICHDL\fR. 
.pp
Each model consists of a model statement and three sections:
interface, initialization, and behavioral description sections.  
Interface defines inputs, outputs, biputs, and internal states. 
Initialization section describes the initializing action to be executed
before running the simulation.  And the behavioral description sections
is the main body of the model containing the algorithms or descriptions
that the modeler is trying to construct.
The details of writing models in \fICHDL\fR can be found in [1].  
.H3 "Pepp
.pp
.c Pepp 
is the \fIThor\fR model to \fIThor\fR star converter, generating C++ code.  
The code it generates is supposed to be compiled with a C++ compiler
(e.g. g++) and linked in the \*(PT environment as a part of the \fIThor\fR
domain.  Suppose there is a \fIThor\fR model with name XXX in file \fIThor\fRXXX.chdl.
Then, running the command
.(c
        pepp \fIThor\fRXXX.chdl
.)c
will produce the C++ code in \fIThor\fRXXX.cc.  With this policy, the makefiles
can contain the default rule
.(c
      .chdl.cc:
	       pepp $<
.)c
See the makefile in ~ptolemy/src/domains/thor/stars for how this can be made
to work.  Unix on-line man pages are provided in ~ptolemy/src/domains/thor/man
for the usage of 
.c pepp 
in detail.

.H2 "Thor Scheduler"
.pp
The scheduler executes the stars in proper order.  The \fIThor\fR scheduler
is a conventional event-driven scheduler.  It keeps a \fItime-wheel\fR which
works as an global event queue.  The \fItime-wheel\fR consists of uniformly
spaced time slots in which future events are scheduled.
That means all the events are supposed to occur at discrete time, and
time stamps associated to the events should always be integer multiples
of the unit time.  
.pp
Stars in \fIThor\fR domain are functional.  Once fired, they finish
their execution in zero-time.  The execution delay can't be
specified within a \fIThor\fR star.  There two ways to generate
future events.  One is that a star can schedule itself at
sometime in the future by calling \fIself_sched()\fR [2] within the code, 
and the other is to put delays at the outputs of a star.  
Output delays can be specified in the 
.c connect 
command from the
.c interpreter
, or by creating a 
.c delay 
object from the 
.c pigi 
graphical
interface.
.H2 "Netlist-style Connection"
.pp
The main usage of \fIThor\fR domain is hardware design verification.
The connections between hardware blocks tend to be more like netlist-style
than point-to-point connection.  And for a netlist-style connection
there may exist more than one inputs driving the net, and also the value
of the net should propagate into multiple outputs.   
.pp
\*(PT provides 
.c node 
object for specifying netlist-type connection.  A net
can be defined as a node which allows multiple inputs and outputs.  There
is a \fIresolution function\fR defined in a node to resolve the net value when
multiple inputs are driving the same node.  See also the section 
"The Ptolemy Interpreter".  
.H1 "Wormhole"
.pp
\fIThor\fR is a timed domain, and \fIThor\fR 
.c wormhole 
was implemented following the
guidelines given in the section "Domains in Ptolemy".   Some caution
has to be made in interconnecting \fIThor\fR domain with other domains.  
.pp
\fIThor\fR domain allows only discrete time so that the time value should
always be integer.  When an incoming particle into \fIThor\fR wormhole carries
a \fItime stamp\fR of real number, the \fItime stamp\fR will be approximated to the
nearest integer value.  For example, a particle arrived at time 1.2 will be
interpreted to be arrived at 1.0, and another particle arrived at 1.7 
will be interpreted to be arrived at 2.0.
.pp
The particles in \fIThor\fR domain are supposed to carry \fIboolean\fR values.  
If an incoming particle to \fIThor\fR domain carries a value other than 0 or 1,
it can't be understood and will set out an error condition.  
When \fIThor\fR domain is defined within another domain which deals with
data types other than \fIboolean\fR, the connection into the \fIThor\fR domain
has to be decomposed into an array of bit-lines before it enters
the wormhole boundary. 
.UH "References"
.ip [1]
VLSI/CAD Group,
"THOR TUTORIAL"
\fIStanford University\fR,
1988,
.ip [2]
VLSI/CAD Group,
"THOR MANUAL"
\fIStanford University\fR,
1988.
.EQ
delim $$
.EN
