Edward A. Lee UC Berkeley This tutorial is aimed at the ... · SDF BDF DDF Thor DE CGC CG56 CG96...

UNIVERSITY OF CALIFORNIA AT BERKELEY

© 9/24/97, p. 1 of 79tutor ia l_97.fm

Ptolemy Ptutorial

ard A. Lee

erkeley

tutorial is aimed atthe software developerplanning to use Ptolemyas a platform.

For Ptolemy version 0.7.

Copyright © 9/24/97,The Regents of the University of CaliforniaAll rights reserved.

p

Edw

UC B

This

© 9/24/97, p. 2 of 79

Ptolemy as a Tool and as a Laboratory

ents with:

putation

c tools

ology

esis

hesis

els are

synthesis.

p


tutor ia l_97.fm

Ptolemy is

• Extensible

• Publicly available

• An open architecture

• Object-oriented

Allows for experim

• Models of com

• Domain-specifi

• Design method

• Software synth

• Hardware synt

• Cosimulation

• Codesign

Rationale for heterogeneity: specialized mod

• More useful to the system-level designer

• More amenable to hardware and software

© 9/24/97, p. 3 of 79

Documentation

Volume 3Kernel Manualocumentation

of C++ classesEssential for

definingTargets andDomains.

p


tutor ia l_97.fm

Volume 1User’s Manual

pigiptcl

domainsvem

pxgraphinstallation

The Almagest

d

Volume 2Programmer’s Manualsoftware organization

writing starsinfrastructure

data typesTcl/Tk

domainscode generation

© 9/24/97, p. 4 of 79

The Kernel: A Flexible Abstract Syntax

p


tutor ia l_97.fm

Hierarchical Graphs —

Levels can usedifferent models of

© 9/24/97, p. 5 of 79

Ptolemy C++ Base Classes Support this Abstract Syntax

PortHole

le

()

()

lize()

lock

p


tutor ia l_97.fm

PortHole PortHole

Block

• initialize()

• run()

• wrapup()

PortHole

• initialize()

• receiveData()

• sendData()

• type()

PortHole

Geodesic

PlasmaPartic

• type

• print

• initia

Particle

Block B

© 9/24/97, p. 6 of 79

Object-Oriented Programming

esigns. Thee software

riented

p


tutor ia l_97.fm

• inheritance

• data abstraction

• polymorphism

The idea is to use a heterogenous softwarenvironment to develop heterogeneous deinteraction between different modules in thenvironment is managed through object-oprinciples.

© 9/24/97, p. 7 of 79

Some Kernel Classes (Booch Notation)

tiPortHole

ss has all thelus more.

e irrelevant and

ith identicalplementations.

p


tutor ia l_97.fm

Block

NamedObj

Star Galaxy

GenericPort

MulPortHole

C++ class:

• Members & Methods

• Public, Protected, Private

Inheritance: A derived claproperties of the parent, p

Data abstraction: Hiding thamplifying the essential.

Polymorphism: Objects winterface have different im

AAbstract base class:Cannot be instantiated.

A

© 9/24/97, p. 8 of 79

Example: NamedObject

p

}

p


tutor ia l_97.fm

class NamedObj {public:

NamedObj ();NamedObj (const char* n,Block* p,const char* d);

const char* name() const;const char* descriptor () const;Block* parent () const;

void setParent (Block* my_parent);void setName (const char* my_name);

virtual const char* className () const;virtual int isA (const char* cname) const;

virtual void initialize () = 0;rivate:

const char* nm;Block* prnt ;const char* myDescriptor ;

© 9/24/97, p. 9 of 79


p

}

uctors

rivate members

members

ation

p


tutor ia l_97.fm








Two possible constr

Methods to access p

Methods to set private

Methods to get class inform

Private members

© 9/24/97, p. 10 of 79


p

}

t be modifiedT

rived class

p


tutor ia l_97.fm








The string will no

Pure virtual method

he return value cannot be modified.

Calling a virtual method gives the version in the de

© 9/24/97, p. 11 of 79

Hierarchical Abstraction

•

XXXStar

Universe

p


tutor ia l_97.fm

Examples of Derived Classes

• class Star :: Block

• class XXXStar :: Star

• class Galaxy :: Block

class Universe :: Galaxy , Runnable

XXXStar Galaxy XXXStar

XXXStar

Galaxy XXXStar

XXXStar

© 9/24/97, p. 12 of 79

Domain Classes Derived from Kernel Classes

YYStar

tarreal workdone here

p


tutor ia l_97.fm

Block

NamedObj

StarGalaxy

A

YXXXStar

XXXWormhole

Wormhole

Runnable

Universe

XXXUserSmultipleinheritance

Assume “XXX” and “YYY”are two domain names.

A

© 9/24/97, p. 13 of 79

Domains in Ptolemy

hor

SDF

us dataflow

dynamic dataflow

idimensional SDF

olean dataflow

circuit simulation

discrete-event

ng processes

process networks

t
p

tutor ia l_97.fm

SDF DDFBDF

T

DE

CGC

CG56

CG96

Silage

VHDLF

CG

PTOLEMYKERNEL

MD

Sproc

PN

VHDLB

synchrono

mult

Bo

communicati

Cod

e ge

nera

tion

dom

ains

CPDMM

design methodology managemen

© 9/24/97, p. 14 of 79

Ptolemy is an Extensible Open Architecture

p

E

•

•

•

•

•

•

•

•


tutor ia l_97.fm

xtensions that are possible:

applications (block diagrams)

a library of galaxies

application builders (using ptcl or pitcl)

a library of custom stars

customized user interfaces (using Tcl/Tk)

simulation managers (Targets)

domains (new models of computation)

foreign simulators and/or synthesis tools

© 9/24/97, p. 15 of 79

Data Types in Ptolemy

Particle

A

Particle

p


tutor ia l_97.fm

ComplexParticle

IntParticle

FloatParticle

FixParticle

Actually a double!Message

MatrixParticle

FloatMatrixParticle

etc.

Base class for user-defined data types

© 9/24/97, p. 16 of 79

Color Hints at Data Types

matrices

p


tutor ia l_97.fm

blue = float (double)

white = complex

magenta = fixed point

orange = integer

thicker stems indicate

© 9/24/97, p. 17 of 79

Anytype

particle. Thehese stars are

:

rticle

le streams

streams

p


tutor ia l_97.fm

Red stems indicate stars that operate on anycode inside refers only to type “Particle,” so tpolymorphic.

Fork:

Commutator

Distributor:

replicate a pa

merge partic

split particle

© 9/24/97, p. 18 of 79

Key Particle methods

andard typesrticles to datahange types.

ASCII“zero”

p

cp


tutor ia l_97.fm

lass Particle {ublic:

virtual operator int ();virtual operator float ();virtual operator double ();... etc...

virtual StringList print ();virtual Particle& initialize ();

// Load the Particle with datavirtual void operator << (int);virtual void operator << (double);... etc...

// Copy a Particlevirtual Particle* clone ();

// compare two particlesvirtual int operator == (const Particle&);

casts to stconvert paand also c

generatereset to

© 9/24/97, p. 19 of 79

Synchronous Dataflow

PSAMPLE

IRED

redictable

nstructedy executed

ronouscessing

p


tutor ia l_97.fm

DOWNSAMPLEDOWNSAMPLE UUPSAMPLE

ENABLED FIRED

ENABLED FENABLED FIRED

1 1

1

1

1 2

2

Properties

• Flow of control is pat compile time

• Schedule can be coonce and repeatedl

• Suitable for synchmultirate signal pro

© 9/24/97, p. 20 of 79

Writing Custom Stars

ne.pl

+ code.

f r, consider

p

T

•

•

•

•

Id


tutor ia l_97.fm

he quick start:

Find a star in the source tree.

Copy it and modify it.cd my_directorycp $PTOLEMY/src/domains/sdf/stars/SDFSin.pl SDFMichmod +w SDFMine.pl

Change the name of the star!

Replace the appropriate fields with your C+

your star is a modification of an existing staeriving from the existing star.

© 9/24/97, p. 21 of 79

Using Custom Stars

environmentith the gnu

p

•

•


tutor ia l_97.fm

Make-star (*)

• If $PTOLEMY != /users/ptolemy, you have to set four (!)variables, or the compiler will not work. This is a flaw wcompilers. See the programmer’s manual.

Make a test application

© 9/24/97, p. 22 of 79

Minimal Star Definition File

.pl”.

+ class.

de

p

T

A

d

}


tutor ia l_97.fm

his should go in a file called “SDFSimpleLog

preprocessor (ptlang) translates it into a C+

efstar {name { SimpleLog }domain {SDF}desc { This star computes the Log of the input }input {

name{input}type{float}

}output {

name{output}type{float}

}ccinclude { <math.h> }go {

output%0 << log (double(input%0));}

C++ co

© 9/24/97, p. 23 of 79

Input and Output for Stars

om the Particle

referenced

ytype)

cle&

p


tutor ia l_97.fm

go {output%0 << log (double(input%0));

}

Returns a reference to a Particle Extracts a double fr

Loads a double into the Particle

Manipulating Particles Directly (for Ango {

Particle& current = input%0;outputA%0 = current;outputB%0 = current;

}

object PortHole has operator % defined to return a Parti

© 9/24/97, p. 24 of 79

More Sophisticated Go Method

is explicitssary.

it.

riters.

handlerror occurred

p


tutor ia l_97.fm

go {double t = double(input%0);if (t <= 0) {

Error::abortRun (*this, “: log of x, x <= 0”);output%0 << -100.0;

}else output%0 << log(t);

}

For most compilers, thcast is not strictly neceStill it is safest to use

One of many infrastructure classes provided to star w

tells the errorwhere the er

© 9/24/97, p. 25 of 79

Accessing Past Samples

mples

rsimed.

p


tutor ia l_97.fm

go {double sum = 0.0;for (int i = 0; i < 10; i++) {

sum += double(input%i);}output%0 << sum;

}

setup {input.setSDFParams(1,9);

}

accessing past sa

need to declare that this will be done:

second argument tells the domain what the largestargument to the % operator will be. This allows buffeto be allocated statically and old Particles to be recla

© 9/24/97, p. 26 of 79

Consuming Multiple Samples

, but:

to

p


tutor ia l_97.fm

go {double sum = 0.0;for (int i = 0; i < 10; i++) {


}

setup {input.setSDFParams( 10,9);

}

the go method is completely unchanged

the first argument tells the domain how many tokensdiscard after the star fires.

© 9/24/97, p. 27 of 79

Using Parameters

wmany)-1);

p

d

}


tutor ia l_97.fm

efstar {name { MyAverage }domain {SDF}desc { This star averages a batch of inputs }input { name{input} type{float} }output { name{output} type{float} }state { name{ howmany} type{int} default{10}}setup {

input.setSDFParams(int( howmany),int( ho}go {

double sum = 0.0;for (int i = 0; i < int( howmany); i++) {


}

© 9/24/97, p. 28 of 79

Type Propagation, MultiPortHoles, and Iterators

tHole object

olymorphic

rs are a basicnism for

ng throughhey have

tor ++ thats the next on the list,turns 0 whent is finished.

p

d

}


tutor ia l_97.fm

Fork starefstar {

name {Fork}domain {SDF}input {

name {input}type { anytype }

}outmulti {

name {output}type { =input }

}go {

MPHIter iterator (output);PortHole* p;while ((p = iterator ++) != 0) {

(*p)%0 = input%0;}

}

output will be a MultiPor

note type propagation

declares the star to be p

iteratomechasteppilists. Toperareturnobjectand rethe lis

© 9/24/97, p. 29 of 79

Methods in a Star

reated

ed

, before the run

free run

stroyed

ods of your own++.

p

S

•

•

•

•

•

•

Yd


tutor ia l_97.fm

tandard methods:

constructor: called when the star object is c

setup: called before the scheduler is initializ

begin: called after the scheduler is initialized

go: called during the run

wrapup: called at the completion of anerror-

destructor: called when the star object is de

ou can also include in a star any other methesign, plus arbitrary code segments in C or C

© 9/24/97, p. 30 of 79

Notes and Extensions

ge in valuelemy treats

ing array states,

ly stop a run.nient time.

ers

p

•

•

•

•


tutor ia l_97.fm

By convention, we callstates that do not chanduring an executionparameters, although Ptothem the same.

There are array states, string states, and stras well as all the standard types.

Calling Error::abortRun does not immediateIt just alerts the scheduler to stop at a conve

Other infrastructure classes include:• I/O stream classes

• String classes

• XGraph

• BarGraph

• List classes

• Hash tables

• Complex class

• Fix class

• Matrix classes

• Random numb

• Histogram

© 9/24/97, p. 31 of 79

Discrete-Event Domain

+ timestamp).

by timestamp.

ecute.

tput tokens.

fired

•

p

D

•

•

•

•


tutor ia l_97.fm

iscrete-Event Domain:

A signal is a sequence ofdiscrete events (data

Discrete events are ordered in a globalqueue

The global queue schedules whichactor to ex

An actor consumes input tokens,produces ou

enabled

•

fired enabled

• •

•

newest new newest

•

© 9/24/97, p. 32 of 79

Execution Model for the Discrete-Event Domain

estamps

the queue andlock

event queue.

actor are

rted according

ports, and

p

R

•

•

S

•

•

•


tutor ia l_97.fm

un-Time Scheduling

Global event queue sorts events by their tim

Scheduler fetches the event at the head of sends it to the input ports of its destination b

pecial Cases

Initialization: insert triggering particles in the

Simultaneous events at all input ports to anprovided when the actor is executed

Equal timestamps in the event queue are soto a topological sort:

1. partial ordering of the actors in the flow graph,2. triggering relationships between the input and output3. ordering of the input ports.

© 9/24/97, p. 33 of 79

Discrete-Event Actors and Channels

delay

cted actors

p

A

•

•

P

•


tutor ia l_97.fm

ctors

Functional actorstimestamp of data on output ports =timestamp of data on triggering input ports

Delay actorstimestamp of data on output ports =timestamp of data on triggering input ports +

roperties of Channels

Delay attributerepresents an infinitesimal delay (sort of)introducesno actual delay in simulated timebreaks topological ordering between conneprevents race conditionssuppresses delay-free loop warnings

© 9/24/97, p. 34 of 79

Delay Star Definition

s/de/stars

r class

tput block

d time units

p

FC

d


tutor ia l_97.fm

ile is “DEDelay.pl” in $PTOLEMY/src/domainontinued on the next page

efstar {name { Delay }domain {DE}desc { Delays its input by a fixed amount }input {

name {input}type {anytype}

}output {

name {output}type {=input}

}defstate {

name {delay}type {float}default {“1.0”}desc { Amount of time delay. }

}

inherits from DESta

Single-input, single-ou

in simulate

© 9/24/97, p. 35 of 79

Delay Star Definition

tar

);

t output time

heduler the star

p


tutor ia l_97.fm

constructor {delayType = TRUE;

}

Member of the DEStar class The star is a delay s

Manipulating Timestampsgo {

completionTime = arrivalTime + double(delayParticle& pp = input.get();output.put(completionTime) = pp;

}

completionTime (member of DEStar class) records lates

arrivalTime (member of the DEStar class) is set by the scto the timestamp of the event(s) the triggered the firing of

© 9/24/97, p. 36 of 79

More Sophisticated Delay Star (a Server)

service time

ource is free

p


tutor ia l_97.fm

go {if ( arrivalTime > completionTime )

completionTime = arrivalTime + double(delay);else

completionTime += double(delay) ;Particle& pp = input.get();output.put(completionTime) = pp;

}

Input event waits until a simulatedresource becomes free to attend to it

delay parameter indicates the

Res

Server Star

© 9/24/97, p. 37 of 79

Functional Star

p

d

d


tutor ia l_97.fm

efstar {name { Switch }domain {DE}desc { Switches input events to one of two outputs,

epending on the last received control input. }input {

name { input }type { anytype }

}input {

name { control }type { int }

}output {

name { true }type { =input }

}output {

name { false }type { =input }

}

© 9/24/97, p. 38 of 79

Functional Stars

l input first

nput

ol input doesgger outputs

p


tutor ia l_97.fm

constructor {control.triggers();control.before(input);

}

For equal timestamps, read contro

Checking for New Data on Data Igo {

if ( input.dataNew ) {completionTime = arrivalTime;Particle& pp = input.get();int c = int(control%0);if ( c )

true.put(completionTime) = pp;else

false.put(completionTime) = pp;}

}

Contrnot tri

© 9/24/97, p. 39 of 79

Extending the GUI

e” designed by

Wesley, Read-n

d targets.

p

D

•

•

E

Ji

T


tutor ia l_97.fm

efinitions:

Tcl is an interpreted “tool command languagJohn Ousterhout at Berkeley.

Tk is an associated X window toolkit.

ssential reference:

. Ousterhout,Tcl and the Tk Toolkit, Addison g, Mass., 1994.

cl and Tk scripts may be invoked by stars an

© 9/24/97, p. 40 of 79

TclScript stars

that is sourcedrmined by this

p

Tafi


tutor ia l_97.fm

he single parameter is the name of a Tcl filet setup time. The behavior of the star is detele.

© 9/24/97, p. 41 of 79

Example

o

1.0” 0.0”

e conflict).

p

#t

#p

#bb

N•

•

•


tutor ia l_97.fm

Create an empty top-level windowplevel .top

Put a button in the windowack [button .top.b -text “PUSH ME”]

Bind an action to pushing the buttonind .top.b <ButtonPress-1> “ setOutputs_$starIDind .top.b <ButtonRelease-1> “ setOutputs_$starID

otes: you cannot use more than one instance of this script (nam

this script fails to remove the window it creates.

the system runs free, unsynchronized to the button.

© 9/24/97, p. 42 of 79

An Awkward way to be Quasi-Object-Oriented

t is sourced:

nel window)

p

G

•

•

S

•

•

P

•

•

•


tutor ia l_97.fm

lobal variables that are set before your scrip

starID (a unique identifier for your star)

ptkControlPanel (the name of the control pa

tar procedures you can call from your script

setOutputs_$starID

grabInputs_$starID

rocedures you can define in your script

goTcl_$starID

wrapupTcl_$starID

destructorTcl_$starID

© 9/24/97, p. 43 of 79

Putting the Button in the Control Panel

.0” 0.0”

p

#s

#p

#bb

N•


tutor ia l_97.fm

Use a variable to store the long window nameet s $ptkControlPanel.middle.button_$starID

Put a button in the windowack [button $s -text “PUSH ME”]

Bind an action to pushing the buttonind $s <ButtonPress-1> “ setOutputs_$starID 1ind $s <ButtonRelease-1> “ setOutputs_$starID

otes: no more name conflict (try using more than one instance).

© 9/24/97, p. 44 of 79

Allowing Repeated Runs

f

1.0” 0.0”

p

s

#i

}u

•


tutor ia l_97.fm

et s $ptkControlPanel.middle.button_$starID

Add the buttons only if they don’t already exist {! [winfo exists $s]} {

pack [button $s -text “PUSH ME”]bind $s <ButtonPress-1> “ setOutputs_$starIDbind $s <ButtonRelease-1> “ setOutputs_$starID

nset s

buttons are only created if they don’t already exist.

© 9/24/97, p. 45 of 79

Parameters

e of the starIDs

lly connected to the

ually connected to

the star.

n or convenience

p

Ai

Ia


tutor ia l_97.fm

global array with the name given by the valu created to store the following information:• [set ${starID}(numInputs)] : The number of inputs actua

star.

• [set ${starID}(numOutputs)]: The number of outputs actthe star.

• [set ${starID}(tcl_file)]: The name of the Tcl file used by

addition, a set of procedures are provided fnd for uniformity of appearance:

• ptkExpanEnvVar

• ptkImportantMessage

• ptkMakeButton

• ptkMakeEntry

• ptkMakeMeter

• ptkMakeScale

© 9/24/97, p. 46 of 79

Another Example

ic, in general.ver however

p

##p

}

NTm


tutor ia l_97.fm

This procedure is invoked every time the star fires, thus providing a synchronized runroc goTcl_$starID {starID} {

# Suppose we know that the star has two inputs.# We can read them and add them together as follows.set inputVals [grabInputs_$starID]

# Split the input list into individual elementsset xin [lindex $inputVals 0]set yin [lindex $inputVals 1]

# Add the numbers and send to the outputsetOutputs_$starID [expr $xin+$yin]

ote that Tcl is not a good way to do arithmetoo slow. Also, the above star should iterate oany inputs are actually connected.

© 9/24/97, p. 47 of 79

Creating Custom Stars Derived from TclScript

ript:

p

d

A

H

Y


tutor ia l_97.fm

efstar {name {MyFancyWidgetStar}derivedFrom {TclScript}

dd your own parameters:state {

name{howManyWidgets}type{int}default{10}

}

ide the tcl_file parameter:setup {

tcl_file = “~me/my_directory/myfile.tcl”;tcl_file.clearAttributes(A_SETTABLE);

}

our parameters are accessible in your Tcl scset n [set ${starID}(howManyWidgets)]

© 9/24/97, p. 48 of 79

Managing Simulation or Code Generation

Target

Target

heduler

p


tutor ia l_97.fm

Target:: Block

• initialize()• setup()• run()• wrapup()• galaxy• scheduler• children

Scheduler

Target

Scheduler Sc

© 9/24/97, p. 49 of 79

Defining Targets

se

xecution

States

, or compilation

ltiprocessors)

p

•

•

•

•

•

•


tutor ia l_97.fm

A Target supervises the execution of Univer

A Universe has a Target that manages its e

A Target normally contains a Scheduler

The Target is a Block, and hence can have

A Target can do simulation, code generation

A Target can have child Targets (e.g. for mu

© 9/24/97, p. 50 of 79

Target Class Structure

t DETarget

Target

p


tutor ia l_97.fm

Block

Scheduler Target

HOFTargeCGTarget SDFTarget

MultiTarget CGBDFAsmTarget HLLTarget

A Target contains a Scheduler

Target methodssetupbeginsetStopTimesetCurrentTimerunwrapup

© 9/24/97, p. 51 of 79

Scheduler Class Hierarchy

Sched

DEScheduler

get parameterne of thesedulers

p


tutor ia l_97.fm

Scheduler Target

DynDFSched DEBaseSDFScheduler

CQScheduler

A DETarselects otwo sche

DDFScheduler

ParScheduler

SDFMultiScheduler

Galaxy

A Scheduler contains a GalaxyA

Scheduler methodssetupsetStopTimesetCurrentTimerun

© 9/24/97, p. 52 of 79

The World’s Simplest Target — Class Definition

/

;

p

/#

cp

}


tutor ia l_97.fm

The base class template file must be includedinclude “Target.h”

lass MyTarget : public Target {ublic:void setup();int run();void wrapup ();

// The constructor simply passes the arguments on// to the base class constructor.MyTarget(const char* nam,const char* stype

const char* desc) : Target(nam,stype,desc) {}

// Every Target has a method to make another instance// of the same type of Target.Block* makeNew() const;

© 9/24/97, p. 53 of 79

The World’s Simplest Target — Method Definitions

/

n

/

p

/

v }

i }

v }

/B }


tutor ia l_97.fm

These methods just use the Error class to issue messages

oid MyTarget::setup() {Error::message(“Requesting setup\n”);

t MyTarget::run() {Error::message(“Requesting run\n”);return 1;

oid MyTarget::wrapup() {Error::message(“Requesting wrapup\n”);

The method to return a new instancelock* MyTarget::makeNew() const {return new MyTarget(name(), starType(), descriptor());

© 9/24/97, p. 54 of 79

The World’s Simplest Target — Instantiation

/

//////

/

p

/#

//////s

/

s


tutor ia l_97.fm

A class that keeps track of all available Targets:include “KnownTarget.h”

Create an instance of the Target (there has to be at least one instance from which clones are made). The arguments are:

Target nametypes of stars supporteda short description of the Target

tatic MyTarget myTargetPrototype(“MyTarget”, “SDFStar”, “The world’s simplest Target”);

Register the Target in the list of known Targets.

tatic KnownTarget entry(myTargetPrototype,”MyTarget”);

© 9/24/97, p. 55 of 79

The World’s Simplest Target — Compilation

p

#

M


tutor ia l_97.fm

The following extremely simple makefile will work

yTarget.o:MyTarget.ccg++ -fPIC -I$(PTOLEMY)/src/kernel -c MyTarget.cc

© 9/24/97, p. 56 of 79

Slightly More Interesting Target

/

/

p

/##

/v

}


tutor ia l_97.fm

Add the following include filesinclude “InfString.h”include “GalIter.h”

Modify the setup methodoid MyTarget::setup() {

// An infinite string classInfString list;

// Construct a list of the blocks at the top level// using an iterator.GalTopBlockIter blockIterator(*galaxy());Block *b;while ((b = blockIterator++) != 0) { list << b->name() << “\n”;}

// Display the namesError::message(list);

© 9/24/97, p. 57 of 79

Interaction Across Models of Computation

XUniverse

Wormhole

XXDomain

YDomain

s

cles

p


tutor ia l_97.fm

XX

XXX

X

YY

YYYtoUniversalXXXfromUniversal

YYYfromUniversalXXXtoUniversal

Eve

ntH

oriz

on

Scheduler

Scheduler

Particle

Parti

© 9/24/97, p. 58 of 79

Wormholes

tar (zero delay)

produce output

p

S

•

•


tutor ia l_97.fm

DF Domain Inside a DE Domain

SDF domain is treated as a functional DE s

Multirate SDF subsystems may not always for a single input

DE

SDF

zero time delay

© 9/24/97, p. 59 of 79

Wormholes

s an SDF star: it of tokens

m to produce an

riate number ofut events.

p

D

•

•

To


tutor ia l_97.fm

E Subsystem Inside an SDF Subsystem

SDF subsystem treats the DE subsystem amust consume and produce a fixed number

SDF subsystem will expect the DE subsysteoutput when given input

he DE sampler star ensures that the approputput events are produced in response to inp

��

��

SamplerServer��

��

© 9/24/97, p. 60 of 79

When Should you Define a New Domain

patible with X.

ting domains.

p

A

•

•

•

T

•

•

•

•


tutor ia l_97.fm

ll of the following should be true:

You need a new model of computation, X.

You understand all existing domains.

The stars in each existing domain are incom

he following are probably not sufficient:

It is too much trouble to understand the exis

You think the existing domains are wrong.

You really want to write alot of C++ code.

Writing domains is cool.

© 9/24/97, p. 61 of 79

Domain-Specific Classes

X

tar

lock

Star

XUserStar

p


tutor ia l_97.fm

Target

XWormhole

Wormhole

Kernel

Domain

XScheduler

Scheduler

Galaxy

S

B

X

Runnable

XTarget

© 9/24/97, p. 62 of 79

More Domain-Specific Classes

FromUniv.

mEH

p


tutor ia l_97.fm

XWormhole

XToUniv. Y

OutYPortHoleInXPortHole

EventHorizon

PortHole FroToEH

Kernel

DomainXPortHole YPortHole

© 9/24/97, p. 63 of 79

Creating a domain ... an Overview

you need.

n actors?

re required?

e next slide).

lasses derived

antics

n domains, too.

p

•

•

•

•


tutor ia l_97.fm

Scope out the computational specialization • what rules regulate the firing of actors?

• what rules dictate how/when data is transferred betwee

• code generation domains - what supervisory functions a

• are new data types needed?

Create outlines for new domain classes (se

Map the functionality onto domain-specific cfrom kernel classes.• need to understand and accommodate mismatches

• create any new classes required to support the new sem

Consider semantic mapping issues betwee• how will/should the domain interact with others?

• what semantics are built in vs. left for designer?

© 9/24/97, p. 64 of 79

The Process... an Overview (cont.)

sting.

cific Stars.

p

•

•

•


tutor ia l_97.fm

Create few basic Stars for the domain for te• debug basic semantics.

Build up and debug a library of domain-spe

Debug heterogeneous interactions.

© 9/24/97, p. 65 of 79

Mechanics: Mkdom and Domain Class Templates

get)

sal)
p
•

•

•


tutor ia l_97.fm

To create domain-specific class templates:% cd ~ptolemy/src/domains/; mkdir new;% cd new; mkdom new

Creates:make.template (!!)

.../new/kernelNEWDomain.cc (NEWDomain and default NEWTarNEWGeodesic.hNEWPortHole.h NEWPortHole.ccNEWScheduler.h NEWScheduler.ccNEWStar.h NEWStar.ccNEWWormhole.h NEWWormhole.cc

(NEWWormhole and NEWTo/NEWFromUniver

.../new/starsNEWNop.pl

Compiles (!!), but does little more.

© 9/24/97, p. 66 of 79

Typical Domain Extensions

ializations aretional domain.

locks based on

hanism for the

nding data ornal stars inherit

t PortHole/ implements

p

Sp

•

•

•

•


tutor ia l_97.fm

ince Ptolemy is OO, many extensions, specossible; some are required to have an opera

NEWScheduler - Sequences execution of bdomain semantics.

NEWPortHole - Supports data transfer mecdomain.

NEWStar - Enforces sequence of getting/seevents relative to execution. Specific functiothis behavior.

NEWTo/NEWFromUniversal - Builds correcEventHorizon combos for NEWWormholes;Wormhole data transfer.

© 9/24/97, p. 67 of 79

Typical Domain Extensions (cont.)

main

k at domain

rget system;

p

•

•

•


tutor ia l_97.fm

NEWDomain - Supports creation of inter-domechanisms like NEWToUniversal andNEWFromUniversal, and NEWWormhole.

NEWWormhole - Dual-natured building blocinterfaces.

NEWTarget - Supervises execution within taused by code generation domains mostly.

© 9/24/97, p. 68 of 79

Overall Software Organization

l)

RNEL

uration hasd-line

ce runs asting Unix

p


tutor ia l_97.fm

PTCL (with Tc

KE

PIGIRPC (with Tk)

OCT RPCDOMAINS

GRAPHICAL USERINTERFACE

PTCL (with Tcl)

KERNEL

DOMAINS

VEM

A minimal configonly a commaninterface.

The user interfatwo communicaprocesses.

© 9/24/97, p. 69 of 79

Standard forms of the Ptolemy Executables

s plus GUI.

p

p

•

p

•

p

•

p

•

p

•


tutor ia l_97.fm

igi

All domains and targets plus the GUI.

trim

SDF, BDF, DDF, DE, CGC and HOF domain

tiny

SDF and DE domains plus GUI.

tcl

All domains, no GUI.

itcl

Experimental OO replacement for ptcl.

© 9/24/97, p. 70 of 79

File Organization

$

quired!)

les

tables

ript)

utables

s

time libraries

ttools

ation)

PTOLEMY to

tolemy.
p

tutor ia l_97.fm

PTOLEMY

src

demo

mk

bin.$ARCH

root of the source tree (re

top-level demo palette

shared portions of makefi

platform-dependent execu

documentation (in PostScdoc

bin platform-independent exec

lib.$ARCH platform-dependent librarie

lib platform-independent run-

octtools a subset of the Berkeley oc

obj.$ARCH object files (upon recompil

tcltk Tcl and Tk

To run ptolemy, set the environment variable the root directory of the installation and put$PTOLEMY/bin in your path.

The preferred installation location is /users/p

© 9/24/97, p. 71 of 79

The Source Tree

$

programs

ustom pigi

the domains

onfigurations

tools

y tool

i

ogram

star writing

domain

p


tutor ia l_97.fm

PTOLEMY/srcptcl

filters

pigiExample

domains

source for ptcl

outside filter design

example to make a c

the code for each of

the Ptolemy kernelkernel

compat header files for odd c

octtools our subset of the oct

libgantt the Gantt chart displa

pigilib source for most of pig

pigiRpc source for pigiRpc pr

ptklib shared Tcl/Tk code

utils utilities

ptlang the preprocessor for

thread code used by the CP

tcltk source for Tcl and Tk

xgraph the pxgraph program

© 9/24/97, p. 72 of 79

The Domains Directory

eneration

solete)

in

te)

HDL

HDL

solete)

ains

es (obsolete)

(obsolete)

p


tutor ia l_97.fm

$PTOLEMY/

cg56

de

cg

Motorola DSP56000

discrete-event

base classes for code g

Motorola DSP96000 (obcg96

bdf Boolean dataflow doma

ddf dynamic dataflow

cgc code generation in C

sdf synchronous dataflow

mq message queue (obsole

sproc Sproc DSP (obsolete)

vhdlf functional modeling in V

vhdl behavioral modeling in V

thor hardware simulation (ob

xxx demonstration new dom

src/domains

cp communicating process

silage Silage code generation

© 9/24/97, p. 73 of 79

Within Each Domain Directory

domain

the domain

pigi

al targets

rce for learningin.

p


tutor ia l_97.fm

demo applications in the

stars stars in the domain

kernel core code defining

icons the icons used by

targets (optional) addition

$PTOLEMY/src/domains/xxx

The stars in a domain are an excellent resouabout how to write custom stars for the doma

READ THE SOURCE

© 9/24/97, p. 74 of 79

Development Environment

n

n

bject trees that code. These

age multiple

p

T

•

•

•

•

•

•

•

•

Maaa


tutor ia l_97.fm

ools used:

g++/gcc/gmake for compilation

Cfront for portability validation

Purify for memory management validatio

SCCS for version control

Emacs + gdb for interactive debugging

FrameMaker and HTML for documentatio

Quantify for performance measurements

NFS for shared filesystem

ost researchers create parallel source and ollow for unobtrusive experimentation with there connected to the SCCS database to manccess and maintain consistency.

© 9/24/97, p. 75 of 79

Debugging

re developmentnvest some effort

n b, emacs). Ofh ut all are freely

p

•

•

•

•

Neita


tutor ia l_97.fm

Dealing with core dumps

Interpreting stack traces

Running a symbolic debugger

Creating custom executables

ote that if you are using Ptolemy as a softwanvironment (a reasonable use), you need to i learning to use reasonable tools (make, gdese, only make is distributed with Ptolemy, b

vailable on the net.

© 9/24/97, p. 76 of 79

Core Dumps

Ptolemy isou develop code

o ny of several

y commands.

p

R

•

•

Ve(mRRCpE

Ys

T


tutor ia l_97.fm

ecall that Ptolemy runs as two processes:

vem

pigiRpc

em rarely crashes in normal usage, but sincextensible, pigiRpc is fairly likely to crash as yr discover bugs in our code). You may get aessages, among them:

PC Error: server: application exited without callingPCExitlosing Application /home/ohm1/users/messer/ptolemy/lib/igiRpcShell on host foucault.berkeley.edulapsed time is 1538 seconds

ou may get the messages:egmentation fault (core dumped)

he vem interface can no longer issue Ptolem

© 9/24/97, p. 77 of 79

Stack Traces

g

p

%

CP#(###############


tutor ia l_97.fm

gdb pigiRpc...

ore was generated by ‘pigiRpc’.rogram terminated with signal 11, Segmentation fault.0 0x2eebb4 in end ()db) where

0 0x2eebb4 in end ()1 0x1c774c in SimControl::doPreActions ()2 0x1c8538 in Star::run ()3 0x16ee74 in DataFlowStar::run ()4 0x16d888 in SDFScheduler::runOnce ()5 0x16d7c4 in SDFScheduler::run ()6 0x1cb4c0 in Target::run ()7 0x1cd4e4 in Runnable::run ()8 0x1bd810 in InterpUniverse::run ()9 0x197774 in KcRun ()10 0x18edac in RpcRun ()11 0x18eeb8 in RpcReRun ()12 0x177634 in RPCApplicationProcessEvents ()13 0x17675c in RPCMain ()14 0x2300 in main ()

© 9/24/97, p. 78 of 79

More Extensive Debugging

on Solaris):

s the code you

debug

he above, or in

rful combination).

p

M

Ma

R

Oy

T


tutor ia l_97.fm

ake a debug version of the executable (e.g.cd $PTOLEMY/obj.sol2/pigiRpcmake ptinyRpc.debug

ake the smallest debug version that containre testing (ptinyRpc, ptrimRpc, or pigiRpc).

unning the new executable:setenv PIGIRPC $PTOLEMY/obj.sol2/pigiRpc/ptinyRpc.pigi -debug

ptional, but strongly recommended (before tour .cshrc file):

setenv PT_DEBUG ptgdb

his specifies to use emacs and gdb (a powe

© 9/24/97, p. 79 of 79

Creating your own Executable

ation to fully

pc thatn

iExample.ur star with the:

ttes.c” tottes you wishcommented.

p

Du

Ci

ACe

YcdR


tutor ia l_97.fm

ynamic linking does not leave enough informse symbolic debugging.

reate your own pigiRpc, ptrimRpc, or ptinyRcludes your stars.

n example is provided in $PTOLEMY/src/pigopy the contents of this directory, replace yoxample there (SDFMyStar.pl) and recompile

make ptinyRpc.debug

ou may optionally edit the file there “defpalehange the default domain and the list of paleisplayed. The make.template is extensively EAD IT.

Edward A. Lee UC Berkeley This tutorial is aimed at the ... · SDF BDF DDF Thor DE CGC CG56 CG96...

Documents

Transcript of Edward A. Lee UC Berkeley This tutorial is aimed at the ... · SDF BDF DDF Thor DE CGC CG56 CG96...