Home

Vol. 2 - Ptolemy 0.7 Programmer`s Manual

image

Contents

1. current value Oo Il I 2 w2 AE 3 4 4 4 5 5 PTOLI EMY This illustrates that both the contents and the size of a FloatArrayState are changed by a setstate command Also notice that file values may be combined with string values when lt filename occurs in an initial value it is processed exactly as if the whole file were substituted at that Ptolemy Last updated 8 26 97 2 26 Writing Stars for Simulation point 2 5 Modifying PortHoles and States in Derived Classes When one star is derived from another it inherits all the states of the base class star Sometimes we want to modify some aspect of the behavior of a base class state in the derived class This is done by placing calls to member functions of the state in the constructor of the derived star Useful functions include setInitValue to change the default value and setAttibututes and clearAttributes to modify attributes When creating new stars derived from stars already in the system you will often also wish to customize them by adding new ports or states In addition you may wish to remove ports or states Although strictly speaking you cannot do this you can achieve the desired effect by simply hiding them from the user The following code will hide a particular state named statename from the user constructor statename clearAttributes A_SETTABLE This means that when the user invokes edit para
2. ccccesessssesseseeeeseeee 9 1 14 6 before method ee ee 12 5 12 7 begin method Last updated 10 17 97 DERepeatStar clas uses se ee ee ee ee ee ee 12 9 begin ptlang directive ees ee 2 6 2 13 Bhattacharyya S S esse see ee ee ee ee 13 21 BRAVES Se REDE D AE RR OE EED De 14 1 binary POIDE ees ees ee see ee n ee ee ee ee ee 4 4 Buck J T 2 1 3 1 4 1 7 1 9 1 13 1 14 1 15 1 BUCK JE sed ke ee ei ko Re 14 1 bufPos method ee ee ee se ee ee 13 12 bufSize method 0 ee ee ee ee ee 13 12 C CHE Primer ee ee ee ee ee ee 2 17 callTcl starID see ee ee ee 5 4 5 5 canGetFired method 12 9 12 9 12 10 ccinclude ptlang directive ccceeeeeees 2 6 2 15 CORE EE RR ota as es ER 3 3 Cfront C compiler esse ee ee ee ee ee 1 2 OG domi oss ER RA hen Meek etm Es 13 COCPOM eso ESE SG Ee ED 13 9 CGCPortHole class ie ee ee ee ee 14 6 CGCStar Class onenn rn ee ee ee se ee ee 14 1 CGCTarget Class use sees se see ee RR Re Re Ge ee 14 2 CGDDF Scheduler i ie ee ee ee ee 13 22 CGMultiTarget class ees ee ee see 13 18 13 19 CGPortHole class i ee ee ee ee ee 14 3 CGSharedBus clasS ee ee ee ee ee 13 19 CGS tare lass SEDEER ER ER EED RE REED 13 3 COGTATSEE see oes Re see eb es Ee aes 14 2 Chans WETE EDS OE RS ED tee 17 1 Chen M J ee ee ee ee ee A 1 17 1 ER EE EO RI 3 3 circAccessThisTime method eie 13 12 clearAttributes method ee ee ee 2 26 Ah EE EO EO IE 3 3 clone method Mes
3. 2 4 2 Reading inputs and writing outputs The precise mechanism for references to input and output portholes depends some what on the domain This is because stars in the domain XXX use objects of class InXXXPort and Out XXXPort derived from PortHole for input and output respectively The examples we use here are for the SDF domain See the appropriate domain chapter for variations that apply to other domains PortHoles and Particles In the SDF domain normal inputs and outputs become members of type InSDFPort and Out SDFPort after the preprocessor is finished These are derived from base class Port Hole For example given the following directive in the defstar of an SDF star input name in type float a member named in of type InSDFPort will become part of the star We are not usually interested in directly accessing these porthole classes but rather wish to read or write data through the portholes All data passing through a porthole is derived from base class Particle Each particle contains data of the type specified in the t ype sub directive of the input or output directive Ptolemy Last updated 8 26 97 2 18 Writing Stars for Simulation The operator operating on a porthole returns a reference to a particle Consider the following example go Particle amp currentSample in 0 Particle amp pastSample in 1 The right hand argument to the operator specifies the delay of the
4. cccccccesesesesseseseteneeeees 2 19 MultiOutSDFPort Class e ee ee ee ee ee ee ee 2 19 multiple portholes iese ee see ee ee Re Re Ge ee 2 19 multiple processor scheduler ees ee ee ees 13 21 MultiPortHole clas eee ee ee ee ee ee ee ee ee 2 19 multiprocessor target ee ee ee ee ee ee ee 13 18 MultiTarget Cla ee ee ee ee ee ee ee ee ee ee 13 18 Murthy P Kars ee RENE EE EG 13 1 13 21 MVlmage class u esse ee ee ee ee ee ee ee ee ee ee 4 4 myData method Envelope Cla ese ee ee ee ee ee ee ee 4 17 N name ptlang directive ese ee ee 2 5 2 6 NegativeExpntl ClaSS ese see ee ee ee ee ee ee 3 17 non determiniSM eeue ees ee ee ee ee ee ee ee ee 12 12 non deterministic OOP sees ee ee ee ee 12 8 num ptlang direCtiVe ees see ee ee ee ee ee 8 2 numberPorts method ees ee ee ee ee 2 21 numSimulEvents method iese ee see 12 5 numTokens ptlang directive esse es see ee ee 7 2 numtokens ptlang directive ese 2 11 2 12 O Obj SPTARCH directori s sees see ee ee ee 1 4 Obj dit alias sects faith Mets N EES Mail eke 1 2 OCttOOlSs RE Seine eis id Mate 1 5 ofstream claS ii ee Ge ee ee 3 2 3 3 operator referencing an entry iese es 4 23 4 38 OutDEPort Class ee ee ee ee ee ee ee ee ee ee 12 5 outmulti ptlang directive 2 6 2 11 2 11 2 19 oi LR EE 3 2 3 3 U C Berkeley output ptlang directive 2 6 2 11 2 11 2 19 OutSDFPort class
5. int input2 get else Error abortRun this One input present the other absent Non strict stars inherit from the SRNonStrictStar class Here is abbreviated source for a non strict two input multiplexer defstar name Mux domain SR derivedFrom SRNonStrictStar input name trueInput type int input name falseInput type int input name select type int output name output type int setup noInternalState reactive go if output known amp amp select known if select present if int select get Select is true copy the true input if it s known if trueInput known if trueInput present output emit lt lt int truelnput get else Ptolemy Last updated 10 10 97 11 4 SR domain true input is absent make the output absent output makeAbsent else Select is false copy the false input if it s known if falseInput known if falseInput present output emit lt lt int trueInput get else false input is absent make the output absent output makeAbsent else Select is absent make the output absent output makeAbsent U C Berkeley Department of EECS Chapter 12 DE Domain Authors Soonhoi Ha Edward A Lee Thomas M Parks Oth
6. void displaySliderValue char window char name char value Ptolemy Last updated 8 26 97 14 8 CGC Domain This function displays a value associated with a scale s slider The scale is identified by its name and the window it is in This function must be called by the user of the slider Only the first 6 characters of the value will be used 14 8 Tycho Target The CGC TychoTarget is an experimental target that provides a way to create CGC control panels that use the functionality in Tycho A universe that uses TychoTarget must pro vide a script that creates the control panel that the user sees The TychoTarget is documented in SPTOLEMY demo whats_new whats_new0 7 tychotarget html U C Berkeley Department of EECS The Almagest 15 1 Chapter 15 CG56 Domain Authors Joseph T Buck Jos Luis Pino Other Contributors S Sriram Kennard White 15 1 Introduction The CG56 domain generates assembly code for the Motorola 56001 processor Chap ter 13 describes the features common to all code generation domains The basic principles of writing code generation stars are explained in section 13 2 You will find explanations for codeblocks macros and attributes there This chapter explains features specific to the CG56 domain Refer to the CG56 chapter in the user manual for an introduction to these domains 15 2 Data Types The supported CG56 data types are int intarray fix fixarray In addition the comp
7. 2 3 3 Items that appear in a defstar The following items can appear in a defstar directive The items are given in the order in which they typically appear in a star definition although they can appear in any order An alphabetical listing and summary of directives is given in table 2 1 name This is a required item and has the syntax name identifier It together with the domain provides the name of the class to be defined and the names of the output files Case is important in the identifier domain This is a required item it specifies the domain such as SDF The syntax is domain identifier where identifier specifies the domain again case is important Ptolemy Last updated 8 26 97 2 6 Writing Stars for Simulation keyword summary reguired page acknowl the names of other contributors to the star no 2 8 edge author the name s of the author s no 2 8 begin C code to execute at start time after the scheduler setup no 2 13 method is called ccinclude specify other files to include in the cc file no 2 15 code C code to include in the cc file outside the class definition no 2 15 codeblock define a code segment for a code generation star no 13 2 conscalls define constructor calls for members of the star class no 2 13 construc C code to include in the
8. Discard the current precision format and set the Fix number to zero There are a few functions for backward compatibility void set_ovflow const char Set the overflow using a name void Set_MASK int value Set the rounding type Same functionality as set_rounding Comparison function int compare const Fix amp a const Fix amp b Compare two Fix numbers Return 1 if a lt b 0 ifa b 1 ifa gt b The following functions are for use with the error condition fields int ovf_occurred Return TRUE if an overflow has occurred as the result of some opera tion like addition or assignment int invalid Return TRUE if the current value of the Fix number is invalid due to it having an improper precision format or if some operation caused a Ptolemy Last updated 10 10 97 int Data Types divide by zero dbz Return TRUE if a divide by zero error occurred void clear_errors Operators Fix amp Fix amp The function Fix Fix Fix Fix Fix Fix Fix Fix Fix Fix Fix Fix int int int int int Reset all error bit fields to zero operator const Fix amp arg Assignment operator If this does not have its precision format set i e it is uninitialized the source Fix is copied Otherwise the source Fix value is converted to the existing precision Either truncation or rounding takes place based on the value of the rounding bit of the cur rent obj
9. Outputs the last token of N input tokens where N is the value of the control input input name input type anytype num 0 input name control type int output name output type anytype private int readyToGo constructor input inheritTypeFrom output setup waitFor control readyToGo FALSE go if readyToGo control receiveData waitFor input int control 0 readyToGo TRUE else int num int control 0 for int i num i gt 0 i input receiveData 8 2 DDF Domain output s0 input 0 output sendData waitFor control readyToGo FALSE The LastOfN star discards the first N particles from the input porthole and routes the last one to the output porthole The value N is read from the control input Since the control data varies the number of particles to read from the input porthole is variable as expected for a DDF star We can specify that the input porthole is dynamic by setting the num field of the input declaration to be 0 using the preprocessor format num 0 The firing rule of the star is controlled by the waitFor method of the DDFStar class actu ally it is defined in the base class DynDFStar The waitFor method takes a porthole as an argument and an optional integer as a second argument It indicates that the star should fire when amount of data specified by the integer default is 1 is available on the spec
10. eie ee ee ee ee 2 26 pragma EE N ed ee een ene 2 21 14 4 precision parameter e ee ee ee ee ee ee ee ee 4 4 precision SIE ee ee ee ee RR Ge ee Ee Ge ee RR 2 10 precision type SALES EE SE Baie odes ed aS 2 9 PIEDIOCESSOF ee ee ee ee ee ee ee ee Re ee ee ee ee ee Re 2 1 print method ee ee ee ee ee ee ee ee ee ee ee ee ee 2 21 Message class ee ee ee ee ee 4 16 4 31 Printer SDF block ese ee se ee ee ee 2 28 private ptlang directive ees se ee ee 2 6 2 14 processMacro method ee ee ee ee 13 12 profile command ee ese ee ee ee ee ee ee ee 2 7 progNotFound function sesse se ee ee ee ee 3 8 protected ptlang directive esse se eene 2 6 2 14 PU ALAS eis esc ER oe ee ee EE EE Ee 1 12 PT DEBUG environment variable sesse esse 1 26 Department of EECS The Almagest pt ifstream class uu ee ee ee ee ee ee ee ee ee 3 2 3 3 pt ofstream class cccsesesesescesseseseseeeeeseeeee 3 2 3 3 PTARCH environment variable 0 cccceeee 1 2 PIDiN ME ee ee ek ek GR Gee RR RR RR ee Ge Ge ee ees 1 6 id etal ete 1 1 1 5 2 24 3 ptkControlPanel ees see see ee ee Re e 5 2 5 6 EER ER RE sacs 1 12 ei uPe EE OO ES EE ayy 2 3 PTOLEMY environment variable ees ees ee 1 2 PtOleMy USE ee se ee ee ee ee ee ee Re ee ee ee ee ee 1 2 public ptlang directive ese 2 6 2 14 pure method ptlang directive see ee ee ee ee 2 11 Pure Sofware INC iese ee ee ee ee ee ee ee ee 1 19 pure virtual
11. return the number of elements on the list Stack class include DataStruct h method description Pointer accessTop return the top of the stack without removing it return zero if empty void initiali remove all elements from the list Pointer popT return and remove the top element from the stack zero if empty void pushBottom add the element p to the bottom of the stack Pointer p void pushTop Pointer add the element p to the top of the stack p int size return the number of elements on the list TABLE 3 11 Two classes derived from SequentialList U C Berkeley Department of EECS The Almagest 3 13 3 7 Hash Tables Hash tables are lists that are indexed by an ASCII string A hashing function is com puted from the string to make random accesses reasonably efficient they are much more effi cient for example than a linear search over a SequentialList Two such classes are provided in the Ptolemy kernel The first HashTable is generic in that the table entries are of type Pointer and thus can point to any user defined data structure The second Text Ta ble is more specialized the entries are strings It is derived from HashTable The HashTable class is summarized in table 3 12 and Text Table class is summa HashTable class include HashTable h method description void clear empty the table virtual void cleanup does nothing in derived classes thi
12. time the star fires wrapupTcl_SstarID If this procedure is defined in the Tcl script associated with an instance of the Ptolemy TclScript star then it will be invoked every Last updated 10 10 97 5 6 Using Tcl Tk time the wrapup method of the star is invoked In other words it will be invoked when a simulation stops destructorTcl_SstarID If this procedure is defined in the Tcl script associated with an instance of the TclScript star then it will be invoked when the destructor for the star is invoked This can be used to destroy windows or to unset variables that will no longer be needed In addition to the starID global variable the TclScript star makes other information available to the Tcl script The mechanism used is to define an array with a name equal to the value of the starID variable Tcl arrays are indexed by strings Thus not only is starIDa global variable but so is starID The value of the former is a unique string while the value of the latter is an array One of the entries in this array gives the number of inputs that are con nected to the star The value of the expression set starID numInputs is an inte ger giving the number of inputs The Tcl command set when given only one argument returns the value of the variable whose name is given by that argument The array entries are summarized below starID This evaluates to a string that is different for every insta
13. After running mkPtolemyTree edit PTOLEMY src pigiExample make tem plate and add your stars as described in Creating a pigiRpc that includes your own stars on page 1 7 1 4 4 Known Bugs in mkPtolemyTree e To build a customized pigiRpc you set makefile variables like SDF or CG56 to in your override mk If you happen to have an environment variable called SDF or CG56 this procedure fails because the rule in stars mk just checks whether the vari able is defined or not not what value it has So ensure that you have no environment Ptolemy Last updated 10 10 97 1 12 Extending Ptolemy Introduction variables that clash with the variables used in override mk Suggested fix In stars mk not only check whether a variable like SDF is defined but also check its value Hopefully the value is different from the other definition and the code is more robust e IfmkPtolemyTree gives you the following message Making a customized Ptolemy development tr using the version of Ptolemy installed in the directory users ptolemy The new customized Ptolemy tree will go in users cxh mypt mkdir illegal option n mkdir usage mkdir m mode p dirname The try setting your path so that usr ucb is before usr bin The problem here is that in Ptolemy 0 7 the mkPtolemyTree script uses the n option with echo which is not portable e mkPtolemyTree cannot add new directories to an already existing tree it c
14. The parent matrix is the same as the parent matrix of src The given dimensions must fit into the parent matrix or an error will be flagged Unlike the sub matrix constructors in the regular matrix classes this constructor does not copy matrix data XXXSubMatrix const XXXSubMatrix src Make a duplicate of the src sub matrix The parent of the new matrix is the same as the parent of src Submatrices support all operations supported by the regular matrix classes Because the matrix classes uniformly use only the entry and operator member functions to access the data the sub matrix classes need only to override these functions and all matrix operations become available on sub matrices xxx amp entry int i Return the i entry of the sub matrix when its data storage is consid ered to be a linear array xxx operator int row Return a pointer to the start of the row of the sub matrix s data storage Using sub matrices in stars Sub matrices are not currently useful in general purpose dataflow stars Rather they were developed to provide an efficient means of referencing portions of a single larger matrix in the multi dimensional synchronous dataflow MDSDF domain We give here a summary For more details see Che94 and the MDSDF sources in PTOLEMY src domains mdsdf kernel and SPTOLEMY src domains mdsdf stars Unlike other domains the MDSDF kernel does not transfer particles through FIFO buffers Instead each g
15. commercial tool from Pure Software Inc One of the most common mistakes leading to memory leaks is applying the wrong delete operator The delete operator should be used to free a single allocated class or data value whereas the delete operator should be used to free an array of data values In C programming the free function does not make this distinction Another common mistake is overwriting a variable containing dynamic memory with out freeing any existing memory first For example assume that thestring is a data mem ber of a class and in one of the methods other than the constructor there is the following statement thestring new char buflen This code should be delete thestring thestring new char buflen Using delete is not necessary in a class s constructor because the data member would not have been allocated previously In writing Ptolemy stars the delete operator should be applied to variables contain ing dynamic memory in both the star s setup and destructor methods In the star s constructor method the variables containing dynamic memory should be initialized to zero By freeing memory in both the setup and destructor methods one covers all possible cases of memory leaks during simulation Deallocating memory in the setup method handles the case in which the user restarts a simulation whereas deallocating memory in the destructor covers the case in which the user exits a simulation This inc
16. desc U C Berkeley Department of EECS The Almagest 2 27 Generates a ramp signal starting at value default 0 with step size step default 1 output name output type float state name step type float default 1 0 desc Increment from one sample to the next state name value type float default 0 0 desc Initial or latest value output by Ramp attributes A_SETTABLE A_NONCONSTANT go double t double value output S0 lt lt t t step value t The next example is the Gain star which multiplies its input by a constant and outputs the result defstar name Gain domain SDF desc Amplifier output is input times gain default 1 0 input name input type float output name output type float state name gain type float default 1 0 desc Gain of the star go output 0 lt lt double gain double input 0 Ptolemy Last updated 8 26 97 2 28 Writing Stars for Simulation The following example of the Printer star illustrates multiple inputs ANYTYPE inputs and the use of the print method of the Particle class defstar name Printer domain SDF inmulti name input type ANYTYP Awe state name fileName type string default lt cout gt desc Filename for output hinclude pt_fstream h protected pt_
17. e Modify PTOLEMY src pigilib mkTerm c There are three switch statements where you will need to insert a new case e In the directory PTOLEMY 1lib colors ptolemy edit bw pat and colors pat to add the new color The color is in RBG format with 1000 being full scale e Run the Octtools installColors program It will ask you a series of mysterious and strangely beautiful questions To start with use the defaults except for Output dis play type where you answer GENERIC COLOR Run the same program again with the following output display types GENERIC BW Postscript Color and Post script BW e To support monochrome screens when pigi is started with the bw option repeat Ptolemy Last updated 10 10 97 4 42 Data Types the above but specify SPTOLEMY 1lib colors ptolemy bw pat as the pattern file SPTOLEMY 1ib bw_patterns as the directory in which to install GENERIC COLOR as the display device and answer YES to the question about color output device e After rebuilding pigilib and restarting create an icon for a star that has your new type as an input or output The terminal should be of the new color U C Berkeley Department of EECS The Almagest 5 1 Chapter 5 Using Tcl Tk Authors Edward A Lee Other Contributors Brian L Evans Wei Jen Huang Alan Kamas Kennard White 5 1 Introduction Tcl is an interpreted tool command language
18. ie ee ee ee 2 17 2 19 overflow Pix Glass SEER AE Re es 4 4 override mk ee ee 1 7 1 9 1 11 P parallel directory tree mkPtolemyTree iese sesse se ee ee ee ee RR 1 9 parallel schedulers e ees ee ee ee ee ee ee 13 21 parallel software development tree OS SES gee ee SE Ad ee 1 12 PAPAIMCLET rarena ee Ee Ps eee Re eg Ee ses As 2 9 parameters SEE 2 10 Parks T M 1 1 10 1 12 1 13 1 14 1 17 1 Particle Class ie ee 2 17 2 21 4 15 Particle tYDES ee ee ee ee ee ee ee Re ee ee ee ee ee ee 2 21 pathSearch function ees ee ee ee RR 3 8 phase mode in DE sees ee ee ee ee ee 12 12 PHASE Sd GE SEE Es ER GE Raa 12 12 phase based firing mode in DE esse ee 12 12 PUBL EER De RE ED NEE Ge GE OER IE 3 4 pigiExample directory cccccsesesessescseesesescsseteens 1 7 PIGIR PC cies EE heck AO TREA 1 5 1 21 pigiRpc Custom version ees ee ee ee ee ee 1 6 pigiRpc debug e see se see ee ee ee ee RR Re RR ee ee 1 23 Pino JER ees 1 1 6 1 13 1 14 1 15 1 plotting data sss GER EER es ak ac 3 3 Pointer YPE eie ee ek ek ee ee RR RR Re Ge ee 3 11 Poisson DE block ees see se ee ee 3 17 12 9 POISSON PYOCESS ee se ee ee ee ee ee RR Re Ge ee 12 9 POIYMOTPRISM ees se se see ee ee ee ee Re Ge ee Ge ee RR 2 28 PortHole ClaSS cssssssssssssscssseesssesssseessseestseesesnees 2 17 porthole SDF parameters ese se se se ee se ee 7 1 porthole dynamic ese ee ee Re ee ee RE 8 1 ports hiding from the USET
19. no debugging symbols found Tell gdb to read in the core file gdb core core Core was generated by users ptolemy bin sol12 pigiRpc 0 0 wat son eecs berkeley edu 32870 inet 1 2 3 Program terminated with signal 11 Segmentation fault Reading symbols from users ptolemy lib sol2 libcg56dspstars so done Reading symbols from users ptolemy lib sol2 libcg56stars so done Since this version of Ptolemy uses shared libraries we see lots of messages about shared libraries which we ve deleted here for brevity gdb where 0 Oxee7alc20 in kill 1 Ox52b04 in pthread_clear_sighandler 2 Ox52cbh4 in pthread_clear_sighandler 3 0x53130 in pthread_clear_sighandler 4 0x53320 in pthread_handle_one_process_signal 5 0x55658 in pthread_signal_sched 6 0x554d8 in called_from_sighandler 7 Ox535e4 in pthread_handle_pending_signals 8 O0x10100c in SimControl getPollFlag 9 0x101604 in Star run 10 0xd394c in DataFlowStar run 11 Oxeeca5fb8 in SDFAtomCluster run this 0x2bd0b0 at src domains sdf kernel SDFCluster cc 1032 12 Oxeeca0f20 in SDFScheduler runOnce this 0x2bd050 at src domains sdf kernel SDFScheduler cc 121 13 OxeecaOeac in SDFScheduler run this 0x2bd050 at src domains sdf kernel SDFScheduler cc 98 1 Note that core files can be large in size so your system administrator may have setup th
20. puts Since the feedback portholes have a delay marker it is never necessary to mention the feedback output porthole in triggers directives even for an input porthole that gives rise to refireAtTime requests the scheduler is uninterested in zero delay paths to the feedback output The event passed across the feedback arc is an ordinary FLOAT particle normally having value zero Sometimes it can be useful to store extra information in the feedback event Beginning in Ptolemy 0 7 the refireAtTime method accepts an optional second parameter that gives the numeric value to place in the feedback event Fetching the value currently requires direct access to the feedback input port for example if feedbackIn gt dataNew double feedbackValue double feedbackIn gt get A future version of DERepeatStar might provide some syntactic sugar to hide the details of this operation In Ptolemy versions prior to 0 7 DERepeat Star did not place a delay marker on the feedback arc but instead used a hack involving special porthole priorities This hack did not behave very well if the star also had ordinary input portholes To work around it writers of derived star types would sometimes set delayType or provide triggers directives When updating such stars to 0 7 these statements should be examined critically they will often be found to be unnecessary and perhaps even wrong 12 3 Phase Based Firing Mode The ordering of simult
21. t designed to handle bidirectional traffic 17 2 5 Geodesic Models a FIFO buffer usually between two PortHoles Major methods setSourcePort setDestPort disconnect setDelay initialize get numInit Major data members originatingPort destinationPort pstack SZ Set the source PortHole and the delay on this connection A delay is usually implemented as an initial Particle in the Geodesic s buffer but this can be changed depending on the desired functionality Set the destination PortHole Disconnect from the given PortHole Set the number of delays on this connection Initialize the buffer in this Geodesic This means either clear it or insert the number of initial Particles needed to match the number of delays on this connection these Particles are taken from the source PortHoles s Plasma Put a Particle into the buffer Get a Particle from the buffer incCount and decCount are used by a Scheduler to simulate an execu tion Return the number of initial particles A pointer to the source PortHole A pointer to the destination PortHole The buffer implemented as a ParticleStack The number of Particles in the buffer numinitialPparticles 17 2 6 Plasma The number of initial delays There are container object for unused Particles There is one global instance of a Plasma for each type of Particle defined in the kernel This clas
22. 1 5 3 Source Code Control At the present time at Berkeley the Ptolemy group uses SCCS for source code con trol This means that each directory with source code in it contains a subdirectory called SCCS That subdirectory is not distributed with Ptolemy but if you are starting your own development expanding on Ptolemy you may wish to use a similar mechanism We assume here that you are familiar with SCCS which is a standard Unix facility Recall the command above pwd users me Ptolemy src domains ddf stars sw DDFRepeater pl mv cannot access DDFRepeater pl ls a DDFEndCase h DDFThresh cc sei DDFEndCase pl DDFThresh h DDFRepeater pl DDFLastOfN cc DDFThresh pl DDFCase cc DDFLastOfN h SCCS DDFCase h DDFLastOfN pl TAGS DDFCase pl DDFRepeater cc ddfstars c DDFDownCounter cc DDFRepeater h ddfstars mk DDFDownCounter h DDFSelf cc make template DDFDownCounter pl DDFSelf h makefile DDFEndCase cc DDFSelf pl Note the symbolic link to the official SCCS directory This will not be present if you are using the distributed Ptolemy and have not created it Assume however that you have put this directory under SCCS control or someone else has Then you can create an editable version of the DDFRepeater pl star with the command o sccs edit DDFRepeater pl 1 24 new delta 1 25 76 lines The sccs utility tells you the latest version number 1 24 and assigns you a new vers
23. A two input multiplexer is an example when the selection input is known it can ignore the unselected input Non strict stars are the key to avoiding deadlocked situations when there are cyclic connections in the system If all the stars in a cycle are strict they each need all of their inputs before producing an output all will be left waiting The deadlock can be broken by introduc ing a non strict star into the cycle that can produce an output without having all inputs from other stars in the cycle A number of methods set attributes of SR stars These should be called in the setup method of a star as appropriate By default none of these attributes is assumed to hold SRStar reactive Indicate the star is reactive it needs at least one present input to produce a present output Star noInternalState Indicate the star has no internal state its behavior in an instant is a function only of the inputs in that instant and not on history By default a star in the SR domain is strict Here is abbreviated pt lang source for a two input adder defstar name Add domain SR input name inputl type int input name input2 type int output name output type int setup reactive U C Berkeley Department of EECS The Almagest 11 3 noInternalState go if inputl present amp amp input2 present output emit lt lt int inputl get
24. These classes were developed specifically for the experimental multidimen sional SDF MDSDF domain and will probably be implemented differently in a future release There are four sub matrix classes one for each concrete matrix class ComplexSub Matrix FixSubMatrix FloatSubMatrix and IntSubMatrix each of which inherits from the corresponding PtMatrix class A sub matrix contains a reference to a parent matrix of the same type and modifies its internal data pointers and matrix size parameters to reference a rectangular region of the parent s data The constructors for the submatrix classes have arguments that specify the region of the parent matrix referenced by the sub matrix As for matrices the description of sub matrices uses the convention that xxx means Complex Fix Float or Int and xxx means Complex Fix double or int The submatrix constructors are XXXSubMat rix Create an uninitialized matrix XXXSubMatrix int numRow int numCol Create a regular matrix with dimensions numRow by numCol return a new submatrix with this matrix as its parent Memory is allocated for the data storage but the entries are uninitialized XXXSubMatrix XXXSubMatrix amp src int sRow int sCol int nRow Ptolemy Last updated 10 10 97 4 38 Data Types int nCol Create a sub matrix of the given dimensions and initialize it to refer ence the region of the parent matrix starting at sRow sCo1 and of size nRow nCol
25. codeblock addCB output inputl input2 Sref output Sref inputl Sref input2 the line Ptolemy Last updated 10 17 97 13 4 Code Generation ref output ref inputl1 Sref input2 would be lost This is because anything preceding the closing on the same line is dis carded by the preprocessor pt lang Secondly the spaces and tabs between the opening and the first non space character will be ignored The first definition of the addcB codeblock is translated by pt lang into a definition of a static public member in the n file class CGCAdd public CGCStar static CodeBlock addCB An associated constructor call will be generated in the cc file CodeBlock CGCAdd addCB output inputl input2 n Sref output ref inputl1 Sref input2 n i The argument is a single string divided into lines for convenience The following will com plete our definition of the add star go addCode addCB e Notice that the code is added in the go method thus implying that the code is generated in the main loop The addCode code stream name lt unique name gt method of a CG star provides an interface to all the code streams stream name and unique name arguments are optional This method defaults to adding code into the myCode stream codestreams are explained later on If a stream name is specified addCode looks up the
26. f MAKEARCH where MAKEARCH is aC shell script at SPTOLEMY MAKI SPTOLEMY obj SPTARCH for SPTARCH if they do not exist EARCH MAK EARCH will create the necessary subdirectories under We split up the sources and the object files into separate directories in part to make it easier to support multiple architectures from one source tree The directory SPTOLEMY obj SPTARCH contains the platform dependent object files for a particular architecture The platform depen dent binaries are installed into SPTOLI EMY bin PTARCH and the libraries go into SPTOLEMY 1ib SPTARCH Octtools Tcl Tk and Gnu tools have their own set of architec ture dependent directories The makefiles are all designed to be run from the obj PTARCH tree so that object files from different platforms are kept separate when you run make in the SPTOLEMY top level the appropriate obj SPTARCH tree is selected for you automatically We are able to have separate object and source directories by using the make pro gram s VPATH facility Briefly VPATH is a way of telling make to look in another directory for a file if that file is not present in the current directory For more information see the Gnu make documentation in Gnu Info format files in SPTOLEMY gnu common info make SPTOLI FIGURE 1 2 U C Berk EMY srce eley compat domains filters gnu kernel octtools pigiExample pigiRpe pigilib prc ptk
27. falselnput 0 U C Berkeley Department of EECS Chapter 10 PN domain Authors Thomas M Parks Other Contributors Brian Evans 10 1 Introduction The Process Network PN domain is an implementation of the theory presented in Thomas M Parks thesis Par95 The PN domain includes the Synchronous Dataflow SDF Boolean Dataflow BDF and Dynamic Dataflow DDF domains as subdomains This hierar chical relationship among the domains is shown in the User s Manual in Figure 1 2 The model of computation for each domain is a strict subset of the model for the domain that con tains it The nodes of a program graph which correspond to processes or dataflow actors are implemented in Ptolemy by objects derived from the class Star The firing function of a data flow actor is implemented by the run method of Star The edges of the program graph which correspond to communication channels are implemented by the class Geodesic A Geodesic is a first in first out FIFO queue that is accessed by the put and get methods The connections between stars and geodesics are implemented by the class PortHole Each PortHole has an internal buffer The methods sendData and receiveData transfer data between this buffer and a Geodesic using the put and get methods Several existing domains in Ptolemy such as SDF and BDF implement dataflow pro cess networks by scheduling the firings of dataflow actors The firing of a dataflow actor is implemented as
28. htmldoc ptlang directive ees ee ee ee ee ee 2 6 HU Scheduler ees see see ee se see ER SR ee RR RE 13 22 Hylands Co ssccccistssssssccde sedetstiessece 1 1 11 1 17 1 I MO staves EL EE N 3 2 3 3 ifstream class ee ee ee ee 3 2 3 3 image processing use ese ee ee ee ee ee RR Re Ge ee 4 40 include CGCTarget ee ee ee ee ee ee ee ee ee 14 1 include files ese se n Se Se ee 3 1 IADEPort Class ee esse se see se ee ee ee RR RR Re ee 12 5 TnfS tring Class SEE GE a DE dead 3 9 initCode CGCStar method ee ee ee 14 7 initCode method ee ee Ge ee ee 13 2 Department of EECS The Almagest initial value for StatES ees ee ee ee ee ee ee 2 25 initialized Fix objects ee ee ee ee ee ee ee ee 4 6 initializing states from files sees ee 2 23 inline method ptlang direCtiVe ees 2 11 inline virtual method ptlang directive 2 11 inmulti ptang directive sees see ee ee ee ee 2 19 inmulti ptlang directive 2 6 2 11 2 11 inout ptlang directive 2 6 2 11 2 11 inoutmulti ptlang directive 2 6 2 11 2 11 DUE SEE OE DERE EG GE AE E 3 2 3 3 input ptlang directive 2 6 2 11 2 11 2 17 InSDFPort Class eean anan 2 17 2 19 installCOlOfS e esse ee ee ee ee ee ee ee ee ee ee 4 4 int type portholes AA AE ON DON 2 11 StALES Es EE ER ER ida Ee A Rg AR RE EE 2 9 INT MATRIX ENV ees sees ee se ee es see ee ee ee ee 4 30 int_matrix_env type portholes 0 ee ee ee ee e
29. input get output put completionTime pp This star uses the completionTime member to store the time at which it becomes free after processing an input On a given firing if the arrivalTime is later than the completion Time meaning that the input event has arrived when the server is free then the server delays the input by the serviceTime only Otherwise the time stamp of the output event is calcu lated as the serviceTime plus the time at which the server becomes free the completion Time Both pure delays and servers are delay stars Hence their constructor sets the delay Type member summarized in table 12 1 This information is used by the scheduler The technical meaning of the delayType flag is this such a star guarantees that it will never produce any output event with zero delay all its output events will have timestamps Ptolemy Last updated 10 17 97 12 4 DE Domain larger than the time of the firing in which they are emitted Stars that can produce zero delay events should leave delayType set to its default value of FALSE Actually stars often cheat a little bit on this rule as we just saw the standard Delay star sets delayType even if the user sets the star s delay parameter to zero This causes the star to be treated as though it had a positive delay for the purpose of assigning firing priorities which is normally what is wanted Both pure delays and servers are delay stars Hence their constructor se
30. stream using the getStream stream name method and then adds the code into that stream Furthermore if a unique name is provided for the code the code will only be added if no other code has previously been added with the given unique name The method addCode will return TRUE if the code string has been added to the stream and otherwise will return FALSE The star just defined is a very simple star Typical code generation stars will define many codeblocks Conditional code generation is easily accomplished as is done in the fol lowing example go if parameter YES addCode yesblock else addCode noblock U C Berkeley Department of EECS The Almagest 13 5 So far we have used the addCode method to generate the code inside the main loop body In the assembly language domains addCode can be called in the initCode and wrapup methods to place code before or after the main loop respectively In all of the code generation domains we can use the addProcedure method to generate declarations out side of the main body Refer to Code streams on page 13 16 for documentation on the addCode and addProcedure methods The next section describes the extended codeblock support The previous discussion of simple codeblocks is still correct and supported by pt lang the extensions below are upward compatible These extensions are experimental They may change in future version of Ptolemy and may still contain bug
31. 27 CONSUIUCTOLS 2 ee ee ee ee ee ee ee 4 23 CONVEFSION OperatOTS iese ee ee ee ee 4 25 dataType funCHON e ese ees ee ee ee 0 4 29 entry FUNCTION ees sees ee ee ee ee 4 22 4 38 FAXMAtrix oues see ek ee ee ee ee ee ee ee ee ee 4 22 FixMatrix special constructors 4 24 4 25 RES ET AE iiaii 4 22 hermitian function for ComplexMatrix 4 27 including Matrix h into a Star 4 30 indentity FUNCTION eise see ee ee ee eens 4 27 Last updated 10 17 97 TAEMAEIE EE cheek ee cee e 4 22 inverse function ee ee ee 4 27 isA FUNCTION eee ese ee ee ee ee ee ee ee 4 29 Teapackt EE EE EE GER 4 33 MatrixEnvParticle ees se ee ee ee ee ee ee 4 22 multiply FUNCTION eeeeeeseseeteseseeteenene 4 29 outputting to a PortHole sesse see 4 3 print FUNCTION eee ee ee ee ee ee ee ee ee ee ee 4 29 star input and OUIPU e ees ee ee ee ee ee ee ee ee 4 30 transpose FUNCTION ees ee se ee ee ee ee ee ee 4 27 writing Stars that use the Matrix class 4 29 Matrix h include file esse ee ee ee ee 4 30 Message CAS ee ee ee Ee ee 4 14 4 40 message data tYDE ese ee ee ee ee ee ee ee ee ee 2 11 message programming example ee 4 18 message type POTtholesees es suisse whedon twee 2 11 MessageParticle Class ccsceee 2 21 4 15 4 18 method ptlang directive 2 6 2 11 2 15 mk Fe Eo EE EE 1 12 MKPtoleMyTree c cecscesesesseseseseeeeeeseseseeeeseseeeesenes 1 9 MultilnSDEPort class
32. 7 parens white_space gt nothing anything_else is passed through unchanged including the In an extended codeblock trailing backslashes will omit the following newline in the gen erated code This special meaning of trailing may be prevented by using or BACKSLASH 13 2 3 In line codeblocks Code blocks may be specified in the body of a method Inside the definition of a method such as go all contiguous blocks of lines with a leading will be translated into an in line codeblock i e an addCode statement The escape mechanism for C expressions works as described above for codeblocks with arguments Within escaped expressions in line codeblocks may reference local method variables as well as member vari ables Leading white space before a leading will be ignored Note that no override mecha nism is provided to prevent the in line codeblock interpretation Note also that has dual meanings the first on the line introduces in line codeblock mode while subsequent char acters on the same line escape into C expressions For example go CMAM_wait amp Sref ackFlag 1 is equivalent to go addCode CMAM_wait amp Sref ackFlag 1 n A more complicated example go Sref output N int ni input numberPorts for int i 1 i lt ni itt Sref input i i lt ni 4 2 Z n If input numberPorts return
33. Berkeley Department of EECS The Almagest 13 15 Each input is copied to every output This is done by the way the buffers are laid out no code is required input name input type ANYTYPE outmulti name output type input constructor noInternalState start forkInit input output xectime return 0 Where possible code generation domains take advantage of Fork type stars by not allocating output buffers but instead the stars reuse the input buffers Unfortunately in the current implementation assembly language fork stars can not do their magic if the buffer size gets too large specifically if the size of the buffer that must be allocated is greater than the total num ber of tokens generated or read by some port during the entire execution of the schedule Here forks or delay stars that copy inputs to outputs must be used Another example of a Fork Type star is the Spread star The star receives N tokens and spreads them to more than one destination Thus each output buffer may share a subset of its input buffer We call this relationship embedding the outputs are embedded in the input For example in the CGCSpread star setup MPHIter iter output CGCPortHole p int loc 0 while p CGCPortHole itert 0 input embed p loc loc p gt numXfer Notice that the output is a multi porthole During setup we express how eac
34. Current Sponsors The Ptolemy project is supported by the Defense Advanced Research Projects Agency DARPA the State of California MICRO program and the following companies The Alta Group of Cadence Design Systems Hewlett Packard Hitachi Hughes Space and Communi cations LG Electronics NEC Philips and Rockwell The Ptolemy project is an ongoing research project focusing on design methodology for heterogeneous systems Additional support for further research is always welcome Trademarks Sun Workstation OpenWindows SunOS Sun 4 SPARC and SPARCstation are trademarks of Sun Microsystems Inc Unix is a trademark of Unix Systems Laboratories Inc PostScript is a trademark of Adobe Systems Inc About the Cover The image on the cover is from a fourteenth century Provengal illuminated manuscript at the British Library It depicts angels cranking a celestial gear that activates planetary spheres The earth is motionless at the center 1 Extending Ptolemy Introduction ese ee ee ee EER RR RR RR RR 1 1 1 1 IntFOAdUGUHON ss Sing see Cheek Wee ee RR Re OE werd 1 1 1 2 File Organization i dee ae ER went cee wae 1 1 Ptolemy environment variables 1 2 Directory Structure 1 3 1 3 Creating Custom Versions of pigiRpc 1 6 Creating a pigiRpc that includes your own stars 1 7 Creating a pigiRpc with more extensive customizations 1 8 14 Using mkPtolemyTree to create a custom Ptolemy trees 1 9 mkPtolemyTree
35. Instead the StringList and InfString classes should be used as the previous example involving localstring illustrates Sometimes the return value from a routine that returns dynamic memory is not stored and therefore the pointer to the dynamic memory gets lost This occurs for example in nested function calls Code such as puts savestring s should be written as const char newstring savestring s puts newstring delete newstring Several places in Ptolemy especially in the schedulers and targets rely on the hash string function which returns dynamic memory This dynamic memory however should not be deallocated because it may be reused by other calls to hashst ring It is the responsi bility of the hashstring function to deallocate any memory it has allocated U C Berkeley Department of EECS Chapter 3 Infrastructure for Star Writers Authors Joseph T Buck Soonhoi Ha Edward A Lee 3 1 Introduction The Ptolemy kernel provides a number of C classes that are fairly generic and often prove useful to star writers Some of these are essential such as those that handle errors Com plete documentation of the kernel classes is given in The Kernel Manual volume of The Almagest Here we summarize only the most generic of these classes i e the ones that are generally useful to star programmers All of the classes described here may be used in stars provided that the star writer includes the appropriate
36. M macro addr name offset ees ee ee ee ee ee ee 13 11 ref assembly eeuse eek ee ee ee ee ek ee ee ee ee 13 12 FA iia ER N NEN 13 10 TERE ER EE Re EE ee DR Re Ve ae ee eed 13 8 sharedSymbol es esse ese se se ee ek Re ee RR 13 9 StarNaMe e ee ee ee ee ee ee ek ee ee ee ee Ee 13 8 TAAETO DS RR RE ED ie OE ERAS 13 12 macro codeblockSymbol iese se see ee ee 13 10 macros CG Stars ee ee ee ee ee ee ee 13 8 mainDecls CGCTarget member iese sees 14 1 mainLoopCode method ee ee ee ee 13 18 TAK Ch ete tet ee MED OE at 1 4 2 1 make template ccccccscssessscscescscscstesssesesesesesseseees 1 7 makefiles e ee ee ee ee ee ee ee oe ee ek Re ee Re ee 1 4 make star command ee esse se ee ee ee ee ee 2 1 Matrix class sta es ER ee EE Saves 4 21 4 33 QPELALOT NN 4 28 operator unary negation operator 4 27 operator inverse Operator Lu ees se ee 4 27 ET TE 4 25 QPETALOT eeuse se se see ee ee SA ee Re Be ER Se Se ee ERA 4 28 HS Operator san sees ee Ge EE GEE RE 4 26 Popedom ekg ksh Ge ee aes 4 28 HE Opelatonss ees ess eet Re Reese devon kde 4 26 IE operatora n ee 4 26 lt S OPelatOr ve ese ve ee A meteors 4 26 operator assignment Operator 4 25 TT EE 4 25 EE N N 4 27 operator transpose Operator s s s 4 27 Clone function Lees ee se ee ee ee ee ee 4 29 ComplexMatrix ee ee se ee ee ee ee ee Re ee ee e 4 22 conjugate function for ComplexMatrix 4
37. Many methods of the Particle class are redefined in the MessageParticle class to cause a run time error for example it is illegal to send an integer floating or complex number to the particle with the lt lt operator The conversion operators conversion to type int double or Complex return errors by default but can be made legal by redefining the asInt asFloat or asComplex methods for a specific message type The principal operations on MessageParticle objects are lt lt with an argument of type Envelope to load a message into the particle and getMessage Envelope to transfer message contents from the particle into a tiser supplied message The getMessage method removes the message contents from the particle In cases where the destructive behavior of getMessage cannot be tolerated an alternative interface accessMes sage Envelope amp is provided It does not remove the message contents from the particle Promiscuous use of accessMessage in systems where large sized messages may be present can cause the amount of virtual memory occupied to grow though all message will be deleted eventually 4 3 4 Use of messages in stars Here are a couple of simple examples of stars that produce and consume messages For more advanced samples look in the Ptolemy distribution for stars that produce or consume messages The image processing classes and stars which are briefly described below in Image particles on pa
38. Notice that the output porthole is declared to be of type message Notice also the ccin clude statement we must include the file Message h in all message manipulating stars and we must also include the definition of the specific message type we wish to use The code itself is fairly straightforward an Int VecData object is created with new is filled in with data and is put into an Envelope and sent Resist the temptation to declare the IntVecData object as a local variable it will not work It must reside on the heap Here is a star to do the inverse operation defstar name UnPackInt domain SDF desc Accept IntVecData messages and produce integers The first length values from each message are produced Ptolemy Last updated 10 10 97 4 20 Data Types defstate name length type int default 10 desc number of values output per message input name input type message output name output type int ccinclude Message h IntVecData h start output setSDFParams int length int length 1 go Envelope pkt input 0 getMessage pkt if pkt typeCheck IntVecData Error abortRun this pkt typeError IntVecData return const IntVecData pd const IntVecData pkt myData if pd length lt int length Error abortRun this Received message is too short return for i 0 i lt
39. ThreadList dynamic scheduling of Kahn process networks The class ThreadList provides mechanisms for terminating groups of threads This class is used by PNScheduler to create threads for each node in the program graph The class SyncDataFlowProcess implements the threads for the nodes 10 4 1 ThreadList The class ThreadList implements a container class for manipulating groups of threads It has two public methods virtual void add PtThread This method adds a Pt Thread object to the list virtual ThreadScheduler This method terminates and deletes all threads in the list 10 4 2 PNScheduler The class PNScheduler controls the execution of a process network Three data members support synchronization between the scheduler and the processes ThreadList threads A container for the threads managed by the scheduler PNMonitor monitor A monitor to guard the scheduler s condition variable PNCondition start A condition variable for synchronizing with threads U C Berkeley Department of EECS The Almagest 10 13 int iteration A counter for regulating the execution of the processes The createThreads method shown below creates one process for each node in the program graph A SyncDataFlowProcess is created for each DataFlowStar and added to the ThreadList container Create threads dataflow processes void PNScheduler createThreads if galaxy return GalStarIter nextStar
40. Writing stars and programs using the PtMatrix class This section describes how to use the matrix data classes when writing stars Some examples will be given here but the programmer should refer to the stars in PTOLEMY src domains sdf matrix stars pl and SPTOLEMY src domains sdf image Ptolemy Last updated 10 10 97 4 30 Data Types stars pl for more examples Memory management The most important thing to understand about the use of matrix data classes in the Ptolemy environment is that stars that intend to output the matrix in a particle should allocate memory for the matrix but never delete that matrix Memory reclamation is done automati cally by the reference counting mechanism of the Message class Strange errors will occur if the star deletes the matrix before it is used by another star later in the execution seguence Naming conventions Stars that implement general purpose matrix operations usually have names with the _M suffix to distinguish them from stars that operate on scalar particles For example the SDFGain M star multiplies an input matrix by a scalar value and outputs the resulting matrix This is in contrast to SDFGain which multiplies an input value held in a FloatParticle by a double and puts that result in an output FloatParticle Include files For a star to use the Pt Matrix classes it must include the file Matrix h in either its hor cc file If the star has a matrix data member then the decla
41. a function call to the run method of a Star object A scheduler executes the system as a sequence of function calls Thus the repeated actor firings that make up a data flow process are interleaved with the actor firings of other dataflow processes Before invoking the run method of a Star the scheduler must ensure that enough data is available to satisfy the actor s firing rules This makes it necessary for a Star object to inform the scheduler of the number of tokens it requires from its inputs With this information a scheduler can guar antee that an actor will not attempt to read from an empty channel By contrast the PN domain creates a separate thread of execution for each node in the program graph Threads are sometimes called lightweight processes Modern operating sys tems such as Unix support the simultaneous execution of multiple processes There need not be any actual parallelism The operating system can interleave the execution of the processes Within a single process there can be multiple lightweight processes or threads so there are two levels of multi threading Threads share a single address space that of the parent process allowing them to communicate through simple variables There is no need for more complex heavyweight inter process communication mechanisms such as pipes Synchronization mechanisms are available to ensure that threads have exclusive access to shared data and cannot interfere with one another to corru
42. a schedule that is consistent with that precedence graph Note that the precedence graph is not physically constructed There are many possible schedules for all but the most trivial graphs the schedule chosen takes resource costs such as the necessity of flushing reg isters and the amount of buffering required into account The target then generates code by executing the actors in the sequence defined by this schedule This is a quick and efficient approach when the SDF graph does not have large sample rate changes If there are large sam ple rate changes the size of the generated code can be huge because the codeblock for an actor might occur many times if the number of repetitions for the actor is greater than one in this case it is better to use some form of loop scheduling We call the second approach Joe s scheduler In this approach loopingLevel CLUST actors that have the same sample rate are merged wherever this will not cause dead lock and loops are introduced to match the sample rates The result is a hierarchical cluster ing within each cluster the techniques described above can be used to generate a schedule The code then contains nested loop constructs together with sequences of code from the actors U C Berkeley Department of EECS The Almagest 13 21 Since the second approach is a heuristic solution there are cases where some looping possibilities go undetected By setting the loopingLevel to SJS we can
43. access A zero always means the most recent particle A one means the particle arriving just before the most recent particle The same rules apply to outputs Given an output named out the same particles that are read from in can be written to out in the same order as follows go out 1 pastSample out 0 currentSample This works because out n returns a reference to a particle and hence can accept an assign ment The assignment operator for the class Particle is overloaded to make a copy of the data field of the particle Operating directly on class Particle as in the above examples is useful for writing stars that accept anyt ype of input The operations need not concern themselves with the type of data contained by the particle But it is far more common to operate numerically on the data carried by a particle This can be done using a cast to a compatible type For example since in above is of type float its data can be accessed as follows go Particle amp currentSample in 0 double value double currentSample or more concisely go double value double in 0 The expression double in 0 can be used anywhere that a double can be used In many contexts where there is no ambiguity the conversion operator can be omitted double value in 0 U C Berkeley Department of EECS The Almagest 2 19 However since conversion operators are defined to convert particles to several types it is often nec
44. amp x const Complex y operator const Complex amp x double y operator const Complex amp x Return the negative of the complex number conj const Complex amp x Return the complex conjugate of the number sin const Complex x cos const Complex amp x exp const Complex amp x log const Complex amp x sqrt const Complex amp x pow double base pow const Complex amp base Other general operators do ub do do do ubl ubl ubl le abs const Comp do ubl const Complex amp expon const Complex amp expon lex amp x Return the absolute value defined to be the square root of the norm arg const Compl lex amp x Return the value arctan x imag x real lex amp x the value x real x real x imag x imag lex amp x al part of the complex number norm const Compl Return real const Comp Return the re imag const Comp lex amp x Return the imaginary part of the complex number Comparison Operators int in operator operato const Complex amp x const Complex amp x 4 2 2 The fixed point data type const Complex amp y const Complex amp y The fixed point data type is implemented in Ptolemy by the Fix class This class sup ports a two s complement representation of a finite precision number In fixed point notation the partition between the integer pa
45. analogous to the universal Event Horizon in wormholes that is automatically built by using communica tion stars supplied by each code generation target This interface is generated in C using the CGC domain and runs on the Ptolemy host workstation To support this infrastructure a target writer needs to define two pairs of communica Ptolemy Last updated 10 17 97 13 26 Code Generation tion stars and add target methods which return each of these pairs The framework will then build the interface by splicing in these stars as is shown in figure 13 1 These same actors are used when constructing an interface to a Ptolemy simulation target as shown in figure 13 2 User Specification Sim SDF External Sim SDF ooo EM 7 Spliced in simulation SDF send receive actors Cc MES DSP Ja VHDL FIGURE 13 2 General Ptolemy simulation interface The analysis and synthesis filter bank blocks are identical to those described in figure 13 1 The Simin and SimOut stars are built into Ptolemy and defined in PTOLEMY src domains cgc targets main CGCSDF Send Receive pl These communication stars described in section 13 4 2 are a specialized form of send receive stars In addition to the previous assumptions in section 13 4 2 send receive for this infrastructure must also define C code to control the target for operations such as down loading initia
46. and a files will be missing Expand the makefile symbolic links o ls 1 make Ptolemy Last updated 10 10 97 1 16 Extending Ptolemy Introduction lrwxrwxrwx 1 eal 56 Jul 14 11 30 make templat gt users ptolemy obj sol2 domains ddf stars make template lrwxrwxrwx 1 eal 51 Jul 14 11 30 makefil gt users ptolemy obj sol2 domains ddf stars makefile Note that they point to the official makefiles To make them point to the versions in your own tree mkl ls 1 make lrwxrwxrwx 1 eal 47 Jul 14 11 31 make template gt src domains ddf stars make template lrwxrwxrwx 1 eal 42 Jul 14 11 31 makefile gt src domains ddf stars makefile Now you can modify the make template file in your own tree as you need Warning Note that modifying Ptolemy files is risky You will have essentially created your own version of Ptolemy You will not be able to install future releases of Ptolemy without aban doning your version However if you have modifications that you believe are valuable please communicate them to the Ptolemy group at ptolemy eecs berkeley edu The Ptolemy group welcomes suggestions for changes 1 5 2 Creating a Duplicate Hierarchy Let s look at a complete example to see how these aliases can be used Suppose you want to modify an existing file that is part of the kernel for the SDF domain You will need a private copy of the file that is writable This allows you t
47. as described in Section 4 3 on page 4 14 This section discusses the PtMat rix class and how to write stars and programs using this class 4 4 1 Design philosophy The PtMatrix class implements two dimensional arrays There are four key classes derived from PtMatrix ComplexMatrix FixMatrix FloatMatrix and IntMatrix Note that FloatMatrix is a matrix of C doubles A review of matrix classes imple mented by other programmers revealed two main styles of implementation a vector of vec tors or a simple array In addition there are two main formats of storing the entries column major ordering where all the entries in the first column are stored before the entries of the sec ond column and row major ordering where the entries are stored starting with the first row Column major ordering is how Fortran stores arrays whereas row major ordering is how C stores arrays The Ptolemy PtMatrix class stores data as a simple C array and therefore uses row major ordering Row major ordering also seems more natural for operations such as image and video processing but it might make it more difficult to interface Ptolemy s PtMatrix class with Fortran library calls The limits of interfacing Ptolemy s PtMat rix class with other software is discussed in Section 4 4 5 on page 4 33 The design decision to store data entries in a C array rather than as an array of vector objects has a greater effect on performance than the decision whether to use
48. assumes that tokens are available on control inputs and appropriate data inputs This requires that the scheduler be aware of the values of control tokens and the data ports that depend on these values Because our scheduler has no such special knowledge these stars must be properly configured for dynamic multi threaded execution in the PN domain Stars in the BDF domain that have been configured for dynamic execution and stars in the DDF domain dynamically inform the scheduler of data dependent firing rules by designating a particular input PortHole with the waitPort method Data must be retrieved from the designated input before invoking the star s run method The star s run method is invoked repeatedly until it indicates an error by returning FALSE void DataFlowProcess run Configure the star for dynamic execution star setDynamicExecution TRUE U C Berkeley Department of EECS The Almagest 10 7 Fire the Star ad infinitum do if star waitPort star waitPort gt receiveData while star run 10 3 Communication Channels Figure 10 2 shows the class derivation hierarchy for the classes that implement the PtGate PtCondition CriticalSection Posterior j PosixCondition PNMonitor PNCondition FIGURE 10 2 The class derivation hierarchy for monitors and condition variables PtGate and PtCondition are abstract base classes each with several possible implementations Ea
49. binary point The output of any operation will have error codes that are the logical OR of those of the arguments to the operation plus any additional errors that occurred during the operation like divide by zero The division operation is currently a cheat it converts to double and computes the result converting back to Fix The relational operators gt lt gt lt are all written in terms of a function int compare const Fix amp a const Fix amp b This functions returns 1 if a lt b 0 if a b and 1 if a gt b The comparison is exact every bit is checked if the two values have the same precision format If the preci sions are different the arguments are converted to doubles and compared Since dou ble values only have an accuracy of about 53 bits on most machines this may cause false equality reports for Fix values with many bits Conversions operator int const Return the value of the Fix number as an integer truncating towards zero operator float const operator double const Convert to a float or a double creating an exact result when possible void complement Replace the current value by its complement Fix overflow rounding and errors The Fix class defines the following enumerated values for overflow handling Fix ovf_saturate Fix ovf_zero_saturate Fix ovf_wrapped Fix ovf_warning They may be used as arguments to the set overflow method as in the followin
50. cee KEER EE DES cele EE DE 15 1 15 4 Code SIeaMmS ia R EDE Es HE DRAERS E Ri 15 2 Sim56Target Code Streams 15 2 S56XTarget S56XTargetWH Code Streams 15 2 16 C50 Doman Ee de ee ee ede a 16 1 16 1 INGOGUCTION is SE EERS EE DE DOELE GE ED 16 1 16 2 Data Types jie de Ms NE EE EE N WE N eee N Ne EE N N 16 1 16 3 Attributes 93 eee een See ie ED Hei ie io 16 1 164 Code Streams ees oe BEE RE EE ER MA RR RE ee re ee 16 1 16 5 Symbols os wask ER sw EE EE EE EE ew Me se ek EE N 16 2 16 6 Reserved Memory 2000ce cece eee eee eee 16 2 17 Creating New Domains iese ees RR RR RR RR RR RR KEER ER EE EER RE 17 1 17 1 INTOGUCTION tas oet REELE BS BROEDER EE GE Eg 17 1 17 2 A closer look at the various classes 17 2 Target 17 3 Domain 17 3 Star 17 3 PortHole 17 3 Geodesic 17 5 Plasma 17 5 Particle 17 5 Scheduler 17 6 17 3 What happens when a Universe is run 17 6 17 4 Recipe for writing your own domain 17 9 Introduction 17 9 Creating the files 17 9 Required classes and methods for a new domain 17 9 Building an object directory tree 17 10 Ptolemy Last updated 10 17 97 Chapter 1 Extending Ptolemy Introduction Authors Christopher Hylands Edward A Lee Thomas M Parks Jos Luis Pino 1 1 Introduction Ptolemy is extensible in the following ways e New galaxies can be defined We do not view this as a programming task so it is explained in
51. choose the third approach called SJS Shuvra Joe Soonhoi scheduling after the inventor s first names Bha94 After performing Joe s scheduling at the front end it attacks the remaining graph with an algorithm that is guaranteed to find the maximum amount of looping available in the graph A fourth approach obtained by setting loopingLevel to ACYLOOP we choose a scheduler that generates single appearance schedules optimized for buffer memory usage This scheduler was developed by Praveen Murthy and Shuvra Bhattacharyya Mur96 Bha96 This scheduler only tackles acyclic SDF graphs and if it finds that the universe is not acyclic it automatically resets the loopingLevel target parameter to SJS Basically for a given SDF graph there could be many different single appearance schedules These are all opti mally compact in terms of schedule length or program memory in inline code generation However they will in general require differing amounts of buffering memory the difference in the buffer memory requirement of an arbitrary single appearance schedule versus a single appearance schedule optimized for buffer memory usage can be dramatic In code generation it is essential that the memory consumption be minimal especially when generating code for embedded DSP processors since these chips have very limited amounts of on chip memory Note that acyclic SDF graphs always have single appearance schedules hence this scheduler will alw
52. constantly as needed by stars this negates much of the speedup gained from faster lookups Also we felt it was important to keep the design of the class simple and the memory usage efficient because of Ptolemy s increasing size and Ptolemy Last updated 10 10 97 4 22 Data Types complexity 4 4 2 The PtMatrix class The PtMatrix base class is derived from the Message class so that we can use Ptolemy s Envelope class and message handling system However the MessageParticle class is not used by the PtMatrix class instead there are special MatrixEnvParticle classes defined to handle type checking between the various types of matrices This allows the system to automatically detect when two stars with different matrix type inputs and outputs are incorrectly connected together Also the MatrixEnvParticle class has some special functions not found in the standard MessageParticle class to allow easier handling of PtMatrix class messages A discussion of how to pass PtMatrix class objects using the MatrixEnvParticles can be found in a following section As explained previously there are currently four data specific matrix classes Com plexMatrix FixMatrix FloatMatrix and IntMatrix Each of these classes stores its entries in a standard C array named data which is an array of data objects corresponding to the PtMatrix type Complex Fix double or int These four matrix classes implement a common set of operators and fun
53. constructor for the star no 2 12 tor copyright copyright information to include in the generated code no 2 8 derived alternative form of derivedFrom no 2 7 derived the base class which must also be a star no 2 7 from desc alternative form of descriptor no 2 7 descriptor a short summary of the functionality of the star no 2 7 destructor C code to include in the destructor for the star no 2 13 domain the domain and the prefix of the name of the class yes 2 5 explana full documentation See also htmldoc no 2 9 tion exectime specify the execution time for a code generation star no 13 2 go C code to execute when the star fires no 2 14 header C code to include in the h file before the class definition no 2 15 hinclude specify other files to include in the h file no 2 15 htmldoc full documentation optionally using HTML directives inmulti define a set of inputs no 2 11 inout define a bidirectional input and output no 2 11 inoutmulti define a set of bidirectional inputs and outputs no 2 11 input define an input to the star no 2 11 location an indication of where a user might find the star no 2 8 method define a member function for the star class no 2 15 name the name of the star and the root of the name of the class yes 2 5 outmulti define a set of outputs no 2 11 output define an output from the star no 2 11 private define private data members of the star class no 2 14 protected defined protected data members of the star class
54. contain the button name name to use for the button itself desc description to be put into the display callback name of callback procedure to register changes ptkMakeEntry Procedure to make a text entry box in a window A callback procedure must be defined by the programmer It will be called whenever the user changes the value in the entry box and types Ptolemy Last updated 10 10 97 5 8 ptkMakeMeter ptkSetMeter ptkMakeScale U C Berkeley Using Tcl Tk lt Return gt Its single argument will be the new value of the entry Arguments win name of window to contain the entry box name name to use for the entry box itself desc description to be put into the display default the initial value of the entry callback name of callback procedure to reg ister changes Procedure to make a bar type meter in a window Arguments win name of window to contain the entry box name name to use for the entry box itself desc description to be put into the display low the value of the low end of the scale high the value of the high end of the scale Procedure to set the value of a bar type meter created with ptkMakeMeter Arguments win name of window to contain the entry box name name to use for the entry box itself value the new value to display in the meter Procedure to make a sliding scale All scales in the control panel range from O to 100 A callback procedure must be defined by the programmer It will be call
55. distribute copies of it under certain conditions type show copying to see the conditions There is absolutely no warranty for GDB type show warranty for details GDB 4 15 1 sparc sun solaris2 4 Copyright 1995 Free Software Foundation Inc Breakpoint 1 at 0x39ab4 file src pigiExample pigiMain cc line 58 Breakpoint 1 main argc 282850408 argv 0x399c0 at src pigiExample pigiMain cc 58 58 pigiFilename argv 0 gdb cont Continuing At this point you are running Ptolemy Use it in the usual way to replicate your problem When you succeed you will get a message something like Program received signal SIGSEGV Segmentation fault Oxeee81394 in mxRealMax gdb At this point you can again examine the stack This time however there will be more infor mation Here we examine the top 5 frames of the stack gdb where 5 0 Oxeee81394 in mxRealMax 1 0xe3864 in SimControl getPollFlag at src kernel SimCon Erol ce 271 2 Oxe3e5c in Star run this 0x28c908 at src kernel Star cco 73 3 Oxbacb8 in DataFlowStar run this 0x28c908 at src kernel DataFlowStar cc 94 4 Oxef485fb8 in SDFAtomCluster run this 0x278570 at src domains sdf kernel SDFCluster cc 1032 More stack frames follow gdb This particular stack trace is a little strange at the bottom gdb calls the lower num bers the bottom even though they are
56. domains However primarly because absent events are different from undefined ones the interface to these ports are unique Because SR domain ports are unbuffered output ports can be read just like input ports It is often convenient to do this when checking to see whether the value on an output port is already correct and does not need to be changed Input Output Porthole Interface int SRPortHole known Return TRUE when the value in the port is is known int SRPortHole present Return TRUE when the value in the port is present int SRPortHole absent Return TRUE when the value in the port is absent Particle amp InSRPort get Return the particle in the port This should only be called when present returns TRUE Output Porthole Interface Particle amp OutSRPort emit Force the value on the output port to be present and return a reference to the output particle 11 2 SR domain void OutSRPort makeAbsent Force the value on the output port to be absent 11 3 Strict and non strict SR stars Broadly there are two types of stars in the SR domain strict and non strict If any input to a strict star is unknown then all of its outputs are unknown A two input adder for example behaves like this it cannot say anything about its output until the values of both inputs are known A non strict star by contrast can produce some outputs before all of its inputs are known
57. ee 1 21 Free Software Foundation ee ee 1 1 functional star in DE seg soeke koos egg 12 1 G EA ER EA en 2 22 g compiler eie se ee ee ee ee ee ee ee ee ee ee 1 1 Gain SDF block ee ee ee ee se ee ee ee ee ee 2 27 N EE ON N EEN 1 22 1 26 generateCode method ese ee ee ee 13 18 generic pointer technique esse ee ee 3 11 get method ees ee eek 12 5 12 6 12 12 getMessage method MessageParticle ClaSS iese ee ee ee ee 4 18 getSimulEvent method sesse see 12 5 12 11 globalDecls CGCTarget method ees 14 2 ed OD EE 1 22 po Methods ahh EER en ees ed EE RS oes 2 3 go ptlang directive occ ees ee ee ee 2 6 2 14 grabInputs_ starID ees see see ee ee RR 5 4 5 5 Graylmage class i e ee ee ee ee ee RR Re ee ee 4 4 H Ha S ee 2 1 3 1 7 1 8 1 12 1 13 1 14 1 hashifable EE ER RS cuties EE eg De 3 8 hashitables EE AR ON RENE 3 13 HashEntry class e esse se ses se ses ee ee ek Rae Re Ee 3 13 hashing function ees se see ee ee ee ee ee RR Re Ge ee 3 13 hashstring function ees ee ee Re ee ee RE 3 8 HashTable class iese ee ee ee ee 3 13 3 15 HashTablelter class use esse se seen ee Re ee ee 3 13 Haskell Pomeren 4 1 4 40 header ptlang directive ccccecceceeeeeeeees 2 6 2 15 heterogeneous message interface ccccceeeees 4 14 HIER Scheduller ccscccssssssscsesesssssssseseeseseees 13 22 hinclude ptlang directive ees ees 2 6 2 15 Histogram classis neo n 3 5 hppaeftont AE MEE EENS 1 2
58. ee 13 15 Ho Er RE OE NN 13 24 AE N seed 13 15 spread collect SAYS ee ee ee ee ee ee 13 24 srcdir alia ee ee ee ee ee ee 1 2 Sriram Sica sails Se ee es 15 1 stack EE EE T et ee Lhd Ce cece RE 1 22 Stack Class ES ES ER EER ae 3 11 star defining a MEW SA vee ee ee ee ee ee ee n 2 1 sfarsmk GER EE OE Ge Ge 1 6 1 10 SERE EG EE EE 2 9 state ptlang directive 2 6 2 9 2 11 2 21 states hiding from the user iese ee ee ee ee ee 2 26 Static buffering ees see ees ee ee ee ee ee ee ee ee 13 16 Static members ee ee ee ee ee 3 15 Static methods ee ee ee ee ee 3 1 static scheduling Last updated 10 17 97 SDE EERS wie the eee Me 7 1 statistics histogram esse se ee ee ee ee ee ee RR RR 3 5 sidere MES SR ER GE DE ee DE 3 3 IR Oe RE N shi EEN 3 3 SR RE OE EE EN IE 3 3 SUNS States AN ected EE N ND 2 9 stringarray States ees se ee ee ee ee ee RR RR ee 2 9 StringArrayState ClaSS ee ese ee ee ee ee ee ee ee 2 21 Stringlaist ClASS ee RE EE ck Ee 3 9 Stringlistlter Class e ee ese ee ee ee ee ee ee ee 3 10 SNOS oh EE SERE N ee eet Acti bd 3 9 StringState class u ee ee ee ee ee ee RR RR Re ee 2 21 EIE SEE EE OE 13 23 substChar method ee ee 13 12 Sub RI VERSE ete A ES RE DE ee 13 23 SWEIS Ee ge ee eere tens 1 12 RE ee N ARE EA AA 14 3 Switch CGC DIG se n ER EE 14 6 symbolic links ee ee ee ee ee ee ee ee ee ee ee ee 1 12 synchronous dataflow e esse ee ee ee ee ee ee ee 7 1 T target
59. ee ee 4 2 COS FUNCTION ee ee ee ee ee ee ee ee ee ee 4 3 EXPO FUNCTION ese ee ee ee ee ee ee ee 4 3 imag FUNCTION eie ee se ee ee ee 4 2 4 3 log funCHON ese ee ee ee ee ee ee ee 4 3 norm FUNCTION ees ee ee ee ee ee ee ee ee 4 3 POW FUNCTION 00 0 ce ese ee ee ee ee ee ee ee ee 4 3 real FUNCTION Lees ese ee ee ee ee 4 2 4 3 sin FUNCTION Lees ee ee ee ee ee ee ee ee 4 3 sgrt funCHON eeeee ese ee ee ee ee ee ee ee ee ee ee ee ee 4 3 Complex data tye ee see ee ee ee ee eed 4 1 4 3 complex data YE ee ee ee ee ee ee ee ee ee ee 2 11 complex dT ors 2 10 complex type portholes ees ee ee ee ee ee ee ee 2 11 AR EE N EA NE 2 9 COMPLEX MATRIX ENV ees esse ee ee see ee ees 4 30 complex matrix env type portholes ie ESEG e ee ee Ge Reese 2 11 complexarray type AE EO EE OER 2 9 Complex ArrayState class uie ee ee ee ee 2 21 ComplexMatrix see Matrix class ComplexParticle class ee ee ee ee ee ee ee ee 2 21 ComplexState ClasS ee ee ee ee ee 2 21 2 22 computer architecture modeling esse 12 1 conscalls ptlang directive esse es 2 6 2 13 constructor ptlang directive esse es 2 6 2 12 CONSEUCTOFS ee ee ee ee ee ee ee ee ee ee ee 2 13 copy constructor Department of EECS The Almagest Message class uie ee ee ee ee ee ee Re ee 4 16 copyright ptlang directive ee esse see ee ee 2 6 2 8 core dump enenu n ee ee E ee ee ee RR ee a 1 21 core dumped ee se ee ee ee ee ee Re ee 1 21 Gor
60. has two tem plates as shown only for the abortRun method The others are the same 3 3 VO Classes Star programmers often need to communicate with the user The most flexible way to do this is to build a customized window based interface as described in Using Tcl Tk on page 5 1 Often however it is sufficient to plot some data or to just construct strings and out put them to files or to the standard output To do the latter use the classes pt_ifstream and pt_ofstream which are derived from the standard C stream classes ifstream and ofstream respectively More sophisticated output can be obtained with the XGraph class the histogram classes and classes that interface to Tk for generating animated interactive dis plays All of these classes are summarized in this section 3 3 1 Extended input and output stream classes The pt_ofstream class is used in the Printer star on page 2 28 Include the header file pt_fstream h The pt_ofstream constructor is invoked in the setup method with 1 Note that when users run pigi the standard output may appear on a window that is buried The console option to pigi helps in that it creates a specific window for the standard output and other interactions with the user The standard output is much more useful with ptcl the textual interpreter U C Berkeley Department of EECS The Almagest 3 3 the call to new It would not do to invoke it in the constructor for the star since the
61. in table 1 1 Suffix Binary Type pein Standard binary debug Binary with debug symbols purify Binary with Purify and debug symbols guantify Binary with Quantify linked in purecov Binary with Pure Coverage linked in TABLE 1 1 Table of filename suffixes and binary types It is possible to use these makefiles to create binaries that do not have any Ptolemy code A reason why you might want to do this is to take advantage of the Pure Software make definitions in standalone mk To specify no Ptolemy libraries use the make argument NOPTOLEMY 1 1 6 1 Standalone example using StringList For example say you want to use the StringList class in a standalone program 1 Rational http www rational com sells tools such as Purify which can be used to find memory leaks and out of bounds memory accesses Quantify which can be used to profile performance Purecov which can be used to provide code coverage information Ptolemy Last updated 10 10 97 1 20 named bar cc include include Str main StringL cout lt lt Extending Ptolemy Introduction ingList h ist testing This is a test n testing To build it you would type make f SPTOLEMY mk standalone mk bar bin If you wanted to make a new standalone program that also uses part of the CG domain just define the domain make variables as used in stars mk on the make command line make f SPTOLEMY mk standalone m
62. is possible to rely on the compiler to automatically invoke this cast However Warning some compilers notably some versions of g may not choose the expected cast In particular g has been known to cast everything to Fix if the explicit cast is omitted in expressions similar to that above The arithmetic is then performed using fixed point point computations This will be dramatically slower than double or integer arithmetic and may yield unexpected results It is best to explicitly cast states to the desired form An exception is with simple assignment statements like double stateValue myName Even g gets this right Explicit casting should be used whenever a state is used in an expres sion For example from the setup method of the SDFChop star in which use_past_inputs is an integer state if int use_past_inputs input setSDFParams int nread int nread tint offset 1 else input setSDFParams int nread int nread 1 Note that the type Complex is not a fundamental part of C We have implemented a subset of the Complex class as defined by several library vendors we use our own version for maximum portability Using the ComplexState class will automatically ensure the inclusion of the appropriate header files A member of the Complex class can be initialized and oper ated upon any number of ways For details see The Complex data type on page 4 1 A state may be update
63. make sure that the cast agrees with the defini tion of the input port Because multiple envelopes might reference the same matrix a star is generally not permitted to modify the matrix held by the Envelope Thus the function myData returns aconst Message We cast that tobe a const FloatMatrix and then de reference it and assign the value to inputMatrix It is generally better to handle matrices by reference instead of by pointer because it is clearer to write A B rather than A B when working with matrix operations Stars that wish to modify an input matrix should access it using the writableCopy method as explained in Use of the Envelope class on page 4 17 Allowing delays on inputs The cast to const FloatMatrix above is not always safe Even if the source star is known to provide matrices of the appropriate type a delay on the arc connecting the two stars can cause problems In particular delays in dataflow domains are implemented as initial particles on the arcs These initial particles are given the value zero as defined by the type of particle For Message particles a zero is an uninitialized Message particle contain ing a dummy data value This dummy Message will be returned by the myData method in the third line of the above code fragment The dummy message is not a FloatMatrix ren dering the above cast invalid A star that expects matrix inputs must have code to handle empt
64. no 2 14 public define public data members of the star class no 2 14 SE Bui C code to execute at start time before compile time scheduling no 2 13 state define a state or parameter no 2 9 version version number and date no 2 7 ABLE 2 1 A summary of the items used to define a star Additional items are allowed in code generation stars as explained in later chapters A minimal set of the most useful items are shaded U C Berkeley Department of EECS The Almagest 2 7 derivedfrom This optional item indicates that the star is derived from another class Syntax derivedfrom identifier where identifier specifies the base class The n file for the base class is automat ically included in the output n file assuming it can be located you may need to cre ate a makefile For example the LMS star in the SDF domain is derived from the FIR star The full name of the base class is SDFFIR but the derivedfrom statement allows you to say either derivedfrom FIR or derivedfrom SDFFIR The derivedfrom statement may also be written derivedFrom or derived descriptor This item defines a short description of the class This description is displayed by the profile pigi command It has the syntax descriptor text where text is simply a section of text that will become the short descriptor of the star You may also write desc instead of descriptor A principal use of the short descriptor is to get on scre
65. numbers The real part is stored at the lower address 16 3 Attributes In addition to the code generation attributes detailed in 13 2 6 for C50 attributes are defined to specify the Single Access RAM and Double Access RAM memory banks They are A_BMEM Allocate this state in the address range specified by the bMem Map target parameter A_UMEM Allocate this state in the address range specified by the uMem Map target parameter The underlying bits are AB_BMEM and AB_UMEM Each attribute above turns one off and turns the other on e g A_BMEM turns AB_BMEM on and AB_UMEM off Also for C50 stars portholes can assert attributes P_BMEM and P_UMEM which work in exactly the same way as A_BMEM and A_UMEM The default attribute for a C50 porthole is P_BMEM which allocates the porthole buffer in DARAM memory Specifying the P_UMEM attribute places the porthole buffer in SARAM memory 16 4 Code Streams The C50 domain uses the default assembly language code streams discussed in Assembly code streams on page 13 17 Additionally TITarget declares a code stream Ptolemy Last updated 10 10 97 16 2 C50 Domain named TISuProcs to store code that should be placed outside the main loop Note that the code stored in this code stream will get added after the wrapup methods of the stars have been called The TISuProcs code stream is useful for add
66. of the CGCPrinter star initCode StringList s s lt lt FILE SstarSymbol fp addDeclaration s addInclude lt stdio h gt addCode openfile codeblock openfile if SstarSymbol fp fopen Sval fileName w fprintf stderr ERROR cannot open output file for Printer star n exit 1 The file pointer fp for a star instance should be unique globally and the starSymbol macro guarantees the uniqueness Within the same star instance the macro returns the same label SsharedSymbol list name Ptolemy Returns the symbol for name in the list scope This macro is provided so that various stars in the graph can share the same data structures such as sin cos lookup tables and conversion table from linear to mu law PCM encoder These global data structures should be created and initialized once in the generated code The macro sharedSymbo1 does not provide the method to generate the code but does provide the method to create a label for the code To generate the code only once refer to Code streams on page 13 16 A example where a shared symbol is used is in CGCPCM star Last updated 10 17 97 13 10 Code Generation codeblock sharedDeclarations int sharedSymbol PCM offset 8 Convert from linear to mu law int sharedSymbol PCM mulaw x double x double m m pow 256 0 fabs x 1 0 255 0 return 4080 0 m codeb
67. row major or col umn major ordering There are a couple of advantages to implementing a matrix class as an array of vector class objects referencing an entry may be faster and it is easier to do opera tions on a whole row or column of the matrix depending on whether the format is an array of column vectors or an array of row vectors An entry lookup in an array of row vectors requires two index lookups one to find the desired row vector in the array and one to find the desired entry of that row A linear array in contrast requires a multiplication to find the location of first element of the desired row and then an index lookup to find the column in that row For example A row col is equivalent to looking up sdata row numRows col if the entries are stored in a C array data whereas it is amp rowArray row colif looking up the entry in an array of vectors format Although the array of vectors format has faster lookups it is also more expensive to create and delete the matrix Each vector of the array must be created in the matrix construc tor and each vector must also be deleted by the matrix destructor The array of vectors format also requires more memory to store the data and the extra array of vectors With the advantages and disadvantages of the two systems in mind we chose to imple ment the PtMat rix class with the data stored in a standard C array Ptolemy s environment is such that matrices are created and deleted
68. size wrapup starList initialize This star has a static private member of type SequentialList with name starList The static in C ensures that there will be no more than one instance of the Sequential List object That instance will be accessible to every instance of the star but not to any other object because the member is private That one instance is actually declared by the lines code SequentialList SDFShare starList The declaration will get put into the file SDFShare cc by the preprocessor Notice that the class name of the star is SDFShare not just Share The begin method simply adds to the sequential list a pointer to the star that invoked the begin method this Note that you should use the begin method here rather than the setup method because the begin method is always invoked exactly once while the setup method might be invoked more than once when the simulation starts up The go method sends to the output named howmany the size of the list This will be equal to the number of stars of this type in the universe The wrapup method has the only tricky part of this code It reinitializes the Sequen tialList so that subsequent runs do not just simply add to a list created by previous runs However note that the wrapup method will not be invoked if an error occurs during the run Pigi ensures correct operation nonetheless by deleting all instances of the stars and recreat ing them if an error occu
69. star could use get within the loop if it did need the event values Sometimes a star simply needs to know how many simultaneous events are pending on a given porthole Without fetching any event we can get the number of simultaneous events by calling the numSimulEvents method This returns the number of simultaneous events still waiting in the global event queue the one already in the porthole isn t counted If the star has multiple input ports the programmer should carefully consider the desired behavior of simultaneous inputs on different ports and choose the order of processing of events accordingly For example it might be appropriate to absorb all the events available for a control porthole before examining any events for a data porthole If a star will always absorb all simultaneous events for all its input portholes it can use phase based firing mode to improve performance See section 12 3 12 2 5 Non deterministic loops The handling of simultaneous events is based on assigning priorities to portholes trac ing the connectivity of a schematic and using the relationships established by the before and triggers relationships When we assign these priorities we start from the input ports of sink stars and rely primarily on a topological sort Delay free loops which would prevent the topological sort for terminating are detected and ruled out But another kind of loop called a non deterministic loop can cause un
70. star instances pointing to it Thus it first checks the hash table to see whether there exists an entry with key equal to mySubset If there does then it removes that entry and deletes the SequentialList myList 3 9 Using Random Numbers Ptolemy uses the Gnu library routines for the random number generation Refer to Vol ume II of the Art of Computer Programming by Knuth for details about the method There are built in classes for some popular distributions uniform exponential geometric discrete uni form normal log normal and so on These classes use a common basic random number gen eration routine which is realized in the ACG class Here are some examples of using random numbers The first example is the part of the DE Poisson star See the DE chapter for details on how to write DE stars hinclude lt NegExp h gt ccinclude lt ACG h gt protected NegativeExpntl random declare the static random number generator in the cc file code extern ACG gen constructor random NULL destructor if random delete random setup if random delete random random new NegativeExpnt1 double meanTime gen DERepeatStar setup go Generate an exponential random variable double p random The built in class for an exponentially distributed random numbers is NegativeExpntl The Ptolemy kernel provides a single object to generate a str
71. stars are written let s write an adder star for the C code generation domain The defstar is almost the same as for a simulation star defstar name Add domain CGC desc Output the sum of the inputs as a floating value author J Pino input name input1 type float input name input2 type float output name output type float 13 2 1 Codeblocks Next we have to define the C code which will be used to generate the run time code For this we use a codeblock A codeblock is a pseudo language specification of a code seg ment By pseudo language we mean that the block of code is written in the target language with interspersed macros Macros will be explained in the following section Codeblocks are implemented as protected static class members e g there is one instance of a codeblock for the entire class Since they are protected codeblocks from one star class can be used from a derived star The codeblock directive defines a block of code with an associated identifying name addCB in this case codeblock addCB output inputl input2 Sref output Sref inputl ref input2 Special care should be given to codeblock specification Within each line spaces tabs and new line characters are important because they are preserved For this reason the brackets should not be on the same lines with the code Had addcB been defined as follows
72. the mapped name returned by isCmdArg cmdargStatesInits calls cmdargStatesInit to generate the default values of the settable states setargStates calls setargState to generate the code segment to match the mapped name to the command line options setargStatesHelps calls setargStatesHelp to build up the help message These are called in the CGCTarget declareStar CGCStar star function after the global and main declarations have been generated CGCStar initCod eState const State state is modified to generate the required initialization code if state is to be settable from the command line In order for a va1 state to be settable from the command line it has to be changed to a reference state The expandVal member function is overloaded in CGCStar to check if the name state is to be made settable from the command line If so it is added to the list of referenced state so that it will be declared and initialized 14 4 3 Limitations of command line arguments Currently this implementation works only for scalar states with float or integer values Extension to other types of state should be straight forward by simply adding the appropriate struct member declaration code in CGCStar cmdargState const State state The cmdargStatesInit setargState setargStatesHelp and initCode String member functions need to be modified accordingly to generate codes for the ini tialization setti
73. virtual void notifyAll 0 This method sends notification to all waiting threads If multiple threads are waiting for notification all of them are activated Once activated all of the threads attempt to reacquire the lock on the gate but only one of them succeeds The others are sus pended again until they can acquire the lock on the gate 10 3 5 PosixCondition The class PosixCondition provides an implementation for the interface defined by PtCondition The implementations of the wait notify and notifyAll methods are shown below void PosixCondition wait Guarantee that the mutex will not remain locked by a cancelled thread pthread_cleanup_push void void pthread_mutex_unlock amp mutex pthread_cond_wait amp condition amp mutex Remove cleanup handler but do not execute pthread_cleanup_pop FALSE Ptolemy Last updated 4 17 97 10 10 PN domain void PosixCondition notify pthread_cond_signal amp condition void PosixCondition notifyAll pthread_cond_broadcast amp condition 10 3 6 PNGeodesic The class PNGeodesic which is derived from the class Geodesic defined in the Ptolemy kernel implements the communication channels for the PN domain In conjunction with the PtGate member provided in the base class Geodesic two condition variables pro vide the necessary synchronization for blocking read and blocking write ope
74. 1 addPort p2 star 2 addPort p3 Connect em up The graph is star 1 3 lt 2 star 0 3 gt 2 star 2 PO connect pl connect Scheduling AcyLoopScheduler sched sched setGalaxy topGalaxy cout lt lt No problem till now Calling sched setup n sched setup int ds for i 0 i lt 3 itt cout lt lt star i fullName lt lt n cout lt lt Repetitions lt lt star i reps lt lt n StringList sch sched displaySchedule cout lt lt sch The command to compile this and produce a standalone binary would be make f SPTOLEMY mk standalone mk OPTIMIZER SDF 1 USE_SHARED_LIBS yes testAcyLoopSched debug 1 7 Debugging Ptolemy and Extensions Within Pigi The extensibility of Ptolemy can introduce problems Code that you add may be defec tive few people write perfect code every time or may interact with Ptolemy in unexpected ways These problems most frequently manifest themselves as a Ptolemy crash where the Ptolemy kernel aborts creating a core file The fact that pigiRpc and vem are separate Unix processes has the advantage that when pigiRpc aborts with a fatal error vem keeps running Your vem schematic is unharmed and can be safely saved Vem gives a cryptic error message something like RPC Error server application exited without calling RPCExit Closing Application home ohml users messer ptolemy lib pigiRpcShell on host foucau
75. 8 uniformly distributed random number ees 3 18 uninitialized Fix objeCt ees ee ee ee ee eke 4 6 user defined messages ee ee ee ee Re ee 4 15 V value method HashEntry class esse ee ees ee ee ee ee 3 13 VEGLOT MESSABE esse see se ek se se Ge ee RR BA ee Re Se Ee 4 15 VEM Se ED DE ED heated 1 1 version ptlang directive cccceeseeeeeeeeeene 2 6 2 7 video processing ius ee ee ee ee ee ee RR Re Ge ee 4 40 virtual method ptlang directive 2 11 Ww waitFor method DDFStar claSS ee ee ee S 8 2 White K EE DE RE GR toy 13 1 14 1 15 1 Williamson M esasa uenen ee ee ee ee 17 1 wrapup Star method sees ee ee Re ee 14 2 wrapup method ee ee ee ee ee ee ee ee Re ee 3 15 wrapup ptlang directive ees es 2 6 2 14 writableCopy method Envelope class ssesescssssessssssssessescscsssesnens 4 17 writeCode method ee ee ee 13 18 X X window system ee ee ee ee Re ee ee ee ee RR 3 3 XGraph classan EE ES Ee 3 3 XHistogram CAS ees ee ee ee ee ee Re ee terete 3 5 Y WACO E A EEEL E ES E E EENET 2 4 Department of EECS
76. ANT attribute then its value is not modified by the run time code in the star it is up to you as the star writer to ensure that this condition is satisfied States with the A_NONCONSTANT attribute may change when the star is run If a state has the A_SETTABLE attribute then user interfaces such as pigi will prompt the user for values when directives such as edit parameters are given States without this attribute are not presented to the user such states always start with their default values as the initial value If no attributes are specified the default is A_CONSTANTIA_SETTABLE Thus in the above example Oe attributes directive is unnecessary The notation A CONSTANTIA SETTABLE indicates a logical or of two flags Confusingly this means that they both apply A_CONSTANT and A SETTABLE Code generation stars use a great number of attributes many specific to the language model for which code is being generated Read chapter 13 Code Generation and the documentation for the appropriate code generation domain to learn more about these Mechanisms for accessing and updating states in C methods associated with a star are explained below in sections 2 4 3 on page 2 21 and 2 4 4 on page 2 23 U C Berkeley Department of EECS The Almagest 2 11 An alternative form for the state directive is defstate The subitems of the state direct
77. Message method MessageParticle ClaSS i iese ee ee ee ee 4 18 ACG classname aa N n eh 3 17 acknowledge ptlang directive ees ees 2 6 2 8 ACYLOOP SDF scheduler option 004 13 21 Ada SDF Dle N bd bok Ee Ee 2 20 addCode CGStar method ee ee 14 2 14 7 addCompileOption CGCTarget method 14 2 addDeclaration CGCStar method ees ee 14 2 AddFix SDF block ee ee Re RA Re 4 5 addGlobal CGCStar method iese eek ee 14 2 addInclude CGCStar method sees ee 14 2 addLinkOption CGCTarget method 14 2 aggressive reclamation c cceccesesesesseseeeeeeeeeees 4 18 aliases BRD EE EDE EEUE DNE 1 12 MiKo N a 1 12 ei ON ON N EA OE deme 1 2 ELE AE OE 1 12 ot Re AO N EL EE ED 1 12 di OE N OE ee 1 12 Bien ee ate thes th 1 2 EO NEE NE EE TE DOT 1 12 aliases for developers u ee ee ee ee ee ee ee ee ee 1 12 allocateMemory method ee ee ee ee ee 13 18 anytype porthole eee ee ee ee ee ee ee ee ee ee 2 11 application exited error Message iese ee 1 21 Ptolemy l 1 ArrayState ClaSS ee ee ee ek RR RR RR 2 23 ArrivingPrecision parameter esse ses sees see ee ee 4 7 asComplex method Message class ee ee ee ek ee ee RR 4 18 asFloat method Message class ee ee ee Re ee RR 4 18 asInt method Message class c ssssssssesesesessessssseseetesseesees 4 18 AsmPortHole class iese ee ee ee 13 12 DUE Stee Se a 2 9 2 10 2 21 As CIRC shots vests en SE ge ee Bee tenet 13 13 A CONSEC
78. NE EDE EE Es ER ER ee ede 3 1 3 2 Handling EfrofS iese ie GR Ee ie Ee wee be 3 1 3 3 VOGClasses oe ons Mie ee ge oes Die Maen ae 3 2 Extended input and output stream classes 3 2 Generating graphs using the XGraph class 3 3 Classes for displaying animated bar graphs 3 4 Collecting statistics using the histogram classes 3 5 34 String Functions and Classes 0000eeeeee 3 8 3 5 dietatOfS se EE RR ER OD DEE a EE wae pee 3 10 3 6 LISECl4SSE6S se Vd Gh SLEE EES See De Ke leks 3 11 3 7 Hash Tables oues bee cates cis WE ER EE ew ec Ee N 3 13 3 8 Sharing Data Structures Across Multiple Stars 3 14 3 9 Using Random Numbers 000eeeeeeeee 3 17 4 Data TY DOS Se EED SA De ce ee ee ee ed es 4 1 4 1 Introduction EER DE RE RE ER AE Rd See teens 4 1 4 2 Scalar Numeric Types 2000e eee RR RR eens 4 1 The Complex data type 4 1 The fixed point data type 4 3 4 3 Defining New Data Types 000 eee Ra ee 4 14 Defining a new Message class 4 15 Use of the Envelope class 4 17 Use of the MessageParticle class 4 18 Use of messages in stars 4 18 4 4 The Matrix Data Types 2000 RR ER eee eee 4 21 Design philosophy 4 21 The PtMatrix class 4 22 Public functions and operators for the PtMatrix class 4 22 Writing stars and programs using the PtMatrix class 4 29 Future extensions 4 33 4 5 The File and String Types 200eeeeeee 4 34 The File type 4 34 The String type 4 35 4 6 Writing Stars Tha
79. NGING ccccsescsseseseseesesescecesessscststenens 4 11 setToZero ee ee Ge ee ee 4 11 Sien BiO ee EE a TE a 4 11 uninitialized e ee ee ee ee ee ee Re ee 4 6 valdeO sae ak ece thse Ee Me oe 4 11 fix type portholes sei EE EE ee EER Ee ge 2 11 SERIES oe EE EE AAA ei 2 9 FIX MATRIX ENV GEE Ee Dee Er gee ee eg dee 4 30 fix_matrix_env type POTthOleS cccecescsesesssescscessscscstesesesesesnsesseees 2 12 FIX MAX LENGTH ee nnnrnnnnn 4 4 Fixed point inputs and outputs e ees se ee ee ee ee RR 4 5 fixed POINE eeue ee ee ee ee ek RR RR Re ee ee ee ee 4 3 array ParamEteTS e ees oe ee ee ee ee ee n 4 4 parameters uses ee ee ee ee ek ee Re ee ee 4 4 precisi n e a 2 10 setting precision ees ee ee ereet e 2 10 States E EO EE EOE EOE 4 4 Fixed point data type uses ees ee ee ee ee 72 4 14 FixMatrix see Matrix class Bix Parcels clas Simien Ee RE 2 21 float type portholes ie EE Ge ee Ee ese e 2 11 SIR RE EE N oo RE 2 9 FLOAT MATRIX ENV Rise ei eek ie ee 4 30 float matrix env type portholess hee RE ee Ee Ee aks 2 11 floatarray type EE N ND ed 2 9 FloatArrayState Class ese ee ee 2 21 2 23 FloatMatrix see Matrix class FloatParticle class ee ee ee 2 21 FloatState claSS ees ee se ee ee ee ee ee ee ee ee 2 21 Fork U C Berkeley code generation oo ee ee ees ee ee ee 13 14 Fork SDF block ee ee ee ee se ee ee ee ee ee ee 2 20 frameCode method ee ee ee ee 13 18 fread of long failed ee ee ee ee ee ee
80. PRIVATE U C Berkeley Department of EECS The Almagest 13 13 Opposite of A_SHARED The default for stars is A_LOCAL A_PRIVATE Right now only A_SHARED A_LOCAL is sup ported in the assembly language domains This combination means that all stars will share the particular state across a processor For all stars to share it in a universe the bits A SHAREDIA GLOBAL need to be set this combination is not implemented yet the default method will probably restrict all the stars that share this state to the same processor A_CONSTANT The state value is not changed by the star s execution A_NONCONSTANT The state value is changed by the star s execution A_SETTABLE The user may set the value of this state from a user interface A_NONSETTABLE The user may not set the value of this state from a user interface e g edit parameters doesn t show it Applying an attribute to an object implies that some bits are to be turned on and oth ers are to be turned off The underlying attribute bits have names beginning with AB_ for states and PB_ for portholes The only two bits that exist in all states are AB_CONST and AB_SETTABLE By default they are on for states which means that the default state works like a parameter you can set it from the user interface and the star s execution does not change it For assembly language domains the following attributes are def
81. Reilly Sunil Samel IMEC Chris Scannel NRL Sun Inn Shih Mario Jorge Silva Rick Spickelmier Eduardo N Spring Richard S Stevens NRL Richard Tobias White Eagle Systems Technology Inc Alberto Vignani Fiat Gre gory Walter Xavier Warzee Thomson Anders Wass Jiirgen Weiss U Stuttgart Andria Wong Anthony Wong Mei Xiao Chris Yu NRL Copyright 1990 1997 The Regents of the University of California All rights reserved Permission is hereby granted without written agreement and without license or royalty fees to use copy modify and distribute the Ptolemy software and its documentation for any pur pose provided that the above copyright notice and the following two paragraphs appear in all copies of the software and documentation IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR DIRECT INDIRECT SPECIAL INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMEN TATION EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRAN TIES INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MER CHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE THE SOFTWARE PROVIDED HEREUNDER IS ON AN AS IS BASIS AND THE UNIVERSITY OF CAL IFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE SUPPORT UPDATES ENHANCEMENTS OR MODIFICATIONS Ptolemy Last updated 8 27 97
82. S see kaas cece RR RR RA Re 9 1 10 PM domain DE EE EE ee ee EE 10 1 10 1 Introduction SES n ea ee ee te ed EE ei rd ee ie 10 1 10 2 Pro tesseS iewe ERWE eee eee EE N 10 3 The PtThread Class 10 3 The PosixThread Class 10 4 The DataFlowProcess Class 10 6 10 3 Communication Channels iss sak RE EER Re 10 7 PtGate 10 8 PosixMonitor 10 8 CriticalSection 10 8 PtCondition 10 9 PosixCondition 10 9 PNGeodesic 10 10 104 Scheduling s ieis Ee ee Ee Boere a 10 12 ThreadList 10 12 PNScheduler 10 12 10 5 Programming Stars in the PN Domain 10 15 Ptolemy Last updated 10 17 97 T1 SR AO aI EERS ES GESE Se Re SEE N NEE Ee EER EE ee ie 11 1 11 1 Introduction ss Re SEE ees Shen es oe ke be 11 1 11 2 Communication in SR iss tas ss ss Ese ee 11 1 11 3 Strict and non strict SR stars ss sk ss EE RR ee 11 2 12 DE Domali ss sede de de ei ee de ee ee N GAN EG de 12 1 12 1 Introduction ss sk ss RE RR RE RE RE ER Re 12 1 12 2 Programming Stars in the DE Domain 12 1 Delay stars 12 2 Functional Stars 12 4 Seguencing directives 12 6 Simultaneous events 12 7 Non deterministic loops 12 8 Source stars 12 8 12 3 Phase Based Firing Mode sae ek ks sae 12 11 12 4 Programming Examples sesse ek ks sae 12 13 Identity Matrix Star 12 13 Matrix Transpose 12 14 13 Code Generation ee ee KERR ER RE RR EER Ee RR GR ee Re ER Ke Ke RR Re Rae 13 1 13 1 Introduction see
83. StringList or InfString class e g InfString localstring if person absent return localstring otherstring return Both StringList and InfString can manage the construction of strings of arbi trary size When a function or method exits the destructors of the StringList and Inf String variables will automatically be called which will deallocate their memory Casts have been defined that will convert StringList to a const char string and InfString toa const char or a char string so that instances of the StringList and InfString classes can be passed as is into routines that take character array string arguments A good example of using the StringList class is in the function compile in the file SPTOLEMY src pigilib pigiLoader cc A simpler example from the same file is the noPermis sion function which builds up an error message into a single string StringList sl msg sl lt lt file lt lt lt lt sys_errlist errno ErrAdd sl The errAdd function takes a const char argument so s1 will converted automatically to aconst char string by the C compiler Instead of using the new and delete operators it is tempting to use constructs like char localstring buflen 1 in which buflen is a variable because the compiler will automatically handle the deallocation of the memory Unfortunately this syntax is a Gnu extension and not portable to other C compilers
84. The PtGate is locked as soon as the Critical Section is constructed When execution of the code exits scope the CriticalSection destructor is automatically invoked unlocking the PtGate and preventing errors caused by forgetting to unlock it Examples of this usage are shown in Section 10 3 6 Because only one thread can hold the lock on a PtGate only one section of code guarded in this way can be active at a given time CriticalSection PtGate g mutex g if mutex mutex gt lock U C Berkeley Department of EECS The Almagest 10 9 CriticalSection if mutex mutex gt unlock 10 3 4 PtCondition The class PtCondition defines the interface for condition variables in Ptolemy A PtCondition provides synchronization through the wait and notify methods A condi tion variable can be used only when executing code within a critical section i e when a PtGate is locked PtGate amp mon This data member refers to the gate associated with the Pt Con dition object virtual void wait 0 This method suspends execution of the current thread until noti fication is received The associated gate is unlocked before exe cution is suspended Once notification is received the lock on the gate is automatically reacquired before execution resumes virtual void notify 0 This method sends notification to one waiting thread If multi ple threads are waiting for notification only one is activated
85. The first line of the go method creates an MPHIter iterator called nextp initialized to point to portholes in output The operator on the iterator returns a pointer to the next porthole in the list until there are no more portholes at which time it returns NULL So the while construct steps through all output portholes copying the input particle data to each one Consider another example taken from the SDF Ada star inmulti name input type float output name output type float go MPHIter nexti input PortHole p double sum 0 0 U C Berkeley Department of EECS The Almagest 2 21 while p nextit 0 sum double p 0 output 0 lt lt sum Again an MPHIter iterator named next i is created and used to access the inputs Upon occasion the numberPorts method of class Mult iPortHole which returns the number of ports is useful This is called simply as portname numberPorts and it returns an int Type conversion The type conversion operators and lt lt operators are defined as virtual methods in the base class Particle There are never really objects of class Particle in the system instead there are objects of class IntParticle FloatParticle ComplexParticle and FixParticle which hold data of type int double not float Complex and Fix respectively there are also MessageParticle and a variety of matrix particles described later The c
86. To build all the o files type cd SPTOLEMY make install The complete build process can take upwards of three hours If you use an over ride mk file you can reduce the build time by building only the functionality you need See Using mkPtolemyTree to create a custom Ptolemy trees on page 1 9 for more information 2 Edit SPTOLEMY src pigiExample make template Add your stars to LOCAL_OBJS and PL SRCS 3 ca to SPTOLEMY obj SPTARCH pigiExample and type make depend to update the makefile from the make template You will see messages some thing like Ptolemy Last updated 10 10 97 Extending Ptolemy Introduction makefile remad you must rerun make exit 1 make makefile Error 1 This is normal and you may safely ignore the error message While still in SP TOL make EMY obj PTARCH pigil Example type This will create a version of the pigiRpc executable with your own stars statically linked in If later you add a new star you should modify the symbols oi PLSRCS in make template to include it and repeat the above procedure starting up with pigi rpc PTOL src pigil EMY obj PTARCH pigil Example init pal Example pigiRpc PTOLI BJS and If you built your pigiRpc with SDFMyStar o you can test your pigiRpc by EMY and then run the wave universe If you want to have the binary you just built be the de
87. UNIVERSITY OF CALIFORNIA AT BERKELEY COLLEGE OF ENGINEERING DEPARTMENT OF ELECTRICAL ENGINEERING AND COMPUTER SCIENCES BERKELEY CALIFORNIA 94720 bpe en VEE oimne ur urio Dug Ae ma OLGA Te er oC TEEN Snare oot Te aps Fi t 2 mne Cotte ct ire 3 va baci ener oo CE phate cd heme mi Ms Ela DU TERDEE EET Vol 2 Ptolemy 0 7 Programmer s Manual Primary Authors Shuvra Bhattacharyya Joseph T Buck Wan Teh Chang Michael J Chen Brian L Evans Edwin E Goei Soonhoi Ha Paul Haskell Chih Tsung Huang Wei Jen Huang Chris topher Hylands Asawaree Kalavade Alan Kamas Allen Lao Edward A Lee Seungjun Lee David G Messerschmitt Praveen Murthy Thomas M Parks Jos Luis Pino John Reekie Gilbert Sih S Sriram Mary P Stewart Michael C Williamson Kennard White Other contributors Raza Ahmed Egbert Amicht AT amp T Sunil Bhave Anindo Banerjea Neal Becker Comsat Jeff Bier Philip Bitar Rachel Bowers Andrea Cassotto Gyorgy Csertan T U Budapest Stefan De Troch IMEC Rolando Diesta Martha Fratt Mike Grimwood Luis Gutierrez Eric Guntvedt Erick Hamilton Richard Han David Harrison Holly Heine Wai Hung Ho John Hoch Sangjin Hong Steve How Alireza Khazeni Ed Knightly Christian Kratzer U Stuttgart Ichiro Kuroda NEC Tom Lane Structured Software Systems Inc Phil Lapsley Bilung Lee Jonathan Lee Wei Yi Li Yu Kee Lim Brian Mountford Douglas Niehaus Univ of Kansas Maureen O
88. a Scheduler or Target An example is in parallel scheduling where the original stars in the InterpUniverse are moved to the subGalaxies for the child Targets see PTOLEMY src domains cg parScheduler ParProcessors cc To signal that a the InterpUniverse needs to be rebuilt upon the next run the scheduler writer should invoke Target requestReset U C Berkeley Department of EECS The Almagest 6 7 6 7 References Cor90 Cormen Leiserson and Rivest Introduction to Algorithms New York MIT Press 1990 Mur94 Murthy Bhattacharyya and Lee Combined code and data minimization for synchronous dataflow programs Memorandum UCB ERL M94 93 University of California at Berkeley December 1994 http ptolemy eecs berkeley edu papers jointCodeDataMinimize Pin95 Pino Bhattacharyya and Lee A Hierarchical Multiprocessor Scheduling Framework for Synchronous Dataflow Graphs Memorandum UCB ERL M95 36 University of California at Berkeley May 1995 http ptolemy eecs ber keley edu papers hierStaticSched Ptolemy Last updated 10 10 97 6 8 Using the Cluster Class for Scheduling U C Berkeley Department of EECS Chapter 7 SDF Domain Authors Joseph T Buck Soonhoi Ha Edward A Lee 7 1 Introduction Synchronous dataflow SDF is a statically scheduled dataflow domain in Ptolemy Statically scheduled means that the firing order of the stars is determined once during the start up phase The firing o
89. a new matrix that has entries of the source matrix multiplied by a scalar value XXXMatrix operator const XXXMatrix amp matrix const xxx amp sca lar Example A Bo oD Return a new matrix that has entries of the source matrix multiplied by a scalar value This is the same as the previous operator but with the scalar on the right Miscellaneous functions int numRows int numCols Return the number of rows in the matrix Return the number of columns in the matrix Message clone Example IntMatrix B A clone Return a copy of this StringList print Example A print Return a formatted St ringList that can be printed to display the con tents of the matrix in a reasonable format XXXMatrix amp multiply const XXXMatrix amp left const XXXMatrix amp right XXXMatrix amp result Example multiply A B C This is a faster 3 operand form of matrix multiply such that the result matrix is passed as an argument so that we avoid the extra copy step that is involved when we write C A B const char dataType Example A dataType Return a string that specifies the name of the type of matrix The strings are ComplexMatrix FixMatrix Matrix 99 66 oF oe FloatMatrix and Int int isA const char type Example if A isA FixMatrix then Return TRUE if the argument string matches the type string of the matrix 4 4 4
90. a self scheduling star A self scheduling star fools the scheduler by generating its own input events These feedback events trigger the star firings An event generator is a spe U C Berkeley Department of EECS The Almagest 12 9 cial case of a delay star in that its role is mainly to control the time spacing of source events The values of the source events can be determined by a functional block attached to the output of the event generator e g Const Ramp etc A self scheduling star is derived from class DERepeat Star which in turn is derived from class DEStar The DERepeat Star class has two special methods to facilitate the self scheduling function refireAtTime and canGetFired These are summarized in table 12 2 The Poisson star illustrates these defstar name Poisson domain DE derivedfrom RepeatStar desc Generates events according to a Poisson process The first event comes out at time zero output name output type float defstate name meanTime type float default 1 0 desc The mean inter arrival time defstate name magnitude type float default 1 0 desc The value of outputs generated hinclude lt NegExp h gt ccinclude lt ACG h gt protected NegativeExpntl random declare the static random number generator in the cc file DERepeatStar class description int canGetFired return if the star is enabl
91. a star in phase mode does not access all simultaneous input events in a particular firing the unaccessed events are discarded The method numSimulEvent returns the current queue size in phase mode Recall that in simple mode the method returns the number of simultaneous events in the global event queue which is one less than the actual number of simultaneous events This difference of one between two modes is necessary for coding efficiency There is still inherent non determinism in the handling of simultaneous events in the U C Berkeley Department of EECS The Almagest 12 13 DE domain For example suppose that the Switch star has more than one simultaneous con trol event Which one is really the last one Since the input is routed to either the true or false output depending on the last value of the cont rol event the decision is quite critical We leave the responsibility of resolving such inherent non determinism to the user 12 4 Programming Examples This section presents different examples of programming in the discrete event domain There are no pre defined stars that work with matrices in the discrete event domain We will give several examples of DE stars that work with matrices 12 4 1 Identity Matrix Star This section develops a star in the DE domain that will create an identity matrix Instead of creating a source star which must schedule itself we will create a star that fires whenever it receives an new input va
92. air of curly braces is stripped The syntax is code body header This keyword allows the user to specify an arbitrary set of definitions that will appear in the header file Everything between the curly braces is inserted into the h file after the include files but before everything else This can be used for example to define classes used by your star The outermost pair of curly braces is stripped method Ptolemy The method item provides a fully general way to specify an additional method for the class of star that is being defined Here is an example virtual method name exec access protected arglist const char extraOpts type void code code for the exec method goes here An optional function type specification may appear before the method keyword which must be one of the following Last updated 8 26 97 2 16 Writing Stars for Simulation virtual inline pure pure virtual inline virtual The virtual keyword makes a virtual member function If the pure virtual key word is given a pure virtual member function is declared there must be no code item in this case The function type pure is a synonym for pure virtual The inline function type declares the function to be inline Here are the method subitems name The name of the method This is a required item access The level of access for the method one of public protected or private If the item is omitted prote
93. ally are concatenated to this stream unless another stream is supplied as an argument Code generation Once the program graph is scheduled the target generates the code in the virtual method generateCode Note code streams should be initialized before this method is called All the methods called by generateCode are virtual thus allowing for target cus tomization The generat eCode method then calls allocateMemory which allocates the target resources After resources are allocated the initCode method of the stars are called by codeGenInit The next step is to form the main loop by calling the method main LoopCode The number of iteration cycles are determined by the argument of the run directive which a user specifies in pigi or in ptcl To complete the body of the main loop go methods of stars are called in the scheduled order After forming the main loop the wrapup methods of stars are called Now all of the code has been generated however the code can be in multiple target streams The frameCode method is then called to piece the code streams together and place the unified stream into the myCode stream Finally the code is written to a file by the method writeCode The default file name is code output and that file will be located in the directory specified by a target parameter destDirectory Finally since all of the code has been generated for a target we are ready to compile load and exe
94. an only be used to create a brand new parallel tree e MAKEARCH may fail when used with a tree that was created with mkPtolemyTree since MAKEARCH may follow symbolic links into the master tree where the user does not have write permission e mkPtolemyTree requires that the master Ptolemy tree have a fully expanded obj PTARCH directory Otherwise you will get an error about no sources rule found 1 5 Using csh aliases to create a Parallel Software Development Tree Below is a set of C shell aliases that can be used to create a parallel software develop ment tree 1 5 1 Aliases for Managing Symbolic Links Below are several csh aliases that can be helpful when managing a duplicate hierar chy that is implemented with symbolic links alias pt echo Scwd sed s HOME Ptolemy PTOLEMY alias ptl 1n s pt alias sw mv NI swap mv NI mv swap alias exp mkdir sw NI cd NI ptl alias rml rm f Vls F sed n s N S p alias mkl rml make ln s vpath make These are documented below in detail For convenience these aliases can be found in the file SPTOLEMY alias The pt Alias The pt alias returns the name of the official Ptolemy directory that corresponds to U C Berkeley Department of EECS The Almagest 1 13 the current directory which is presumably in your personal hierarchy This assumes that you have the e
95. ands to an inline definition of the function for exam ple ISA_INLINE IntVecData Message could have been written above instead of the definition of isA to generate exactly the same code Alternatively to put the function body in a cc file one can write int isA const char const in the class definition and put ISA_FUNC IntVecData Message in the cc file or wherever the methods are defined The class must define a copy constructor unless the default copy constructor generated by the compiler which does memberwise copying will do the job The class must redefine the clone method of class Message Given that the copy constructor is defined the form shown in the example where a new object is created with the new operator and the copy constructor will suffice In addition the user may optionally define type conversion and printing functions if they make sense If a star that produces messages is connected to a star that expects integers or floating values or complex values the appropriate type conversion function is called The base class Message defines the virtual conversion functions asInt asFloat and asComplex and the printing method print see the file SPTOLEMY src kernel Message h for their exact types The base class conversion functions assert a run time error and the default print function returns a StringList saying lt type gt no print metho
96. aneous events is the most challenging task of the DE scheduler In general simultaneous events are caused by insufficient time resolution particularly when the time unit is integral In our case simultaneous events are primarily caused by functional stars that produce output events with the same time stamp as the input events Since the time stamp is a double precision floating point number we have very high time resolution As explained earlier the DE scheduler fetches at most one event for each input port hole for each firing of a DE star In the body of the star code the programmer can consume the simultaneous events onto a certain input porthole by calling the get SimulEvent method for the porthole This mode of operation is called simple mode which is the default mode of oper ation Suppose we program a new DE star called Counter The Counter star has one clock input and one demand input A clock event will increase the counter value by one and the demand input will send the counter value to the output If there are multiple simulta neous clock inputs and a simultaneous demand input we should count all the clock inputs before consuming the demand input and producing an output Thus the programmer should call the getSimulEvent method for the clock input However the getSimulEvent method is expensive when there are many simultaneous events since it gets only one simulta Ptolemy Last updated 10 17 97 12 12 DE Domain ne
97. ar lookup const t char key lookup an entry with the given key return 0 if there is no such entry int remove const t char key remove the entry with the given key from the table and deallocated its memory int size TABLE 3 13 classes return the number of entries in the hash table A summary of the most useful methods of the HashTable and TextTab In some future version HashTable might be reimplemented using templates 3 8 Sharing Data Structures Across Multiple Stars It is sometimes desirable to have a set of stars that share and manipulate a common data structurel A simple way to accomplish this is to define a star that contains a static mem ber Suppose for example you wish to define a class of stars that create a shared list of point ers one to each instance of this type of star Thus every star of this type would be able to access every other star of this type Consider the following implementation defstar name Share domain SDF desc A star with a shared data structure hinclude DataStruct h private output static SequentialList starList name howmany type int code 1 See the SDFWriteVar and SDFReadVar stars for a similar implementation U C Berkeley Department of EECS The Almagest 3 15 SequentialList SDFShare starList begin starList append this go howmany 0 lt lt starList
98. at the top of the list because it was generated by invok ing a dynamically linked star and the symbol information is not complete However you can still find out quite a bit Notice that you are now told where the files are that define the meth ods being called The file names are all relative to the directory in which the corresponding object file normally resides The Ptolemy files can all be found in some subdirectory of SPTOLEMY src You can get help from gdb by typing help Suppose you wish to find out first which star is being run when the crash occurs The following sequence moves up in the stack until the run call of a star gdb up 1 Oxe3864 in SimControl getPollFlag at src kernel SimCon trol ce 271 U C Berkeley Department of EECS The Almagest 1 25 271 PEBlockSig SIGALRM gdb up 2 Oxe3e5c in Star run this 0x28c908 at src kernel Star cc 73 73 go gdb At this point you can see that line 73 of the file SPTOLEMY src kernel Star cc reads go Odds are pretty good that the problem is in the go method of the star You can find out to which star this method belongs as follows gdb p this 1 lt Block gt lt NamedObj gt nm 0x28ad58 BadStarl prnt 0x28c878 myDescriptor 0x28b658 Causes a core dump deliberately _vptr Oxeee91738 flags nElements 0 val 0x0 pTarget 0x28aa60 scp 0x0 ports lt NamedObjList gt lt Sequ
99. ate If there is no makefile pigi will run a make like proce dure on its own running the preprocessor as needed to produce the C source files then running the C compiler to create the object file By default the C compiler will be told to look for include files in the kernel directory and the domain specific kernel and star directories if this is not adequate then you need to write a makefile Once compilation if any is complete the dynamic linker is used to load the star into the system Compilation errors if any will appear in a popup window e Whenever the definition of a star is changed so that the new definition has differ ent I O ports the icon must be updated as well You can do this by calling make star again to replace the old icon with a new one If the linking fails one of the following situations may apply e Whoever installed Ptolemy did not install the compiler e The compiler is not configured correctly If you are using a prebuilt compiler obtained from the Ptolemy ftp site you may need to set some environment vari ables if your Ptolemy installation is not at users ptolemy See Appendix A of the Ptolemy User s Manual for more information e A spurious makefile exists in your directory If a makefile exists in your direc tory Ptolemy will attempt to use it to compile your star Remove it and try again U C Berkeley Department of EECS The Almagest 2 3 e The version of the compiler used to bui
100. ays give single appearance schedules If the file target parameter is set then a sum mary of internal scheduling steps will be written to that file Essentially two different heuris tics are used by the ACYLOOP scheduler called APGAN and RPMC and the better one of the two is selected The generated file will contain the schedule generated by each algorithm the resulting buffer memory requirement and a lower bound on the buffer memory require ment called BMLB over all possible single appearance schedules If the second third or fourth approach is taken the code size is drastically reduced when there are large sample rate changes in the application On the other hand we sacrifice some efficient buffer management schemes For example suppose that star A produces 5 sam ples to star B which consumes 1 sample at a time If we take the first approach we schedule this graph as ABBBBB and assign a buffer of size 5 between star A and B Since each invoca tion of star B knows the exact location in the allocated buffer from which to read its sample each B invocation can read the sample directly from the buffer If we choose the second third or fourth approach the scheduling result will be A5 B Since the body of star B is included inside a loop of factor 5 we have to use indirect addressing for star B to read a sample from the buffer Therefore we need an additional buffer pointer for star B memory overhead and one more level of memory ac
101. be writing stars since it explains some of the more generic and useful classes defined in the Ptolemy kernel Many of these are useful in stars C code segments are an important part of any star definition They can appear in the setup begin go wrapup constructor destructor exectime header code and method directives in the Ptolemy preprocessor These directives all include a body of arbi trary C code enclosed by curly braces and In all but the code and header direc tives the C code between braces defines the body of a method of the star class Methods can access any member of the class including portholes for input and output states and members defined with the public protected and private directives 2 4 1 The structure of a Ptolemy star In general the task of a Ptolemy star is to receive input particles and or produce output particles in addition there may be side effects reading or writing files displaying graphs or even updating shared data structures As for all C objects the constructor is called when the star is created and the destructor is called when it is destroyed In addition the set up and begin methods if any are called every time a new simulation run is started the go method which always exists except for stars like BlackHole and Nu11 that do nothing is called each time a star is executed and the wrapup method is called after the simulation run com pletes without errors
102. behavior of the object itself Each object has a private data field that is initialized by the con structor when there is an overflow the overflow_handler looks at this field and uses the U C Berkeley Department of EECS The Almagest 4 7 specified method to handle the overflow This data field is set to saturate by default and can be set explicitly to any other desired overflow handling method using a function called set_ovflow lt keyword gt The keywords for overflow handling methods are saturate default zero_saturate wrapped warning saturate replaces the original value is replaced by the maximum for overflow or minimum for underflow value representable given the precision of the Fix object zero_saturate sets the value to zero Explicitly casting inputs In the above example the first line of the go method assigned the input to the pro tected member sum which has the side effect of quantizing the input to the precision of sum We could have alternatively written the go method as follows go sum Fix input1 0 Fix input2 0 output 0 lt lt sum The behavior here is significantly different the inputs are added using their own native preci sion and only the result is quantized to the precision of sum Some stars allow the user to select between these two different behaviors with a parameter called ArrivingPrecision If set to YES the input particles are not explicitly cast they are used as they are if set
103. ber with unspecified precision and value zero Fix int length int intbits Create a Fix number with total word length of Length bits and int bits bits to the left of the binary point The value is set to zero If the precision parameters are not valid then an error bit is internally set so that the invalid method will return TRUE Fix const char precisionString Create a Fix number whose precision is determined by precision String which has the syntax leftbits rightbits where leftbits is the number of bits to the left of the binary point and rightbits is the number of bits to the right of the binary point or rightbits totalbits where totalbits is the total number of bits The value is set to zero If the pre cisionString is not in the proper format an error bit is internally set so that the invalid method will return TRUE Fix double value Create a Fix with the default precision of 24 total bits for the word length and set the number of integer bits to the minimum needed to rep resent the integer part of the number value If the value given needs more than 24 bits to represent the value will be clipped and the number stored will be the largest possible under the default precision i e satu ration occurs In this case an internal error bit is set so that the ovf occurred method will return TRUE Fix int length int intbits double value Create a Fix with the specified precision and set its value to the gi
104. bolic links 1 3 1 Creating a pigiRpc that includes your own stars For those who just want to statically link in their own stars with minimal hacking with makefiles an example showing how to do this is provided in SPTOLEMY src pigiExam ple In the example below we assume that SPTOLEMY and SPTARCH are set and that you have write permission to the Ptolemy source tree If you don t have write permission you can set up a parallel tree with the Unix 1n s command If for example the Ptolemy tree was at users ptolemy but you wanted to build under pt you could do the following to create the directory and create symbolic links for the dot files like cshrc and create symbolic links for the other files and directories in the distribution mkdir pt cd pt In s users ptolemy ln s users ptolemy setenv PTOLEMY pt setenv PTARCH SPTOLEMY bin ptarch rm obj SPTARCH src bin PTARCH mkdir p src src pigiExample bin SPTARCH cd bin SPTARCH ln s users ptolemy bin SPTARCH cd src ln s users ptolemy src cd pigiExample cp users ptolemy src pigiExample You also need to be sure that you have your environment set up properly for the com piler that you are using Continuing with our example of how to build a pigiRpc that includes your own stars 1 Build a basic pigiRpc PigiRpc depends on o files under SPTOLEMY obj PTARCH so you must do a basic build
105. ceive stars that are declared to support ANYTYPE but fail to support a par ticular datatype should display an appropriate error message using the Error abortRun method Finally each of these stars must call PortHole numXfer to determine the size of the block of data that needs to be transferred upon each invocation Spread Collect stars Consider a multi rate example in which star A produces two tokens and star B con sumes one token each time Suppose that the first invocation of star B is assigned to the same processor as the star A processor 1 but the second invocation is assigned to processor 2 After star A fires in processor 1 the first token produced should be routed to star B assigned to the same processor while the second token produced should be shipped to processor 2 inter processor communication is required Since star A has one output port and that port should be connected to two different destinations one is to star B the other is to a send star we insert a spread star after star A As a result the sub galaxy created for processor 1 contains 4 blocks star A is connected to a spread star which in turn has two outputs connected to star B and a send star The role of a spread star is to spread tokens from a single output port hole to multiple destinations On the other hand we may need to collect tokens from multiple sources to a single input porthole Suppose we reverse the connectio
106. cess runtime overhead for indirect addressing 13 4 2 Multiprocessor schedulers A key idea in Ptolemy is that there is no single scheduler that is expected to handle all situations Users can write schedulers and can use them in conjunction with schedulers we have written As with the rest of Ptolemy schedulers are written following object oriented design principles Thus a user would never have to write a scheduler from ground up and in fact the user is free to derive the new scheduler from even our most advanced schedulers We have designed a suite of specialized schedulers that can be mixed and matched for specific applications Ptolemy Last updated 10 17 97 13 22 Code Generation The first step in multiprocessor scheduling or parallel scheduling is to translate a given SDF graph to an acyclic precedence expanded graph APEG The APEG describes the dependency between invocations of blocks in the SDF graph during execution of one itera tion Refer to the SDF domain documentation for the meaning of one iteration Hence a block in a multirate SDF graph may correspond to several APEG nodes Parallel schedulers sched ule the APEG nodes onto processors We have implemented three scheduling techniques that map SDF graphs onto multi ple processors with various interconnection topologies Hu s level based list scheduling Sih s dynamic level scheduling Sih91 and Sih s declustering scheduling Sih91 The target architecture is des
107. ch CriticalSection and PtCondition refers to a PtGate communication channels of Kahn process networks The classes that implement the commu nication channels provide the synchronization necessary to enforce the blocking read seman tics of Kahn process networks The classes PtGate PosixMonitor and CriticalSection provide a mutual exclusion mechanism The classes Pt Condition and PosixCondition provide a synchronization mechanism The class PNGeodesic uses these classes to implement a communication channel that enforces the blocking read operations of Kahn process networks and the blocking write operations required for bounded scheduling The abstract base class PtGate defines the interface for mutual exclusion objects in Ptolemy The class PosixMonitor provides an implementation of PtGate based on the POSIX thread standard Other implementations are possible The class PNMonitor is a typedef that determines which implementation is used in the PN domain Changing the underlying implementation simply requires changing this typedef The abstract base class PtCondition defines the interface for condition variables in Ptolemy The class PosixCondition provides an implementation based on the POSIX thread standard Other implementations are possible The class PNCondition is a typedef that determines which implementation is used in the PN domain Changing the underlying implementation simply requires changing this typedef The class CriticalSection p
108. ch have been added using the CGCStar addLinkOption method 14 3 Buffer Embedding Although many of the methods related to buffer embedding are actually implemented in the CG domain only the CGC domain makes use of them at this time The following func U C Berkeley Department of EECS The Almagest 14 3 tion is defined as a method of the CGPortHole class void embed CGPortHole port int location 1 Embed the buffer of port in the buffer of this porthole with offset location The default location of 1 indicates that the offset is not yet determined For example the following statements appear in the setup method of the Switch block This causes the buffers of t rueOut put and falseOutput to be embedded within the buffer of input input embed trueOutput 0 input embed falseOutput 0 14 4 Command line Settable States In the Ptolemy releases before Ptolemy0 6 the C programs generated by Ptolemy in the CGC domain did not take any command line arguments The state values of the various stars were set during compilation and thus hard coded into the program In order to change a state variable the code had to be recompiled again i e the universe had to be re run within Ptolemy This was time consuming and it also placed unnecessary load on the machine In Ptolemy0 6 and later the CGC domain can generate C code that allow users to set the state values from the command line which allows runs with different parameter
109. code generation ee ese ee ee ee ee ee ee 13 16 target multiPTOCESSOL eeuse ee ee ee ee ee ee ee 13 18 TARGETS dons AE ME ME 1 1 Tel TK EE EE EE ER EE EE 1 1 TclScript DE block ee ee ee ee ee ee ee ee 5 12 TelScript stars ER RE ER De EE OG De Ee 5 1 Telstar lfc Clis Srann n 5 12 tempFileName funcCHON e ee ees ee ee ee ee 3 8 TextTable class e ese see ee ee ee ee RR Re Re Ge ee 3 13 TextTablelter Class use sesse see ee eek ee ee Se ee 3 13 time stamp ees ee ee oe ek ee eke ee ee Re ee ee ee 12 1 TE SS SG alt 3 4 ENDLER Mad EE 14 7 tkSetup CGCTeITkTarget esse ese se ee 14 7 TkShow Values se se see ee ee ee ee Re ee ee Gee ee 5 2 triggers method ese se se ees see ee RR Re ee Se De 12 5 HOL EG ED Ee rd ee ee 2 4 truncation Eie CASS se EG EE N TE GE 4 4 two s complement ccccssesessesesesteteesteeeeesesesteees 4 4 Tycho Target sesse se se se ese see ee ERA ee Re se ee 14 8 tylndir scripteanna ee ee ee 1 11 type CONVELSION Luus see ee ee ee ee ee ee ee ee ee ee 2 21 Message TOE 4 16 type C50 state se see ee se ee ee RR Re Re Ge ee 16 1 type CG56 CG96 state ee ee ee 15 1 TYPE CHECK macro iese see se ese ee se se ee ee 4 17 typeCheck method Envelope Cla ese ee ee ee ee ee ee ee reese 4 17 typeError method Envelope Cla ese ee ee ee ee ee ee ee reese 4 17 U C Berkeley TYPES icc el OE tea OE ORE 2 11 AE EO 1 5 U underflow it di EE EE EN N NE 4 4 Uniform Class SE Oe go 3 1
110. cribed by its Target object derived from CGMultiTarget The Target class provides the scheduler with the necessary information on interprocessor communication to enable both scheduling and code synthesis The CGMultiTarget has a parameter schedName that allows the user to select the type of schedule Currently there are five different scheduling options DL If schedName is set to DL we select the Sih s dynamic level scheduler that accounts for IPC overhead during scheduling HU Hu s level scheduler is selected which ignores the IPC over head DC The Sih s declustering scheduler can be selected by setting DC The declustering algorithm is advantageous only when the list scheduling algorithm shows poor performance judged from the scheduling result because it is more expensive than the DL or HU scheduler HIER DL or HIER HU or HIER DC If we want to use Pino s hierarchical scheduler we have to set schedName to HIER DL or HU or DC The default top level scheduling option is the DL scheduler To use other scheduler DC or HU should be specified within the parenthesis CGDDF If the schedName is set to CGDDF the Ha s dynamic construct scheduler is selected To use this scheduler Ptolemy should be recompiled with special flags or use mkcgddf executable Whichever scheduler is used we schedule communication nodes in the generated code For example if we use the Hu s level based list sch
111. cript in the form of a glo bal Tcl variable st ar ID The procedure used by the Tcl script to set output values is called setOutputs_ starID This procedure takes as many arguments as there are output ports The argument list should contain a floating point value for each output of the star In the above example Tcl code is executed when the Tcl script is sourced This occurs during the setup phase of the execution of the star After the setup phase no Tcl code will be executed unless the user pushes the PUSH ME button The command bind s lt ButtonPress 1 gt setOutputs_S starID 1 0 defines a Tcl command to be executed asynchronously Notice that the command is enclosed in quotation marks not braces Tcl aficionados will recognize that this is necessary to ensure that the starID variable is evaluated when the command binding occurs when the script is sourced rather than when the command is executed There is no guarantee that the variable will be set when the command is executed In the above example no Tcl code is executed when the star fires The following example shows how to define Tcl code to be executed each time the star fires and also how to read the inputs of the star from Tcl Example 2 Consider the following schematic in the SDF domain A Ramp Suppose we specify the following Tcl script for the Tc1Script star TclScript ra Fi de j
112. cted is assumed arglist The argument list including the outermost parentheses for the method as a quoted string If this is omitted the method has no arguments type The return type of the method If the return type is not a single identi fier you must put quotes around it If this is omitted the return type is void no value is returned code The code that implements the method This is a required item unless the pure keyword appears in which case this item cannot appear exectime This item defines the optional myExecTime function which is used in code generation to specify how many time units are required to execute the star s code The syntax is exectime body The optional keyword inline may appear before the exectime keyword The body defines the body of a function that returns an integer value codeblock Codeblocks are parametrized blocks of code for use in code generation stars Their use and format is discussed in detail in the code generation chapters The syntax is codeblock code 2 4 Writing C code for stars This section assumes a knowledge of the C language no attempt will be made to U C Berkeley Department of EECS The Almagest 2 17 teach the language We recommend C Primer Second Edition by Stanley Lippman from Addison Wesley for those new to the language Chapter 3 Infrastructure for Star Writers is also highly recommended reading for those who will
113. ctions in addition the ComplexMat rix class has a few spe cial methods such as conjugate and hermitian and the FixMatrix class has a num ber of special constructors that allow the user to specify the precision of the entries in the matrix Generally all entries of a FixMatrix will have the same precision The matrix classes were designed to take full advantage of operator overloading in C so that operations on matrix objects can be written much like operations on scalar ones For example the two operand multiply operator has been defined so that if A and B are matrices A B will return a third matrix that is the matrix product of A and B 4 4 3 Public functions and operators for the PtMatrix class The functions and operators listed below are implemented by all matrix classes Com plexMatrix FixMatrix FloatMatrix and IntMatrix unless otherwise noted The symbols used are e Xxx refers to one of the following Complex Fix Float or Int e xxx refers to one of the following Complex Fix double or int Functions and Operators to access entries of the Matrix xxx amp entry int i Example A entry i Return the i entry of the matrix when its data storage is considered to be a linear array This is useful for quick operations on every entry of the matrix without regard for the specific row column position of that entry The total number of entries in the matrix is defined to be numRows nu
114. cute the code Derived targets should redefine the virtual methods compile Code loadCode and runCode to do these operations At times it does not make sense to have separate LoadCode and runCode methods and in these cases these oper ations should be collapsed into the runCode method 13 3 3 Multiprocessor targets Targets representing multiple processors are derived from the CGTarget class The base class for all multiple processor targets is called MultiTarget and resides in the PTOLEMY src domains cg kernel directory CGMultiTarget is derived from MultiTarget CGMultiTarget class is the base class for all multiple processor targets It is called FullyConnected in the CG domain target list The design of Ptolemy is also intended to support heterogeneous multi processor tar gets In the future the base class of all abstract heterogeneous multiprocessor targets will be implemented from the MultiTarget class For such targets certain actors must be assigned to certain targets and the cost of a given actor is in general a function of which child target it is assigned to We have developed parallel schedulers that address this problem Sih91 We have implemented or are in the process of implementing both abstract and concrete multi processor targets For example we have classes named CGMultiTarget U C Berkeley Department of EECS The Almagest 13 19 and CGSharedBus that represent sets of
115. d U C Berkeley Department of EECS The Almagest 4 17 where type is whatever is returned by dataType By redefining these methods you can make it legal to connect a star that generates messages to a star that expects integer floating or complex particles or you can connect to a Printer or XMgraph Star for XMgraph to work you must define the asFloat function for Printer to work you must define the print method 4 3 2 Use of the Envelope class The Envelope class references objects of class Message or derived classes Once a message object is placed into an envelope object the envelope takes over responsibility for managing its memory maintaining reference counts and deleting the message when it is no longer needed The constructor which takes as its argument a reference to a Message copy con structor assignment operator and destructor of Envelope manipulate the reference counts of the references Message object Assignment simply copies a pointer and increments the refer ence count When the destructor of a Envelope is called the reference count of the Message object is decremented if it becomes zero the Message object is deleted Because of this dele tion a Message must never be put inside a Envelope unless it was created with the new operator Once a Message object is put into an Envelope it must never be explicitly deleted it will live as long as there is at least one Envelope that contains it and it w
116. d attr setstacksize amp attributes 0x8000 Create a thread pthread create amp thread amp attributes thread func t runThis this Discard temporary attribute object pthread attr destroy amp attributes The runA11 method which is shown below allows all threads to run by lowering the priority of the main thread If execution of the threads ever stops control returns to the main thread and its priority is raised again to prevent other threads from continuing Start or continue the running of all threads void PosixThread runAll1 Lower the priority to let other threads run When control returns restore the priority of this thread to prevent others from running pthread_attr_t attributes pthread_attr_init amp attributes pthread_getschedattr mainThread amp attributes pthread_attr_setprio amp attributes minPriority pthread_setschedattr mainThread attributes pthread_attr_setprio amp attributes maxPriority pthread_setschedattr mainThread attributes pthread_attr_destroy amp attributes The terminate method shown below causes the thread to terminate before deleting the PosixThread object First it requests that the thread associated with the PosixThread object terminate using the pthread cancel function Then the current thread is suspended by pthread_join to give the cancelled thread an opportunity to terminate O
117. d by ordinary assignment in C as in the following lines U C Berkeley Department of EECS The Almagest 2 23 double t expression mystate t This works because the Float State class definition has overloaded the assignment operator to set its value from a double Similarly an IntState can be set from an int anda StringState can be set from a char or const char 2 4 4 Array States The ArrayState classes FloatArrayState IntArrayState and ComplexAr rayState are used to store arrays of data For example state name taps type FloatArray default 0 0 0 0 0 0 0 0 descriptor An array of length four defines an array of type double with dimension four with each element initialized to zero Quotes must surround the initial values Alternatively you can specify a file name with a pre fix lt If you have a file named foo that contains the default values for an array state you can write default lt foo If you expect others to be able to use your star however you should specify the default file name using a full path For instance default lt user_name directory foo For default files installed in the Ptolemy directory tree this should read default lt SPTOLEMY directory foo The format of the file is also a sequence of data separated by spaces or newlines tabs or commas File input can be combined with direct data input as in default d
118. d name scoping hierarchy Recall that when we initialize a Galaxy for clustering we flatten the original user specified hierarchy Before this action we extract the important information in the hierarchy using the Scope class In this section we detail this class The details in this section however are not necessary to understand clustering in Ptolemy Blocks inherit states from their parent The Scope class makes it possible for a Tar get or Scheduler to change the Block hierarchy by saving the inherited states in the user specified hierarchy The scoping hierarchy was first released in Ptolemy 0 6 and is only cre ated when the static method Scope createScope Galaxy amp is invoked Currently the only code that uses the scoping hierarchy is the Cluster class The Scope class manages its memory Once a Scope is created it will not be deleted until all Blocks within the given Scope are deleted The Scope class is privately derived from Galaxy To turn on scoping a programmer simply calls the static method static Scope Scope createScope Galaxy This method constructs a parallel tree corresponding to each Galaxy and copies the StateList and name for each level 6 6 Resetting an InterpUniverse back to actionList Ptolemy 0 6 and later includes the ability to reset an InterpUniverse back to the original user specification Resetting is occasionally necessary to undo certain operations done on a universe by
119. d to modify or work on them Your new code should be placed in the parallel directory with the other similar Ptolemy subdirectories using the same directory structure This way you can reuse the makefiles of similar Ptolemy directories with minimal modifications After you create your own Ptolemy tree and add your new directories and files certain Ptolemy makefiles typically SPTOLEMY mk ptbin mk and SPTOLEMY mk stars mk need to be modified to include your own code Building your own pigiRpc ptcl or tysh this way requires extensive knowledge of the Ptolemy directory tree structure and makefiles but if you are doing serious development in Ptolemy you will need to know this anyway Warning If you have write permission in the directory where Ptolemy is installed make sure to modify the place where make install puts the completed executable or it will attempt to overwrite the pigiRpc in the Ptolemy installation and other users may be upset with you if you succeed in doing that If you are using the makefile from PTOLEMY src pigiExam ple you do not need to worry about this because make install has been removed from that makefile The simplest thing to do is to replace the line in the makefile install makefile DESTBIN with install makefile pigiRpc This will leave the pigiRpc in whatever directory you make it even if you type make install 1 4 Using mkPtolemyTree to creat
120. data comes in the U C Berkeley Department of EECS The Almagest 12 15 form of an envelope which is essentially an instance of a class embedded in a message parti cle To extract the contents of the message we first extract the message from the input enve lope Then we extract the data field from the message and cast it to be a FloatMatrix Just as in the previous example we need to allocate dynamic memory to hold the value of the matrix to be output In this case we do not have to code the transpose operation since it is already built into the matrix classes Ptolemy Last updated 10 17 97 12 16 DE Domain U C Berkeley Department of EECS The Almagest 13 1 Chapter 13 Code Generation Authors Joseph Buck Soonhoi Ha Edward A Lee Praveen K Murthy Thomas M Parks Jos Luis Pino Kennard White 13 1 Introduction The CG domain and derivative domains are used to generate code rather than to run simulations Pin92 Only the derivative domains are of practical use for generating code The stars in the CG domain can be thought of as comment generators they are useful for testing and debugging schedulers and for little else The CG domain is intended as a model and a col lection of base classes for derivative domains This section documents the common features and general structure of all code generation domains The CG domain is currently based on dataflow semantics Dataflow models of compu tation in Ptolemy inclu
121. ddF ix star configured for two inputs defstar name AddFix domain SDF derivedFrom SDFFix input name inputl type fix input name input2 type fix output name output type fix defstate name OutputPrecision type precision default 2 14 desc Precision of the output in bits and precision of the accumulation When the value of the accumulation extends outside of the precision the OverflowHandler will be called Note that the real AddFix star supports any number of inputs By default the precision used by this star during the addition will have 2 bits to the left of the binary point and 14 bits to the Ptolemy Last updated 10 10 97 4 6 Data Types right Not shown here is the state OverflowHandler which is inherited from the SDFFix star and which defaults to saturat e that is if the addition overflows then the result satu rates pegging it to either the largest positive or negative number representable The result value sum is initialized by the following code protected Fix sum begin SDFFix begin sum Fix const char OutputPrecision if sum invalid Error abortRun this Invalid OutputPrecision sum set_ovflow const char OverflowHandler if sum invalid Error abortRun this Invalid OverflowHandler The begin method checks the specified precision and overflow handler for correctness T
122. dded that handle ANYTYPE work with message particles without change e Message portholes can send different types of messages during the same simulation This is especially useful for modeling communication networks e It avoids copying large messages by using a reference count mechanism as in many C classes for example string classes e It is possible to safely modify large messages without excessive memory allocation and deallocation e It is relatively easy for users to define their own message types no change to the ker nel is required to support new message types The message type is understood by Ptolemy to mean a particle containing a message There are three classes that implement the support for message types e The Message class is the base class from which all other message data types are derived A user who wishes to define an application specific message type derives a new class from Message e The Envelope class contains a pointer to an derived from Message When an Enve lope objects is copied or duplicated the new envelope simply sets its own pointer to U C Berkeley Department of EECS The Almagest 4 15 the pointer contained in the original Several envelopes can thus reference the same Message object Each Message object contains a reference count which tracks how many Envelope objects reference it when the last reference is removed the Mes sage is deleted The MessageParticle cla
123. ddle The middle panel in the control panel that is intended for user defined entries SptkControlPanel low The lowest panel in the control panel that is intended for user defined entries In addition to these global variables a number of procedures have been supplied Using these procedures can ensure a consistent look and feel across a variety of Ptolemy applications The complete set of procedures can be found in PTOLEMY 1ib tcl We list a few of the more useful ones here Note also that the entire set of commands defined in the Tcl based textual interpreter for Ptolemy ptc1 are also available So for example the command curuniverse will return the name of the current universe See the ptcl chapter in the User s Manual ptkExpandEnvVar Procedure to expand a string that begins with an environment variable reference For example ptkExpandEnvVar SPTOLEMY Src will return something like usr users ptolemy src Arguments path the string to expand ptkImportantMessage Procedure to pop up a message window and grab the focus The process is suspended until the message is dismissed Arguments win window name to use for the message text text to display in the pop up win dow ptkMakeButton Procedure to make a pushbutton in a window A callback proce dure must be defined by the programmer It will be called whenever the user pushes the button and takes no arguments Arguments win name of window to
124. de synchronous dataflow SDF dynamic dataflow DDF and bool ean dataflow BDF Both DDF and BDF are very general models of dataflow in that they are Turing equivalent SDF is a subset of both these models Hence a code generation target that uses the BDF scheduler can support BDF and SDF stars but a target that uses SDF schedulers only supports SDF stars Most targets in code generation domains use SDF schedulers and parallel schedulers which makes these targets support only SDF stars An advantage of SDF is that compilation can be done statically this permits very efficient code generation While we have implemented targets that allow DDF code generation stars in the system these targets are not in the current release However there are a couple of targets that use the BDF sched uler refer to the BDF domain documentation the section on the bdf cg target in the CG domain documentation in the user s manual and the section on the bdf cgc target in the CGC domain documentation for more information on BDF semantics and the types of stars that can be supported In this chapter we assume that stars obey only SDF semantics since code gener ation for non SDF models is still in its early stages The design goal of the code generation class hierarchy is to save work and to make the system more maintainable Most of the work required to allocate memory for buffers con stants tables and to generate symbols that are required in code is completely pr
125. designed by John Ousterhout while at UC Berkeley Tk is an associated X window toolkit Both have been integrated into Ptolemy Parts of the graphical user interface and all of the textual interpreter pt cl are designed using them Several of the stars in the standard star library also use Tcl Tk This chapter explains how to use the most basic of these stars TclScript as well how to design such stars from scratch It is possible to define very sophisticated totally customized user interfaces using this mechanism In this chapter we assume the reader is familiar with the Tcl language Documentation is provided along with the Ptolemy distribution in the SPTOLEMY tcltk itcl man direc tory in Unix man page format HTML format documentation is available from the other src tar file in SPTOLEMY src tcltk Up to date documentation and software releases are available by on the SunScript web page at http www sunscript com There is also a newsgroup called comp lang tcl This news group accumulates a list of frequently asked questions about Tcl which is available http www teraform com 7Elvirden tcl faq The principal use of Tcl Tk in Ptolemy is to customize the user interface Stars can be created that interact with the user in specialized ways by creating customized displays or by soliciting graphical inputs 5 2 Writing Tcl Tk scripts for the TclScript star Several of the domains in Ptolemy have a star called TclScript This star p
126. directory in the official Ptolemy tree Using the F option of the 1s com mand makes it easy to see which files in a directory are symbolic links they are marked with a trailing sign The sw Alias When experimenting with Ptolemy you may want to switch back and forth between using the official version of some directory and your own version You can keep two versions of the same directory or a file The sw alias swaps a file or directory filename with another file or directory filename The period at the beginning of the second file name makes it invisible unless you use the a option of the 1s command For example suppose you wish to experiment with making a change to just one file DDFRepeater pl in the directory above to fix a bug and then send the bug fix back to the Ptolemy group Ptolemy Last updated 10 10 97 1 14 Extending Ptolemy Introduction o pwd users me Ptolemy src domains ddf stars sw DDFRepeater pl mv cannot access DDFRepeater pl ls a ad DDFEndCase h DDFThresh cc sash DDFEndCase pl DDFThresh h DDFRepeater pl DDFLastOfN cc DDFThresh pl DDFCase cc DDFLastOfN h SCCS DDFCase h DDFLastOfN pl TAGS DDFCase pl DDFRepeater cc ddfstars c DDFDownCounter cc DDFRepeater h ddfstars mk DDFDownCounter h DDFSelf cc make template DDFDownCounter pl DDFSelf h makefile DDFEndCase cc DDFSelf pl Notice that DDFRepeater pl was moved to DDFRepeater
127. e SPTOLEMY bin mkPtolemyTree is a tclsh script that creates a new parallel Ptolemy tree Note that mkPtolemyTree cannot be run in an already existing Ptolemy devel opment tree The file SPTOLEMY mk stars mk controls what directories mkPtolemyTree creates you need not actually edit the mkPtolemyTree script To create pigiRpc binaries with your new domain in it you will need to modify stars mk so adding support for mkP tolemyTree is fairly trivial PTOLEMY mk stars mk Follow the style for domain addition that you see in this file for the other domains A few things to keep in mind Ptolemy You should list the new domain before any other domain library that the new domain depends on You should make sure to define the make variables to pull in other domain libraries as necessary You may need MDSDF 1 definition for example mkPtolemyTree uses the CUSTOM_DIRS makefile variable to determine what direc tories to create so be sure to add your directories here Continuing with our example of adding the yyy domain 5 Edit SPTOLEMY mk stars mk and add your entry YYYDIR CROOT src domains cg56 ifdef YYY CUSTOM_DIRS YYYDIR kernel YYYDIR stars Have to create this eventually PALETTES PTOLEMY src domains yyy icons main pal STARS LIBDIR yyystars o LIBS lyyystars lyyy LIBFILES LIBDIR libyyystars LIBSUFFIX LIBDIR libyyy LIBSUFFIX endif Last updat
128. e InterpUniverse Currently the user specifications are in the form of ptcl or oct facets In the future there will probably be also a Tycho specification format An InterpUniverse captures the user hierarchy in the form of a directed graph of WormHoles Galaxies and Stars The InterpUniverse is derived from Galaxy and contains the top level user specification in its BlockList Every other level of the user specified hierarchy is represented by either a Wormhole or Galaxy embedded inside of its parent Galaxy All Blocks have a parent Block pointer The parent of a Block is the Galaxy or WormHole in which the Block is embedded The InterpUniverse which is the top level Galaxy user specification has its parent pointer set to NULL 6 3 Galaxies and their relationship to Adjacency Lists To define graph algorithms adjacency lists and adjacency matrices are commonly used to represent a directed graph Cor90 An adjacency matrix is a square matrix where 6 2 Using the Cluster Class for Scheduling there is one column i and one row j for each node i the graph An element i j in this matrix is either 1 if there is an arc from i to j or 0 if no arc exists The second representation is an adjacency list in which each node has a list containing the nodes to which it is connected Thus an adjacency list is better suited for sparse graphs whereas adjacency matrices are well suited for dense graphs Blocks wi
129. e Sproc Mur93 Silage Kal93 DSP56000 assembly code CG56 and DSP96000 assembly code CG96 Each code generation domain has a default target which defines routines generic to the target language A derived Target that defines architec ture specific routines can then be written A given language particularly a generic language such as C may run on many target architectures Code generation functions are cleanly divided between the default domain target and the architecture specific target All target architectures are derived from the base class Target The special class KnownTarget is used to add targets to the known list of targets much as KnownBlock is used to add stars and other blocks to the known block list and to assign names to them A Target object has methods for generating a schedule compiling the code and run ning the code which may involve downloading code to target hardware and beginning its execution There also may be child targets for representing multiprocessor targets together with methods for scheduling the communication between them Targets also have parameters that are user specified 13 3 1 Single processor target The base target for all code generation domains is the CGTarget which represents a single processor by default This target is called default CG in the target list for the CG domain As the generic code generation target the CGTarget class defines many common functions for code generation ta
130. e char desc char initValue Tcl CmdProc callback This function creates an entry box in a window The name of the entry box must be unique e g derived from the star name The description of the entry box is desc The initial value in the entry box is initValue A callback function is called whenever the user enters a RET in the box The argument to the callback function will be the value that the user has put in the entry box The return value of the callback func tion should be TCL_OK void makeButton char window char name char desc Tcl Cmd Proc callback This function creates a push button in a window The name of the push button must be unique e g derived from the star name The description of the push button is desc A callback function is called whenever the user pushes the button The return value of the callback function should be TCL_OK void makeScale char window char name char desc int posi tion Tcl CmdProc callback This function creates a scale with slider in a window The name of the scale must be unique e g derived from the star name The description of the push button is desc The initial position of the slider must be between 0 and 100 A callback function is called whenever the user moves the slider in the scale The argument to the callback function will be the current position of the slider which can range from 0 to 100 The return value of the callback function should be TCL_OK
131. e then you would be well advised to look at a few examples contained in the directory PTOLEMY src domains sdf stars The directory PTOLEMY mk contains master makefiles that are included by other makefiles The makefile include directive does this for us SPTOLEMY mk config SPTARCH mk refers to the makefile for the architecture SPTARCH For instance SPTOLEMY mk config sun4 mk is the makefile that contains the sun4 specific details bin platform independent executables bin SPTARCH platform dependent executables demo top level demo directory with pointers to demos in src doc documentation including this manual in PostScript lib platform independent run time libraries SPTOLEMY lib SPTARCH platform dependent libraries used for linking mk shared portions of makefiles obj SPTARCH object files this appears when Ptolemy is recompiled octtools a subset of the Berkeley octtools used by pigi sre root of the source tree includes all demos and icons tcltk the installation of Tcl and Tk used by pigi tycho the Ptolemy syntax manager FIGURE 1 1 Structure of the home directory of the Ptolemy installation PTOLEMY Ptolemy Last updated 10 10 97 When you cd to SPTOLI checks to see if the directory SPTOLI Extending Ptolemy Introduction EMY and type make SPTOLEMY makefile contains a rule that EMY obj SPTARCH exists If this directory does not exist then make runs the command csh
132. e PN domain we experimented with implementations based on Sun s Light weight Process library AWESIME A Widely Extensible Simulation Environment by Dirk Grunwald Gru91 and Solaris threads Pow91 Eyk92 Kha92 Kle92a Kle92b Ste92 Sun94 The current implementation is based on a POSIX thread library by Frank Mueller Mue92 Mue93 Gie93 Mue95 This library which runs on several platforms is based on Draft 6 of the POSIX standard Parts of our implementation will need to be updated to be compliant with the final POSIX thread standard By choosing the POSIX standard we improve the portability of our code Sun and Hewlett Packard already include an implementation of POSIX threads in their operating sys tems Solaris 2 5 and HPUX 10 Having threads built into the kernel of the operating system as opposed to a user library implementation offers the opportunity for automatic paralleliza tion on multiprocessor workstations Thus the same program runs properly on uniprocessor workstations and multiprocessor workstations without needing to be recompiled This is important because it would be impractical to maintain different binary executables of Ptolemy for each workstation configuration U C Berkeley Department of EECS The Almagest 10 3 10 2 Processes Figure 10 1 shows the class derivation hierarchy for the classes that implement the PtThread f PosixThread PNThread DataFlowProcess SyncDataFlowProcess FIGURE 10 1 The cla
133. e TESE SS DE Gane ates 1 21 eo OE E ONE 2 28 3 3 creating a NeW SA ee ee ee ee ee ee ee ee ee 2 1 CUSTOM DIRS veeres ee se ee enpe inpre Ge Re 1 10 D data EY PES ee sk eoan ree Ee Ee 2 11 user defined i e enter die es A 14 dataNew lag ees ee se ee ee ee ee ee 12 5 12 12 dataNew flag in DE ee ee ee see ee ee ee ee ee eg 12 4 dataType method Envelope Class u ees ee ee ee ee 4 17 DC Scheduler u uses ses see ese oe Be ER ek See RR RE 13 22 DCTImage class iese se ee se ee ee ee RR ee ed 4 4 DDESITS iese hoe atid ne ee ER oe SS 8 1 DDFStar o E A 8 2 DE Writing StATS ees ees ee ee ee ee ee ee ee ee ee ee 12 1 DE ORE 5 RR SE ED DE 12 1 debugging ese ee ee RR RR RR 1 21 1 23 default parameter value ees see ee ee ee ee ee 2 10 default value for StateS e ees se see ee ee ee ee Re ee 2 9 delay DE dom GER GE Died 12 1 delay stars in DE domain ese ee ee ee ee 12 1 for matrix AICS eg 4 31 EIE ale anede EO ON 4 3 TE 3 ME EER ed Ge Ge ge 12 8 Delay DE block ue ese seer ee ee ee ee ee ee ee eg 12 1 DEPortHole claSS ese se see se se ee ee ee Re eee 12 5 DERepeatStar class ee ee se see ee ee ee Re ee 12 9 derived ptlang directive e esse ee ee ee ee ee 2 6 derivedfrom ptlang directive ees ees 2 6 2 7 desc ptlang directive ee se ee ee ee ee RR ee 2 6 descriptor EE a S E 2 10 descriptor ptlang directive ees see ee ees 2 6 2 7 DEStar E 12 9 destructor ptlang directive ee
134. e a custom Ptolemy trees In Ptolemy 0 6 and later there are two methods of building custom Ptolemy trees that have a user selected set of domains csh aliases and the mkPtolemyTree script This section discusses the mkPtolemyTree script see Using csh aliases to create a Parallel Software Development Tree on page 1 12 for an alternative method of creating a parallel tree In Ptolemy 0 6 and later the mkPtolemyTree script and a user supplied over ride mk file to create an entire custom object tree The tree will have copies of all Ptolemy directories on which the customized installation depends The script will also set up the override mk files needed to build custom pigiRpc tysh and ptcl binaries Since mkP tolemyTree runs very fast you may avoid having to recompile the entire Ptolemy tree which can take 3 hours on a fast workstation 1 4 1 mkPtolemyTree example The mkPtolemyt ree command usage is mkPtolemyTree override mk_file root_pathname_of_new_tree For example say that you wanted to build a tree that only has the VHDL domain in mypt 1 One would create a file called override mk that contains VHDL 1 DEFAULT _DOMAIN VHDL Ptolemy Last updated 10 10 97 Extending Ptolemy Introduction ERSION_DESC VHDL only The file SPTOLEMY mk ptbin mk contains a list of the makefile variables that can be set to bring in the various domains 2 Set SPTOLEMY to point to the Ptolemy distribution in
135. e csh limit command to disable the creation of core files For further information see the csh man page U C Berkeley Department of EECS The Almagest 1 23 14 0x108358 in Target run 15 0x109e04 in Runnable run 16 Oxe62ec in InterpUniverse run 17 Oxee9e7f04 in PTcl run this 0x20af80 argc 2949528 argv 0x109fa4 at src ptcl PTcl ce 521 18 Oxee9e99a4 in PTcl dispatcher which 0x27 interp 0x1d4830 argc 2 The where command shows that state of the stack at the time of the crash The actual stack trace was 72 frames long the last two frames being 71 Oxeec06d5c in ptkMainLoop at src pigilib ptkTkSetup c 192 72 0x4982c in main Scanning this list we can recognize that the crash occurred during the execution of a star Unfortunately unless you are running a version of pigiRpc with the debug symbols loaded it will be difficult to tell much more from this 1 7 2 More extensive debugging To do more extensive debugging you need to create or find a version of pigiRpc with debug symbols called pigiRpc debug The first step is to build a pigiRpc that contains the domains you are interested in debugging There are several ways to build a pigiRpc a There may be prebuilt debug binaries on the Ptolemy Web site check the directory that contains the latest release b Rebuild the entire tree from scratch This takes about 3 hours Appendix A in the Ptolemy User s Manual has ins
136. e initialized to the cor responding arg_store members during the variable initialization stage By doing this a state will get its default value if it is not set on the command line 14 4 2 Changes in pigiRpc to support command line arguments The pragma mechanism in the Target base class is used to specify the state that is to be made settable via command line arguments as well as to store the name to be used on the command line In CGCtarget these are stored as a character string in a Text Table map pings a pointer to a HashTable in which the data value and index are character strings via the overloaded pragma member functions A function isCmdArg const State state is used to check whether state is to be set by a command line argument It calls CGCTarget pragma and scans through the StringList returned for the state s name If found the mapped name is return Other wise a null string is return Four new protected CodeStream are added to CGCTarget to store the additional codes cmdargStruct stores the struct members U C Berkeley Department of EECS The Almagest 14 5 cmdargStruct stores the default values setargFunc stores the code segment in set arg val setargFuncHelp stores the built up help message Four new public member functions and four private ones are also added to CGCStar to generate the codes cmdargStates calls cmdargState to generate the members of struct arg_store using
137. e oe ek ee ee ee ee ee 2 11 intarray type SEE N EE EA ES 2 9 IntArrayState ClaSS e ee se ee ee ee ee ee ee RR Re ee 2 21 IntMatrix see Matrix class IntParticle Cla ee ee ee ee ee ee ee ee ee ee 2 21 IntState Class ees ee ee ee ee ee ee ee Re ee ee ee 2 21 isA method Message class uie ee ee ee ee ee ee Re ee ee 4 16 TSA FUNC macro u e ceccesecescseseccescesceevescescseecvers 4 16 ISA INLINE macro iese se ee see se ee se ee ee ee 4 16 iterator classes cccssseseccscseseseseececseseseseececeeseees 3 10 ERT a AEE ON OE 3 10 3 13 K KRealavades Az NAI EIE EAEE E 4 1 key method HashEntry class ees ee see ee see ee ee ee ee 3 13 Khazeni Annea ee ee ee ee Ge ee ee ee A 1 L label codeblockSymbol sees ee ee ee 13 10 ane TEE EE GEE GE A 1 last in first out LIFO queue ee ee ee 3 11 LastOfN DDE block sccesrshciceassesh 8 1 Lee E A 1 1 2 1 3 1 4 1 7 1 12 1 13 1 14 1 libraries Of Stars eeuse ee ee ee ee ee ee ee ee ee 2 1 BUT os EE 14 1 Lippman Soeke RE N RES sb ed onse 2 17 Tistlter Clas Srani ie Res Gees GEE De ge oie 3 11 loadCode method ee ee ee ee 13 18 load star command ees eek ee ee ee ee ee ee ee 2 3 load star perm command ees ee ee ee ee ee 2 3 location ptlang directive ee ee ee ee ee 2 6 2 8 Ptolemy I 5 look inside command use ees se see ee ee ee ee ee 2 1 loop scheduler iese ee ee ee ee RR 13 21 loopingLevel target parameter ese 13 21
138. e processed first A chain of before directives can assign rela tive priorities to a whole set of inputs The other statement in the constructor control triggers has somewhat different objectives It tells the scheduler that a cont rol input does not trigger outputs on any porthole If an input event causes an output event with the same time stamp then the input event is said to have triggered the output event In the above example the cont rol event does not trigger any immediate output event but an input event does By default an input triggers all outputs so it is not necessary to add the directive input triggers output Providing triggers directives informs the scheduler that certain paths through the graph do not have zero delay allowing it to ignore those paths in making its topological sort The triggers directive is essentially a selective version of the delayType flag setting delayType means the star contains no zero delay paths whereas providing t riggers infor mation tells the scheduler that only certain porthole to porthole paths through the star have zero delay By default the scheduler assumes that all paths through the star have zero delay In some stars an input event conditionally triggers an output In principle if there is any chance of triggering an output we set the triggering relation between the input and the output The triggering relation informs the scheduler that there may be a delay free path fro
139. e same dimensions as the source matrix and the data values are copied from the source XXXMatrix const XXXMatrix amp src int startRow int startCol int numRow int numCol Example IntMatrix A B 2 2 3 3 This special submatrix constructor creates a new matrix whose val ues come from a submatrix of the source The arguments startRow and startCols specify the starting row and column of the source matrix The values numRow and numCo1 specify the dimensions of the new matrix The sum startRow numRow must not be greater than the maximum number of rows in the source matrix similarly start Col numCol must not be greater than the maximum number of col umns in the source For example if B is a matrix with dimension 4 4 then A B 1 1 2 2 would create a new matrix A that is a 2 2 matrix with data values from the center quadrant of matrix B so that A 0 0 B 1 1 A 0 1 B 1 2 A 1 0 B 2 1 and A 1 1 B 2 2 The following are special constructors for the FixMat rix class that allow the programmer to specify the precision of the entries of the FixMatrix FixMatrix int numRow int numCol int length int intBits Example FixMatrix A 2 2 14 4 Create a FixMatrix with the given dimensions such that each entry is a fixed point number with precision as given by the length and int Bits inputs FixMatrix int numRow int numCol int lengt
140. eam of random numbers the global variable gen a poor choice of name perhaps is a pointer to it We create an instance of the NegativeExpnt1 class in the setup method not in the constructor since Ptolemy allows you to change the seed of the random number generator When the user changes the seed of the random number generator the object pointed to by gen is deleted and re created so all objects such as the one pointed to by random in this star become invalid Ptolemy Last updated 8 26 97 3 18 Infrastructure for Star Writers Finally we can read a random number of the specific type by calling operator of the NegativeExpnl class This example uses a uniformly distributed random number hinclude lt Uniform h gt ccinclude 1 lt ACG h gt protected Uniform random declare th xtern random number generator in the cc file code extern ACG gen constructor destructor setup random NULL if random delete random if random delete random random new Uniform 0 double output numberPorts gen double p random You may notice that the two examples above are very similar in nature You can get another kind of distribution for the random numbers by including the appropriate library file in the n file and by creating the instance with the right parameters in the set up method U C Berkeley Department of EECS Chapter 4 Data Type
141. ecial PortHole called a MultiPortHole is used to make multiple connections but with only one terminal Two Blocks are not directly connected through their PortHoles Rather their PortHoles are connected to an intermediary object called a Geodesic In simulation domains data is passed between PortHoles through the Geodesic using container objects called Particles Ptolemy uses a system where Parti cles are used and recycled instead of created and deleted when needed Particles are obtained from a production and storage class called a Plasma which creates new Particles if there are no old ones to reuse Particles that have completed their task are returned to the 17 2 Creating New Domains Plasma Which may reissue them at a later reguest Graphically the Star to Star connection is depicted below Block Geodesic e initialize e initialize run e setSourcePort wrapup setDestPort Geodesic DEE PortHole PortHole PortHole Particle Particle initialize type receiveData print sendData e initialize e type FIGURE 17 1 Block objects in Ptolemy can send and receive data encapsulated in Particles through Portholes Buffering and transport is handled by the Geodesic and gar bage collection by the Plasma Some methods are shown The classes defined above provide most of the functionality necessary for a working domain One additional class needed by all domains is a Schedule
142. ect Overflow results either in saturation zero saturation replacing the result with zero or a warning error message depending on the overflow field of the object In these cases ovf_occurred will return TRUE on the result operator double arg Assignment operator The double value is first converted to a default precision Fix number and then assigned to this of these arithmetic operators should be self explanatory operator const Fix operator const Fix operator const Fix operator int operator const Fix amp operator const Fix amp const Fix operator const Fix amp const Fix operator const Fix amp const Fix operator const Fix int operator int const Fix operator const Fix amp const Fix operator const Fix amp unary minus operator const Fix a const Fix amp b operator const Fix amp a const Fix amp b operator gt const Fix a const Fix amp b operator lt const Fix amp a const Fix amp b operator gt const Fix amp a const Fix amp b U C Berkeley Department of EECS The Almagest 4 13 Note int operator lt const Fix amp a const Fix amp b These operators are designed so that overflow does not as a rule occur the return value has a wider format than that of its arguments The exception is when the result cannot be represented in a Fix with all 64 bits before the
143. ed 10 10 97 17 12 Creating New Domains PTOLEMY mk ptbin mk In SPTOLEMY mk ptbin mk add your domain to the FULL definition This causes your domain to be built in whenever a full pigiRpc binary is created Building 6 cd a pigiRpc To build a pigiRpc with your domain first build and install your domain s kernel and star libraries SPTOLEMY obj PTARCH domains yyy make depend make install If your domain depends on other domains you will have to build in those directo ries as well You may find it easier to do cd SPTOLEMY make install though this could take 3 hours An alternative would be to create a parallel directory tree using mkPtolemyTree 7 If you have not recompiled from scratch or run mkPtolemyTree you may also need to do cd SPTOLEMY obj PTARCH pigilib make ptkRegisterCmds o 8 Then build your pigiRpc You can either build a full pigiRpc with all of the domains or you can create a override mk in PTOLEMY obj PTARCH pigiRpc which will pull in only the domains you want SPTOLEMY obj PTARCH pigiRpc override mk could contain YYY 1 DEFAULT_DOMAIN YYY USERFLAGS VERSION_DESC YYY Domain Only To build your binary do cd SPTOLEMY obj SPTARCH pigiRpc make If you don t have all the libraries built you may get an error message make No rule to make target 1lib sol2 1ibcg56dspstars so needed by pigiRpc Stop cd 10 cd The
144. ed for firing void refireAtTime schedule the star to fire again at time t double t void begin schedule the star to fire at time zero TABLE 12 2 A summary of the methods of the DERepeat Star class used when writing a source star Source stars are derived from this Ptolemy Last updated 10 17 97 12 10 DE Domain code extern ACG gen constructor random NULL destructor if random delete random begin if random delete random random new NegativeExpnt1 double meanTime gen DERepeatStar begin Generate an output event Recall that the first event comes out at time 0 output put completionTime lt lt double magnitude and schedule the next firing refireAtTime completionTime Generate an exponential random variable double p random Turn it into an exponential and add to completionTime completionTime p The Poisson star generates a Poisson process The inter arrival time of events is exponen tially distributed with parameter meanTime Refer to Using Random Numbers on page 3 17 for information about the random number generation The method refireAtTime launches an event onto a feedback arc that is invisible to the users The feedback event triggers the self scheduling star some time later Note that the feedback event for the next execution is generated in the current execu tion To initiate th
145. ed to represent gray scale images The DCTImage class is used to represent images or image fragments that have been encoded using the discrete cosine transform The MVImage class is a bit more specialized it stores a frame s worth of motion vectors 4 7 3 First class types All of the types built in to the Ptolemy kernel are first class in the sense that they are understood by pigi and ptlang We recommend that users create their own types using the mechanism described in Defining New Data Types on page 4 14 This approach has the dis advantage that all user defined types are seen by pigi and ptlang as being of type mes sage If this is not acceptable then it is possible to create your own first class types by sub classing Particle and adding the new types to VEM The following instructions briefly describes this process We stress however that this method is not officially supported and that types created this way will probably have to be reworked in a future release of Ptolemy You will need to use some other color say ileColor as a sample to follow when modifying the various source files e Sub class Particle and Message Use the classes in SPTOLEMY src kernel FileMessage h cc and SPTOLEMY src kernel FileParticle h cc as examples You will need to create a static instance of your Particle and static Plasma and PlasmaGate instances to hold your particles as demonstrated by FileParticle
146. ed whenever the user moves the control on the scale Its single argument will be the new position of the control between and 100 Arguments win name of window to contain the scale name name to use for the scale itself desc description to be put into the display position initial integer position between 0 and 100 callback name of callback procedure to register changes Note A widget is created with name win name value that should be used by the programmer to display the current value of the slider Thus the callback procedure should contain a command like Department of EECS The Almagest 5 9 Swin Sname value configure text Snew value to display the new value after the slider has been moved This is not performed automatically because the fixed range from 0 to 100 may be correct from the user s perspective So for exam ple if you divide the scale value by 100 before displaying it then to the user it will appear as if the scale ranges from 0 0 to 1 0 It is also possible to control the position of the slider from Tcl overriding the user actions using a command like Swin name scale set Sposition where position is an integer valued variable in to 100 the range of 0 Example 3 The following Tcl script can be used with the TclScript star in the sys tem configuration given in example on page 5 2 ptkMakeMeter SptkControlPanel high meter_SstarlI meter tracking scale 0 100 proc scale_update_S starID n
147. eduler we ignore communication overhead when assigning stars to processors Hence the code is likely to contain more com munication stars than with the other schedulers that do not ignore IPC overhead There are other target parameters that direct the scheduling procedure If the parameter manualAssignment is set to YES then the default parallel scheduler does not perform star assignment Instead it checks the processor assignment of all stars set using the procId state of CG and derived stars By default the procId state is set to 1 which is an illegal assign ment since the child target is numbered from 0 If there is any star except the Fork star that has an illegal procId state an error is generated saying that manual scheduling has failed Otherwise we invoke a list scheduler that determines the order of execution of blocks on each processor based on the manual assignment We do not support the case where a block might U C Berkeley Department of EECS The Almagest 13 23 require more than one processor The manualAssignment option automatically sets the oneStarOneProc state to be discussed next If there are sample rate changes a star in the program graph may be invoked multiple times in each iteration These invocations may be assigned to multiple processors by default We can prevent this by setting the oneStarOneProc State to YES Then all invocations of a star are assigned to the same processor regardless of whe
148. efault T lt foo 2 0 0 5 lt foo lt bar ct ct A repeat notation is also supported for ArrayState objects the two value strings 1 0 5 fT Or SO PaO AO EO default default Gh sc are equivalent Any integer expression may appear inside the brackets The number of ele ments in an ArrayState can be determined by calling its si ze method The size is not spec ified explicitly but is calculated by scanning the default value As an example of how to access the elements of an ArrayState suppose fState is aFloatState and aState is a FloatArrayState The accesses like those in the follow Ptolemy Last updated 8 26 97 2 24 Writing Stars for Simulation ing lines are routine fState aState 1 0 5 aState 1 double fState 10 0 aState 0 double fState aState 2 R star defined For a more complete example of the use of FloatArrayState consider the F1 below Note that this is a simplified version of the SDF FIR star that does not permit interpo lation or decimation defstar name FIR domain SDF desc A Finite Impulse Response FIR filter input name SignalIn type float output name signalOut type float state name taps type floatarray default 04 001 17 37 2 37 s7 0018 DAT 4 desc Filter tap values setup tell the PortHole the maximum delay we will use signalin
149. eger input specifies the number of particles that will be consumed on the next firing After these particles have been consumed the star reverts to SDF behavior to collect the next control input In the following readyToGo and num are private integers setup clearWaitPort readyToGo FALSE go inte ds if readyToGo get input token from Geodesic input receiveData num int input 0 waitFor input num readyToGo TRUE else for i 0 i lt num i input receiveData output 0 lt lt int input 0 output sendData readyToGo FALSE clearWaitPort Because of the clearWaitPort in the setup method the star begins as an SDF star It consumes one data stores its value in num and issues a waitFor command This changes its behavior to DDF and specifies the number of input tokens that are required On the next firing it will read num input tokens and copy them to the output and then it will revert to SDF behav ior Ptolemy Last updated 7 23 96 8 4 DDF Domain U C Berkeley Department of EECS Chapter 9 BDF Domain Authors Joseph T Buck 9 1 Writing BDF Stars BDF stars are written in almost exactly the same way as SDF stars are written When the go method of the star is executed it is guaranteed that all required input data are present and after execution any particles generated by the star are correctly sent off to their destina tions The only additional thing
150. em e g the factor of upsampling and downsampling stars and changing these would mean that new code needs to be generated since the scheduling is hard coded into the generated code Thus these should not be allowed to take values from the command line A new attribute can be intro duced to identify those states that should not be settable from the command line Warnings can then be generated if users attempt to specify these for command line setting 14 5 CGC Compile time Speed There are several areas that can affect the amount of time that it takes a CGC universe to compile we discuss them below e Large sample rate changes and large delays can result in Ptolemy taking a very long time to generate C code A symptom of this sort of problem is that the pigiRpc pro cess will consume all the available swap and eventually crash If you feel you need really large delays James Lundblad suggests writing your own code in your stars that provides the same functionality as delays but uses malloc in the initCode sec tion instead of the array that is created by the CGC Delay icon e C compiler optimizers do not work well with functions that have thousands of lines The main function of a CGC simulation may be too large for the peephole opti mizer causing the optimizer to take a long time to compile the file Under gcc you can pass the 00 option to turn off the optimizer 14 6 BDF Stars Because the class CGCPortHole is not derived from BDFPo
151. en a Universe is run Now that you have some idea of what classes exist in the Ptolemy kernel this section will try to explain flow of control when a Universe is run By knowing this you will get an idea of what additions or changes might be needed to get the functionality you desire and how the code of your new domain will fit in First off a little more about the basics of Ptolemy classes Almost every object class in Ptolemy is derived from the NamedObj class This class simply provides support for a Name field a longer Description field and a pointer to a Parent Block Also the method ini tialize is declared here to be purely virtual so every object should have some kind of initialization function The Block class is derived from NamedoOb j and is the main base class for most actors in Ptolemy It has I O constructs like PortHoles and MultiPortHoles state parameter constructs like State and defines execution methods such as setup run and wra pup The Block also provides a virtual function to access an associated Scheduler A simulation universe is generally of type DataFlowStar When a universe is run the flow of control is as follows using the SDF domain as an example PTcl dispatcher PTcl run PTcl computeSchedule Runnable initTarget Block initialize SDFTarget setup Target setup SDFScheduler setup U C Berkeley Department of EECS The Almagest 17 7 Notice at this poi
152. en help so the descriptor should not include any troff for matting commands Unlike the htmldoc described below it does not pass through troff The following are legal descriptors desc A one line descriptor or desc A multi line descriptor The same line breaks and spacing will be used when the descriptor is displayed on the screen By convention in these descriptors references to the names of states inputs and out puts should be enclosed in quotation marks Also each descriptor should begin with a capital letter and end with a period If the descriptor seems to get long augment it with the htmldoc directive explained below However it should be long enough so that it is sufficient to explain the function of the star version This item contains two entries as shown below Ptolemy Last updated 8 26 97 2 8 Writing Stars for Simulation version 1 number MO DA YR where the number is a version number and the MO DA YR is the version date If you are using SCCS for version control then the following syntax will work well o G o version WS When the file is checked in by SCCS the string sw will be replaced with a string of the form filename num where num is the version number and G3 will be replaced with a properly formatted date author This optional entry identifies the author or authors of the star The syntax is author authori author2 and author3 Any set o
153. entialList gt lastNode 0x0 dimen 0 states lt NamedObjList gt lt SequentialList gt lastNode 0x0 dimen 0 multiports lt NamedObjList gt lt SequentialList gt lastNode 0x0 dimen 0 indexValue 1 inStateFlag 1 gdb This tells you that a star with name nm BadStar1 and descriptor Causes a core dump deliberately is being invoked This particular star has the following erroneous go method go char p 0 D SE Teg More elaborate debugging reguires that the symbols for the star be included The easiest way to do this is to build a version of pigiRpc debug that includes your star already linked into the system Then repeat the above procedure The bottom of the stack frame will have much more complete information about what is occurring 1 7 3 Debugging hints Below are some hints for debugging e Using emacs gdb and pigi on page 1 26 e Gdb and the environment on page 1 26 e Optimization on page 1 26 e Debugging StringLists in gdb on page 1 26 e How to use ptcl to speed up the compile test cycle on page 1 27 Ptolemy Last updated 10 10 97 1 26 Extending Ptolemy Introduction e Miscellaneous debugging hints for gdb on page 1 28 See also Appendix A of the Ptolemy User s manual Using emacs gdb and pigi By default gdb is started in an X terminal window with its default command line interface Many peop
154. eodesic keeps a single copy of a parent matrix that represents the current two dimensional datablock Each time a star fires it obtains a sub matrix that refer ences this parent matrix with the getOutput function of the MDSDF input port class For example a star might contain FloatSubMatrix data FloatSubMatrix input getInput Note that this is not really getting a matrix but a sub matrix that references a region of the current data matrix The size of the sub matrix has been set by the star in its initialization code by calling the setMDSDFParams function of the port To write data to the output matrix the star gets a sub matrix which references a region of the current output matrix and writes to it with a matrix operator For example FloatSubMatrix result FloatSubMatrix output getOutput result data U C Berkeley Department of EECS The Almagest 4 39 Because the sub matrices are only references to the current matrix on each arc they must be deleted after use Ptolemy delete amp input delete amp result Here is a simplified example of a complete MDSDF star defstar name Add domain MDSDF desc Matrix addition of two input matrices A and B to produce matrix C All matrices must have the same dimensions version SWS G S author Mike J Chen location MDSDF library input name Ainput type FLOAT_MATRIX input name Binput
155. epartment of EECS The Almagest 13 11 instances will have unigue symbols A example of where this is used in the CG56HostoOut star codeblock cbSingleBlocking Slabel wait jclr m_htde x m_hsr Slabel wait jclr 0 x m_pbddr Slabel wait movep Sref input x m_htx codeblock cbMultiBlocking move Saddr input r0 LOOP Sval samplesOutput Slabel wait jclr m_htde x m_hsr Slabel wait jclr 0 x m_pbddr Slabel wait movep x r0 x m_htx ENDL nop The above two codeblocks use a label named wait The label macro will assign unique strings for each codeblock The base CGStar class provides the above 8 macros In the derived classes we can add more macros or redefine the meaning of these macros Refer to each domain document to see how these macros are actually expanded There are three commonly used macros in the assembly code generation domains these are Saddr name This returns the address of the allocated memory location for the given state or porthole name The address does not include references to the memory bank the location is coming from for instance x 2034 for location 2034 in the x memory bank for Motorola 56000 is output as 2034 Saddr name lt offset gt This macro returns the numeric address in memory of the named object with out for the 56000 an x or y prefix If the given quantity is allocated in a register not yet su
156. eplacement operators These operators are member functions that modify the current value of the object In the following examples A is usually the lvalue this All operators return this XXXMatrix amp operator const XXXMatrix amp src Example A B Ptolemy Last updated 10 10 97 4 26 XXXMatrix amp XXXMatrix amp XXXMatrix amp XXXMatrix amp XXXMatrix amp XXXMatrix amp XXXMatrix amp XXXMatrix amp XXXMatrix amp U C Berkeley Data Types This is the assignment operator make A into a matrix that is a copy of B If A already has allocated data storage then the size of this data stor age is compared to the size of B If they are equal then the dimensions of A are simply set to those of B and the entries copied If they are not equal the data storage is freed and reallocated before copying operator xxx value Example A value Assign each entry of A to have the given value Memory management is handled as in the previous operator Note this operator is targeted for deletion Do not use it operator const XXXMatrix src Example A B Perform the operation A entry i B entry i for each entry in A A and B must have the same dimensions operator xxx value Example A value Add the scalar value to each entry in the matrix operator const XXXMatrix src Example A B Perform the operation A entry i B entry i for each ent
157. equired communication on the shared bus member object of that class and returns the scheduled time The communication cost in time is mod eled by the commTime method Given the information on which processors are involved in this communication and how many tokens are transmitted it returns the expected communica tion time once started By default or in fully connected topology it only depends on the number of tokens A CGMultiTarget has a sequence of child target objects to represent each of the individual processors The number of processors are determined by an IntState nprocs and the type of the child target is specified by a StringState childType Refer to the User s Manual for details on how to specify the various target parameters In the setup stage the child targets are created and added to the child target list as members of the multiprocessor target Classes derived from Multi Target represent the topology of the multi processor net work communication costs between processors schedules for use of communication facili ties etc and single processor child targets can represent arbitrary types of processors The resource allocation problem is divided between the parent target representing the shared resources and the child targets representing the resources that are local to each processor The main role of a multiprocessor target is to set up one of the chosen parallel schedul ers and to coordinate the child tar
158. er we will cover the use of these facilities and some of the important methods currently available in Ptolemy to implement new scheduling algorithms 6 2 Basic Classes User specifications done in Ptolemy are represented internally as a collection of anno tated directed graphs that may contain cycles Nodes in these directed graphs may themselves contain other directed graphs An atomic node is either a Star which defines code to imple ment the node operation or a WormHole which has an internal graph that is hidden from the outside A WormHole is used when there is a change in the semantics between the internal and external graphs such as a change in the Domain or Scheduler For purposes of the outside graph a wormHole is equivalent to a Star A non atomic node or Galaxy is a node which contains an internal graph which is visible from the outside This internal graph is stored in a Galaxy s BlockList Finally a Scheduler is a class that determines the firing order of atomic nodes in a graph WormHoles Galaxies and Stars are all derived from the class Block A Block contains Port Lists which store a list of PortHoles that provide locations to connect input or output arcs to the Block Blocks also contain StateLists which may either be user specified parameters or run time states that are used when a graph is executed A user specification is compiled into an internal representation known as an inter preted univers
159. er Contributors Brian L Evans 12 1 Introduction The discrete event DE domain in Ptolemy provides a general environment for time oriented simulations of systems such as gueueing networks communication networks and high level computer architectures In the domain each Particle represents an event that corresponds to a change of the system state The DE schedulers process events in chronolog ical order Since the time interval between events is generally not fixed each particle has an associated time stamp Time stamps are generated by the block producing the particle using the time stamps of the input particles and the latency of the block We assume in this chapter that the reader is thoroughly familiar with the DE model of computation Refer to the User s Manual Moreover we assume the reader is familiar with chapter 2 Writing Stars for Simulation In this chapter we give the additional information required to write stars for the DE domain 12 2 Programming Stars in the DE Domain A DE star can be viewed as an event processor it receives events from the outside processes them and generates output events after some latency In a DE star the management of the time stamps of the particles events is as important as the input output mapping of par ticle values Generating output values and time stamps are separable tasks For greatest modularity therefore we dedicate some DE stars so called delay stars to time manageme
160. er for the star to fire The following line in the setup method of the star is used to make this information available to the scheduler input setSDFParams int size int size 1 The name of the input porthole is input The first argument to set SDFParams specifies how many samples are consumed by the star when it fires it is the same as the number of samples required in order to enable the star The second argument to set SDFParams specifies how many past samples before the most recent one will be accessed by the star when it fires If the number of particles produced or consumed is a constant independent of any states then it may be declared right along with the declaration of the input in the p1 file For example input name signalIn type complex 7 2 SDF Domain numTokens 2 desc Complex input that consumes 2 input particles This declares an input that consumes two successive complex particles U C Berkeley Department of EECS Chapter 8 DDF Domain Authors Soonhoi Ha 8 1 Programming Stars in the DDF Domain A DDF star as distinct from an SDF star has at least one porthole either an input or an output that receives or sends a variable number of particles Such portholes are called dynamic Consequently for a DDF star how many particles to read or write is determined at run time in the go method Consider an example the Last OfN star defstar name LastOfN domain DDF desc
161. er of blocks in each child target and creating the sub galaxies The actual creation of send receive stars is done by the parallel scheduler by invoking methods createSend and createReceive as mentioned earlier in the parent multi target Ptolemy Last updated 10 17 97 13 24 Code Generation Once the generated code is loaded processors run autonomously The synchronization protocol between processors is hardwired into the send and receive stars One common approach in shared memory architectures is the use of semaphores Thus a typical synchroni zation protocol is to have the send star set a flag when it completes the data transfer and have the receive star read the data and reset the semaphore The receive star will not read the data if the semaphore has not been set and similarly the send star will not write data if the semaphore has not been reset In a message passing architecture the send star may form a message header to specify the source and destination processors In this case the receive star would decode the message by examining the message header For properly supporting arbitrary data types the send star should have an ANYTYPE input the receive star should have an ANYTYPE output The resolved type for each of these ports can be obtained using the Porthole resolvedType method For a preliminary ver sion of the communication stars you can use a fixed datatype such as FLOAT or INT The send re
162. er we use g from the Free Software Foundation Tcl Tk and vem programs that were developed quite independently but upon which Ptolemy relies The distribution also includes a large number of demonstrations Perusing the demonstrations can be an excellent way to get familiar with the system Perusing the source code is by far the best way to under stand the system At a minimum anyone wishing to write new stars should read the source 1 2 Extending Ptolemy Introduction code for a few of the built in stars 1 2 1 Ptolemy environment variables The root of the Ptolemy tree is often installed in the home directory of a fictitious user called ptolemy If the installation follows this model at your site you can find the Ptolemy code with the following command cd ptolemy If your installation does not have a user named ptolemy then you must find out where your system administrator has installed the system and set an environment variable called PTOLEMY to point to this directory For instance if your system administrator installed Ptolemy in users ptolemy then you should issue the following command setenv PTOLEMY users ptolemy SPTARCH is an environment variable representing the architecture on which you are running and has one or more of the following values sun4 so12 or hppa for Sun under Sun O S Sun under Solaris 2 X and HP machines respectively There are a few other pos sible values for the PTARCH variab
163. ere are four scalar numeric data types defined in the Ptolemy kernel complex fixed point double precision floating point and integer All of these four types can be read from and written to portholes as described in Reading inputs and writing outputs on page 2 17 The floating point and integer data types are based on the standard C double and int types and need no further explanation To support the other two types the Ptolemy kernel contains a Complex class and a Fix class which are described in the rest of this section 4 2 1 The Complex data type The Complex data type in Ptolemy contains real and imaginary components each of which is specified as a double precision floating point number The notation used to represent 4 2 Data Types a complex number is a two number pair real imaginary for example 1 3 4 5 corre sponds to the complex number 1 3 4 57 Complex implements a subset of the functionality of the complex number classes in the cfront and libg libraries including most of the stan dard arithmetic operators and a few transcendental functions Constructors Complex Create a complex number initialized to zero that is 0 0 0 0 For example Complex C Complex double real double imag Create a complex number whose value is real imag For example Complex C 1 3 4 5 Complex const Complex amp arg Create a complex number with the same value as the argument the copy constructor For e
164. es to ensure that files are not deleted until no longer needed Although we created a new particle type to allow these types to appear in the pigi graphical interface we recommend that you use the Message interface described in Section 4 3 for your own types The File type adds the following functions to Message Constructors FileMessage Create a new file message with a unique filename By default the file will be deleted when no file messages reference it FileMessage const char name Create a new file message with the given filename By default the file will not be deleted when no file messages reference it FileMessage const FileMessage amp src Create a new file message containing the same filename as the given file message By default the file will not be deleted when no file mes sages reference it Operations const char fileName Return the file name contained in this message StringList print Return the file name contained in this message in a StringList object const char fileName Return the file name contained in this message void setTransient int transient Set the status of the file If transient is TRUE the file will be deleted U C Berkeley Department of EECS The Almagest 4 35 when no file messages reference it if FALSE then it will not be deleted 4 5 2 The String type The string type is implemented by the classes StringMessage and StringParti cle which are der
165. ese see ee ee ee 3 8 explanation ptlang directive ees see ee 2 6 2 9 exponentially distributed random numbet 3 17 external programs INVOKING Sissi ee Es gee Alaa alent Aves 3 8 F FETCx SDF block oe ee 7 1 file input to states iese ee ee RR RR 2 23 file target parameter esse se se ee ee ee ee ee 13 21 first in first out FIFO queue ee ee ee 3 11 Fix CLASS 35 SE goes Eg See does 4 3 2772 4 14 OPCLALOL ees ee ee ee ee ee ek ee ee ee ee Ee 4 12 A Operator Ten sate aah 4 12 r Operators Ai eek EE site Be 4 12 OPCLALOL eeue een ee ee ee ek en Re Re ee ee A 12 TT N N 4 12 operato eseese ee NR duck Ee eg se teks 4 12 OPV EE 4 12 OPEtAtOF ER sean ete keM EE 4 12 Operators a ee a Re ER ee A 12 clear errors ie Ge ee ee 4 12 COMPALE ee eek ee ee ee ee ee ee ee ee 4 11 complement ees ee ee ee ee 4 13 GONSITUCTOIS akeo N a 4 9 CONVEFSION OperatOTS iese ee ee ee o 4 13 Last updated 10 17 97 RR ESE DVD AG 4 12 INTDO SEER ESEG EE coe RE es 4 10 INVALIA eee ceseecscecseeecsesescecesesvecsssescsenees 4 11 isaer RE ESE DS aah 4 11 ETE OR ER ER ESEE nes 4 10 TREE GER EE ES DE EE EE Ee Ee 4 11 maximum length ee se ee ee ee ee ee ee 4 4 OR A ar et Ae tee ele nts 4 11 overflOW iese ee ee ee ee ee ee ee ee ee 4 10 OVE occumed ee ee ee ee 4 11 PLCCISION ee ee ee eek ek ee ee ee ee ee ee ee 4 10 roundMode oe ceseececesesesceeseesesesescscsseseecsesees 4 11 Set Overflow iets Gandia 4 11 SCt_LOU
166. essary to indicate precisely which type conversion is desired To write data to an output porthole note that the right hand side of the assignment operator should be of type Particle as shown in the above example An operator lt lt is defined for particle classes to make this more convenient Consider the following example go float t t some value to be sent to the output out sO lt lt t Note the distinction between the lt lt operator and the assignment operator the latter operator copies Particles the former operator loads data into particles The type of the right side oper and of lt lt may be int float double Fix Complex or Envelope the appropriate type conversion will be performed For more information on the Envelope and Message types please see the chapter Data Types on page 4 1 SDF PortHole parameters In the above example where in 1 was referenced some special action is required to tell Ptolemy that past input particles are to be saved Special action is also required to tell the SDF scheduler how many particles will be consumed at each input and produced at each out put when a star fires This information can be provided through a call to set SDFParams in the setup method This has the syntax setup name setSDFParams multiplicity past where name is the name of the input or output porthole multiplicity is the number of par ticles consumed or produced and past is the maximum va
167. eturn FALSE if setup fails Block parent pointer to the block using the class char desc label for the bar graph int numInputs the number of data sets to plot int numBars the number of bars per data set to show at once double top the numerical value that will produce the highest bar double bottom the numerical value that will produce the lowest bar char geometry the starting position for the window e g 0 0 or 0 0 double width the starting width of the window in cm double height the starting height of the window in cm int update modify or add a bar return FALSE if it fails int dataSet the number of the data set starting with 0 int bar the horizontal position of the point to plot double y the requested height of the bar TABLE 3 3 A summary of the most useful methods of the BarGraph class which creates ani mated bar graph charts in a window and is available to stars running under pigi 3 3 4 Collecting statistics using the histogram classes The Histogram class constructs a histogram of data supplied The XHistogram oar Chere dar lay deal rangri ql DUE FIGURE 3 2 An example of an animated bar graph created using the BarGraph class This class uses Tk so it is available under pigi but not under pt cl Ptolemy Last updated 8 26 97 3 6 Infrastructure for Star Writers class also constructs a histogram but then plots it usi
168. eturns nothing This procedure therefore allows for synchro nous communication between the Ptolemy simulation and the Tcl code it is synchronized to the firing of the star If no goTcl1 S starl D procedure is defined then communication is asynchronous Tcl commands are invoked at arbitrary times as specified when the script is read For asynchronous operation typically X events are bound to Tcl Tk commands that read or write data to the star The inputs to the star can be of any type The print method of the particle is used to construct a string passed to Tcl Although chronous reads of the star inputs are also allo it is not illustrated in the above examples asyn wed Below is a summary of the Tcl procedures used when executing a Tcl Script star grabInputs_SstarID A procedure that returns the current values of the inputs of the star corresponding to the given starID This procedure is defined by the TclScript star if and only if the instance of the star has at least one input port setOutputs_SstarID A procedure that takes one argument for each output of the TclScript star The value becomes the new output value for the star This procedure is defined by the TclScript star if and only if the instance of the star has at least one output port goTcl_ starID If this procedure is defined in the Tcl script associated with an instance of the TclScript star then it will be invoked every
169. ew_value ptkSetMeter SptkControlPanel high meter _SstarID Snew_value D SptkControlPanel high scale_S starID value N configure text Snew_value ptkMakeScale SptkControlPanel high scale starl my scale 50 scale_update_SstarID ptkMakeButton SptkControlPanel middle button s my button button_update proc button update ptkImportantMessage msg ptkMakeEntry SptkControlPanel low entry starID my entry 10 entry update starID proc entry update starlID inew value setOutputs_SstarID VS new value It will create the rather ugly control panel shown below Control panel for tel script demo When to stop oom F Debug OD Return PAUSE Seaces STOP Escape meter tracking scale my attom my entry EE DISATSS The commands are explained individually below Ptolemy ptkMakeMeter SptkControlPanel high meter_ starI D tarID N Hello D Last updated 10 10 97 5 10 Using Tcl Tk meter tracking scale 0 100 This creates a meter display with the label meter tracking scale in the upper part of the control panel with range from 0 to 100 proc scale_update_SstarID new_value otkSetMeter SptkControlPanel high meter _SstarID Snew_value SptkControlPanel high scale_SstarID value configure text VSnew value This defines the callback function to be used for the slider scale shown below the
170. example 1 9 How mkPtolemyTree works 1 10 Combining mkPtolemyTree and pigiExample 1 11 Known Bugs in mkPtolemyTree 1 11 1 5 Using csh aliases to create a Parallel Software Development Tree 1 12 Aliases for Managing Symbolic Links 1 12 Creating a Duplicate Hierarchy 1 16 Source Code Control 1 18 1 6 Building standalone programs that use Ptolemy libraries 1 19 Standalone example using StringList 1 19 Standalone example that tests a Scheduler 1 20 1 7 Debugging Ptolemy and Extensions Within Pigi 1 21 A quick scan of the stack 1 22 More extensive debugging 1 23 Debugging hints 1 25 2 Writing Stars for Simulation ceeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeees 2 1 2 1 IMMPOGUCUON ss force neared MOED GE ee AE RE REDE wee eee 2 1 2 2 Adding stars dynamically to Ptolemy 2 1 2 3 The Ptolemy preprocessor language ptlang 2 3 Invoking the preprocessor 2 4 An example 2 4 Items that appear in a defstar 2 5 2 4 Writing C code for starS ss ss ae cee eee eee 2 16 The structure of a Ptolemy star 2 17 Reading inputs and writing outputs 2 17 States 2 21 Array States 2 23 2 5 Modifying PortHoles and States in Derived Classes 2 26 2 6 Programming exampleS ss ss ae RR RR AR RR RE 2 26 2 7 Preventing Memory Leaks in C Code 2 28 3 Infrastructure for Star Writers cccseseeseeeseeeeeeeeeeeeeeeeeeeeeees 3 1 Ptolemy Last updated 10 17 97 d d ulntroducHOR ss SERE EE E
171. execution order of stars including send receive stars This is done by a simple list scheduling algorithm in each child target The final scheduling results are displayed on a Gantt chart The multiple processor scheduler produces a list of single processor schedules giving them to the child targets The schedules include send receive stars for interprocessor communication The child targets take their schedules and generate code To produce code for child targets we create a sub galaxy for each child target which consists of the stars scheduled on that target and some extra stars to be discussed below if nec essary A child target follows the same step to generate code as a single processor target except that the schedule is not computed again since the scheduling result is inherited from the parent target Send Receive stars After the assignment of APEG nodes is finished the interprocessor communication requirements between blocks are determined in sub galaxies Suppose star A is connected to star B and there is no sample rate change By assigning star A and star B to different proces sors 1 and 2 respectively the parallel scheduler introduces interprocessor communication Then processor 1 should generate code for star A and a send star while processor 2 should generate code for a receive star and star B These send and receive stars are inserted automatically by the Ptolemy kernel when determining the execution ord
172. expected results A non deterministic loop is one in which the priorities cannot be assigned uniquely there is more than one solution Such a loop has at least one before relation If a programmer can guarantee that there is no possibility of simultaneous events on such a loop then system may be simulated in a predictable manner Otherwise the arbitrary decisions in the scheduler will affect the firing order If a non deterministic loop contains exactly one before relation the scheduler assigns priorities in a well defined way but unfortunately in a way that is hidden from the user For a non deterministic loop with more than one before relation the assignment of the priorities is a non deterministic procedure Therefore the scheduler emits a warning message The warning message suggests that the programmer put a delay element on an arc usually a feedback arc to break the non deterministic loop As mentioned before the delay element has a totally different meaning from that in the SDF domain In the SDF domain a delay implies an initial token on the arc implying a one sample delay In the DE domain however a delay element simply breaks a triggering chain Therefore the source port of the arc is assigned the lowest priority 12 2 6 Source stars The DE stars discussed so far fire in response to input events In order to build signal generators or source stars or stars with outputs but no inputs we need another class of DE star called
173. f This global variable has been set by pigi and can be used by any Tcl script The second part middle specifies that the button should appear in the subwindow named middle of the control panel The control panel by default has empty subwindows named high middle and low The last part button starID gives a unique name to the button itself The Tcl variable st arID has been set by the TclScript star to a name that is guaranteed to be unique for each instance of the star Using a unique name for the button permits multiple instances of the star in a schematic to create separate buttons in the control window without conflict if winfo exists s This conditionally checks to see whether or not the button already exists If for exam ple the system is being run a second time then there is no need to create the button a second time In fact an attempt to do so will generate an error message If the button does not already exist then it is created by the following lines button s text PUSH ME pack append S ptkControlPanel middle s top The first of these defines the button and the second packs it into the control panel see the Tk documentation The following Tcl statement binds a particular command to a mouse action thus defining the response when the button is pushed bind s lt ButtonPress 1 gt setOutputs_S starID 1 0 When button number 1 of the mouse is pressed the Tcl interpre
174. f characters between the braces will be interpreted as a list of author names acknowledge This optional entry attaches an acknowledgment section to the documentation The syntax is acknowledge arbitrary single line of text copyright This optional entry attaches a copyright notice to the n cc and t files The syntax is copyright copyright information For example we used to use the following our lawyers have recently caused us to increase the verbosity copyright 1994 The Regents of the University of California The copyright may span multiple lines just like a descriptor In house we use the SCCS sos keyword to update the date when a file is changed A typical copyright line might look like copyright 1990 0 The Regents of the University of California location This item describes the location of a star definition The following descriptions are used for example U C Berkeley Department of EECS The Almagest 2 9 location SDF dsp library or location directory where directory is the location of the star This item is for documentation only explanation This item is used to give longer explanations of the function of the stars In releases previous to Ptolemy 0 7 this item included troff formatting directives In Ptolemy 0 7 and later this item has been superceded by the htm1doc item htmldoc state Ptolemy This item is used to give longer explanations that
175. f constructor arguments for each sep arated by commas if there is more than one The syntax is conscalls memberl arglist member2 arglist Note that member1 and member2 should have been previously defined in a public private or protected section see page 2 14 destructor setup begin This item inserts code into the destructor for the class The syntax is destructor body You generally need a destructor only if you allocate memory in the constructor begin method or setup method termination functions that happen with every run should appear in the wrapup function The optional keyword inline may appear before destructor if so the destructor function definition appears inline in the header file Since the destructor for all stars is virtual this is only a win when the star is used as a base for derivation This item defines the setup method which is called every time the simulation is started before any compile time scheduling is performed The syntax is setup body The optional keyword inline may appear before the setup keyword It is common for this method to set parameters of input and output portholes and to initialize states The code syntax for doing this is explained starting on page 2 16 In some domains with some targets the setup method may be called more than once during initiation You must keep this in mind if you use it to allocate or initialize memory This item defines the begin meth
176. f the object s data members If the buffer is full then the thread that invoked slowPut is suspended until notification is received on not Full Data is placed in the buffer and notification is sent on notEmpty to any other thread that may have been waiting Block when full Notify when not empty void PNGeodesic slowPut Particle p Avoid entering the gate more than once CriticalSection region gate if sz gt cap amp amp notFull CriticalSection region fullGate numFull while sz gt cap amp amp notFull notFull gt wait CriticalSection region fullGate numFull pstack putTail p sztt if notEmpty notEmpty gt notifyAll The setCapacity method shown below is used to adjust the capacity limit of com munication channels If the capacity is increased so that a channel is no longer full notifica tion is sent on not Full to any thread that may have been waiting void PNGeodesic setCapacity int c CriticalSection region gate cap C if sz lt cap amp amp notFull notFull gt notifyA1ll Ptolemy Last updated 4 17 97 10 12 PN domain 10 4 Scheduling Figure 10 3 shows the class derivation hierarchy for the classes that implement the ThreadScheduler E PosixScheduler PNThreadScheduler PNScheduler FIGURE 10 3 The class derivation hierarchy for schedulers ThreadList is a container class for threads Each PNScheduler uses a
177. fString temporary will be destroyed too soon leaving the const char or char pointer pointing to garbage The solution is to assign the returned value to a local StringList or InfString before performing the cast Suppose for example that the function foo returns an InfString Further suppose the function bar takes a char argu ment Then the following code will fail bar foo Note that the cast to char is implicit The following code will succeed InfString x foo bar x 3 5 lIterators The StringList class is one of several list classes in the Ptolemy kernel A basic oper ation on list classes is to sequentially access their members one at a time This is accomplished using an iterator class companion to the list class For the StringList class the iterator is called StringListIter Its methods are summarized in table 3 9 An example program frag StringListIter class include StringList h description StringList constructor StringList amp list the list over which the iterator will iterate t char next return the next string on the list or 0 if there are no more char operator a synonym for next void reset reset the iterator to start at the head again TABLE 3 9 An example of an iterator class used to access the elements of a list class ment using this is given below StringListIter item myList const char string U C Berkeley De
178. fault binary for yourself you can set your PI the name of the binary you just built G setenv PI IRPC SPTOL EMY obj PTARCH pigil G Example pigiRpc IRPC environment variable to Next time you start pigi your new executable will be used instead of the standard one To revert to using the installed pigiRpc just type GI unsetenv PI SPTOLI directory RPC If you want your pigiRpc to be the default pigiRpc you can install it in EMY bin PTARCH but this will wipe out whatever pigiRpc is in that With the same makefile you can make a version of the pigiRpc program that has debug symbols Just type make pigiRpc debug To use this assuming the Gnu debugger gdb is in your path specify the executable as fol lows setenv PIG SPTOLI assuming your executable is in as follows pigi debug To revert to using the installed p Bi unsetenv PI IRPC EMY obj SPTARCH pigil Example pigiRpc debug PTOLEMY obj SPTARCH igiRpc just type RPC pigil 1 3 2 Creating a pigiRpc with more extensive customizations Example Then start pigi If you are extending Ptolemy in nontrivial ways such as writing a new domain we U C Berkeley Department of EECS The Almagest 1 9 suggest that you create your own copy of the Ptolemy directory tree You may use symbolic links to the official directories if you do not nee
179. fied during a run There is currently no mechanism for checking the correctness of these attributes All states are derived from the base class State defined in the Ptolemy kernel The derived state classes currently defined in the kernel are Float State IntState Complex State StringState FloatArrayState IntArrayState ComplexArrayState and StringArrayState A state can be used in a star method just like the corresponding predefined data types As an example suppose the star definition contains the following directive state Ptolemy Last updated 8 26 97 2 22 Writing Stars for Simulation name myState type float default 1 0 descriptor Gain parameter This will define a member of class FloatState with default value 1 0 No attributes are defined so A_CONSTANT and A_SETTABLE the default attributes are assumed To use the value of a state it should be cast to type double either explicitly by the programmer or implicitly by the context For example the value of this state can be accessed in the go method as follows go output 0 lt lt double myState double input 0 The references to input and output are explained above The reference to myState has an explicit cast to double this cast is defined in FloatState class Similarly a cast to int is available for IntState to Complex from ComplexState and to const char for Stringstate In principle it
180. fileName state would not have been initialized Notice that the setup method reclaims the memory allocated in previous runs or previous invocations of the setup method before creating a new pt_ofstream object Notice that we are not using a wrapup method to reclaim the memory since this method is not invoked if an error occurs during a run The classes pt_ifstream and pt_ofstream are only a slight extension of the classes ifstream and ofstream They add the following features e First certain special file names are recognized as arguments to the constructor or to the open method These file names are lt cin gt lt cout gt lt cerr gt or lt clog gt the angle brackets must be part of the string then the corresponding standard stream of the same name is used for input pt ifstream or output pt_ofst ream In addition C standard I O fans can specify lt stdin gt lt stdout gt or lt stderr gt e Second the Ptolemy expandPathName see table 3 7 on page 3 8 is applied to the filename before it is opened permitting it to start with user or SVAR e Finally if a failure occurs when the file is opened Error abortRun is called with an appropriate error message including the Unix error condition These classes can be used for binary character data as well as ASCII 3 3 2 Generating graphs using the XGraph class The XGraph class provides an interface to the pxgraph program used for plotting data on an X window system disp
181. for Simulation default 040609 0 0 001628 0 0 17853 0 0 37665 0 0 37665 0 0 17853 0 0 001628 0 0 040609 0 0 For complex states the syntax for the default value is real imag where real and imag evaluate to integers or floats The precision state is used to give the precision of fixed point values These values may be other states or may be internal to the star The default can be specified in either of two ways Method 1 As a string like 3 2 or more generally m n where m is the number of integer bits to the left of the binary point and n is the number of fractional bits to the right of the binary point Thus length is m n Method 2 A string like 24 32 which means 24 fraction bits from a total length of 32 This format is often more convenient because the word length often remains con stant while the number of fraction bits changes with the normalization being used In both cases the sign bit counts as one of the integer bits so this number must be at least one The desc or descriptor item which is optional but highly recommended attaches a descriptor to the state The same formatting options are available as with the star descriptor Finally the attributes keyword specifies state attributes At present two attributes are defined for all states A CONSTANT and A_SETTABLE along with their comple ments A_NONCONSTANT and A_NONSETTABLE If a state has the A_CONST
182. ft operator const xxx amp scalar const XXXMatrix amp matrix Example A 5 B Return a new matrix that has entries of the source matrix added to a scalar value operator const XXXMatrix amp matrix const xxx amp sca lar Example A B 5 Return a new matrix that has entries of the source matrix added to a scalar value This is the same as the previous operator but with the scalar on the right operator const XXXMatrix amp left const XXXMatrix amp right Example A B C Return a new matrix which is the difference of the first two The left and right source matrices must have the same dimensions operator const xxx amp scalar const XXXMatrix amp matrix Example A 5 B Return a new matrix that has the negative of the entries of the source matrix added toa scalar value operator const XXXMatrix amp matrix const xxx amp sca lar Example A B 5 Return a new matrix such that each entry is the corresponding entry of the source mat rix minus the scalar value operator const XXXMatrix amp left const XXXMatrix amp right Example A B C Return a new matrix which is the matrix product of the first two The left and right source matrices must have compatible dimensions i e A numCols B numRows operator const xxx amp scalar const XXXMatrix amp matrix Example A 5 B Department of EECS The Almagest 4 29 Return
183. g a customized star If the interconnection topology is neither fully connected nor shared bus in particular the communication scheduling should be designed in the target which makes a target design more complicated So the best way to design a target is to look at an already implemented tar get such as CGCMultiTarget class in the CGC domain 13 4 Schedulers Given a Universe of functional blocks to be scheduled and a Target describing the topology and characteristics of the single or multiple processor system for which code is to be generated it is the responsibility of the Scheduler object to perform some or all of the following functions e Determine which processor a given invocation of a given Block is executed on for multiprocessor systems e Determine the order in which actors are to be executed on a processor e Arrange the execution of actors into standard control structures like nested loops In this section we explain different scheduling options and their effect on the generated code 13 4 1 Single processor schedulers For targets consisting of a single processor we provide three different scheduling techniques The user can select the most appropriate scheduler for a given application by set ting the loopingLevel target parameter In the first approach loopingLevel DEF which is the default SDF scheduler we conceptually construct the acyclic precedence graph APG corresponding to the system and generate
184. g example out set_overflow Fix ovf_saturate The member function Ptolemy Last updated 10 10 97 4 14 Data Types int overflow const returns the overflow type This returned result can be compared against the above enumerated values Overflow types may also be specified as strings using the method void set_ovflow const char overflow type the overflow_type argument may be one of saturate zero_saturate wrapped or warning The rounding behavior of a Fix value may be set by calling void set_rounding int value If the argument is false or has the value Fix mask_truncate truncation will occur If the argument is nonzero for example if it has the value Fix mask_truncate_round round ing will occur The older name Set_MASK is a synonym for set_rounding The following functions access the error bits of a Fix result int ovf_occurred const int invalid const int dbz const The first function returns TRUE if there have been any overflows in computing the value The second returns TRUE if the value is invalid because of invalid precision parameters or a divide by zero The third returns TRUE only for divide by zero 4 3 Defining New Data Types The Ptolemy heterogeneous message interface provides a mechanism for stars to trans mit arbitrary objects to other stars Our design satisfies the following requirements e Existing stars stars that were written before the message interface was a
185. galaxy DataFlowStar star LOG_NEW threads new ThreadList Create Threads for all the Stars while star DataFlowStar nextStar NULL LOG_NEW SyncDataFlowProcess p new SyncDataFlowProcess star start iteration threads gt add p p gt initialize It is often desirable to have a partial execution of a process network The class Sync DataFlowProcess which is derived from DataFlowProcess supports this by synchro nizing the execution of a thread with the iteration counter that belongs to the PNScheduler The run methods of PNScheduler and SyncDataFlowProcess imple ment this synchronization The PNScheduler run method shown below increments the iteration count to give every process an opportunity to run The SyncDataFlowProcess run method shown below ensures that the number of invocations of the star s run method does not exceed the iteration count Run or continue the simulation int PNScheduler run if SimControl haltRequested galaxy Error abortRun cannot continue return FALSE while currentTime lt stopTime amp amp SimControl haltRequested Notify all threads to continue CriticalSection region start gt monitor iterationt t start gt notifyAll PNThread runAll Ptolemy Last updated 4 17 97 10 14 PN domain while PNGeodesic blockedOnFull gt 0 amp amp SimControl haltRequested i
186. ge 4 40 provide a particularly rich set of examples The matrix classes described on page 4 21 are also good examples The matrix classes are recognized in the Ptolemy kernel and supported by pigi and ptlang 1 The reason for this aggressive reclamation policy both here and in other places is to minimize the number of no longer needed messages in the system and to prevent unnecessary clones from being generated by writableCopy by eliminating references to Message objects as soon as possible U C Berkeley Department of EECS The Almagest 4 19 defstar name PackInt domain SDF desc Accept integer inputs and produce IntVecData messages defstate name length type int default 10 desc number of values per message input name input type int output name output type message ccinclude Message h IntVecData h start input setSDFParams int length int length 1 go int 1 length IntVecData pd new IntVecData l Fill in message input 0 is newest must reverse for int i 0 i lt 1 itt pd gt data l i 1 int input i Envelope pkt pd output 0 lt lt pkt Since this is an SDF star it must produce and consume a constant number of tokens on each step so the message length must be fixed though it is controllable with a state See Setting SDF porthole parameters on page 7 1 for an explanation of the setSDFParams method
187. gets The CGMult iTarget class has a set of parameters to select parallel scheduling options See the schedulers section for a detailed discussion on par allel schedulers The selected parallel scheduler schedules the program graph onto the child targets and the scheduling results are displayed on a Gantt chart The parent multiprocessor target collects the code from each of the child targets after the child targets have generated code based on the scheduling results By default it merges all of the child processor code into a single file If separate files are required then one approach is to create separate files with names derived from the child target names and write the code to these files in the frame Code method of the multi target Interprocessor communication IPC stars are created by the multiprocessor target by the methods createSend and createReceive These stars are spliced in to the sub Ptolemy Last updated 10 17 97 13 20 Code Generation galaxies that are created and handed down to the child targets Typically these methods just create the appropriate IPC star and return a pointer to the object created Each send receive pair is matched in the pairSendReceive method Typically this might involve setting pointers in the send receive pair to point to each other There is no preprocessor for targets like ptlang for stars Designing a customized multiprocessor target therefore is a bit complicated compared to designin
188. group of ports type data type of output particles descriptor summary of the function of the output numtokens number of tokens produced by the port use ful only for dataflow domains name the name of the state variable type data type of the state variable default the default initial value always a string descriptor summary of the function of the state attributes hints to the simulator or code generator TABLE 2 2 Some items used in defining a star have subitems These are described here Ptolemy Last updated 8 26 97 2 12 Writing Stars for Simulation fix_matrix_env The type item may be omitted the default type is anyt ype For more information on all of these please see chapter 4 Data Types The numtokens keyword it may also be written num or numTokens specifies the number of tokens consumed or produced on each firing of the star This only makes sense for certain domains SDF DDF and BDF in such domains if the item is omit ted a value of one is used For stars where this number depends on the value of a state it is preferable to leave out the numtokens specification and to have the setup method set the number of tokens in the SDF domain and most code generation domains this is accomplished with the setSDFParams method This item is used primarily in the SDF and code generation domains and is discussed further in the doc umentation of those domains There is an alternative syntax for the type field
189. h int intBits PortHole amp myPortHole Example FixMatrix A 2 2 14 4 Create a FixMatrix with the given dimensions such that each entry is a fixed point number with precision as given by the length and int Bits inputs and initialized with the values that are read from the parti cles contained in the porthole myPortHole FixMatrix int numRow int numCol int length int intBits Fix ArrayState dataArray Example FixMatrix A 2 2 14 4 Create a FixMatrix with the given dimensions such that each entry is a fixed point number with precision as given by the length and int Bits inputs and initialized with the values in the given FixArray State There are also special copy constructors for the FixMat rix class that allow the programmer to specify the precision of the entries of the FixMatrix as they are copied from the sources These copy constructors are usually used for easy conversion between the other matrix types U C Berkeley Department of EECS The Almagest 4 25 The last argument specifies the type of masking function truncate rounding etc to be used when doing the conversion FixMatrix const XXXMatrix amp src int length int intBits int round Example FixMatrix A CxMatrix 4 14 TRUE Create a FixMatrix with the given dimensions such that each entry is a fixed point number with precision as given by the length and int Bits arguments Each entry of the new matrix is copied from the co
190. h output is embedded in the input starting at location loc At the buffer allocation stage we do not allo cate buffers for the outputs but instead reuse the input buffer for all outputs This feature however has not yet been implemented in the assembly language generation domains A Collect star embeds its inputs in its output buffer setup MPHIter iter input Ptolemy Last updated 10 17 97 13 16 Code Generation CGCPOortHole p int loc 0 while p CGCPortHole iter 0 output embed p loc loc p gt numXfer Other examples of embedded relationships are UpSample and DownSample stars One restriction of embedding however is that the embedded buffer must be static Automatic insertion of Spread and Collect stars in multi processor targets refer to the target section guarantees static buffering If there is no delay i e no initial token in the embedded buffer static buffering is enforced by default A buffer is called static when a star instance consumes or produces data in the same buffer location in any schedule period Static buffering requires a size that divides the least common multiple of the number of tokens consumed and produced if such a size exists that equals or exceeds the maximum number of data values that will ever be in the buffer static allocation is performed 13 3 Targets A code generation Domain is specific to the language generated such as C CGC Sproc assembly cod
191. he name of a state that has the current value 1 Sref name offset Returns a reference to an array state or a port with an offset that is not negative For a port it is functionally equivalent to nameZoffset in SDF simulation stars Sval state name Returns the current value of the state If the state is an array state the macro will return a string of all the elements of the array spaced by the new line char acter The advantage of not using ref macro in place of va1 is that no addi tional target resources need to be allocated Ssize name Returns the size of the state port argument The size of a non array state is one the size of a array state is the total number of elements in the array The size of a port is the buffer size allocated to the port The buffer size is usually larger than the number of tokens consumed or produced through that port SstarName Returns the instantiated name of the star without galaxy or universe names SfullName Returns the complete name of the star including the galaxies to which it belongs SstarSymbol name Returns a unique label in the star instance scope The instance scope is owned by a particular instance of that star in a graph Furthermore the scope is alive across all firings of that particular star For example two CG stars will have two distinct star instance scopes As an example we show some parts of ptlang U C Berkeley Department of EECS The Almagest 13 9 file
192. he size fullSize and startPos members varies within each subclass Typically the size variable holds the number of pixels that an object is storing If an object is not produced by fragment then size fullSize If the object is produced by a fragment call size may be less than or equal to fullSize An objects s fullSize may be bigger or smaller than width height It would be bigger for example in DCTIm U C Berkeley Department of EECS The Almagest 4 41 age where the amount of allocated storage must be rounded up to be a multiple of the block size It would be smaller for example for an object that contains run length coded video The frameld variable is used during assembly Fragments with the same ramera s are assembled into the same image So it is important that different frames from the same source have different framelds The comparison functions lt gt etc compare two objects frameld s They can be used to resequence images or to sort image fragments The copy constructor and clone methods have an optional integer argument If a non zero argument is provided then all state values of the copied object are copied to the created object but none of the image data is copied If no argument or a zero argument is provided then the image data is copied as well Classes derived from BaseImage should maintain this policy The Grayrmage class derived from BaseImage is us
193. header files For instance the entry ccinclude pt_fstream h will permit the star to create instances of the basic stream classes described below in the body of functions that are defined in the star If the user wishes to create such an instance as a private protected or public member of the star then the header file needs to be included in the h file specified as done in the line hinclude pt_fstream h in the Printer star defined on page 2 28 The source code for most of classes and functions described in this section can be found in SPTOLEMY src kernel The source code is the ultimate reference Moreover since this directory is automatically searched for include files when a star is dynamically linked no special effort is required to specify where to find the include files 3 2 Handling Errors Uniform handling of errors is provided by the Error class The Error class provides four static methods summarized in table 3 1 From within a star definition it is not necessary to explicitly include the Error h header file A typical use of the class is shown below Error abortRun this this message is displayed The notation Error abortRun is the way static methods are invoked in C without having a pointer to an instance of the Error class The first argument tells the error class which object is flagging the error this is strongly recommended The name of the object will be printed along w
194. hen in the go method we use sum to calculate the result value thus guaranteeing that the desired precision and overflow handling are enforced For example go sum setToZero sum Fix input1 0 checkOverflow sum sum Fix input2 0 checkOverflow sum output 0 lt lt sum The checkOverflow method is inherited from SDFFix The protected member sum is an uninitialized Fix object until the begin method runs In the begin method it is given the precision specified by OutputPrecision The go method initializes it to zero If the go method had instead assigned it a value specified by another Fix object then it would acquire the precision of that other object at that point it would be initialized Assignment and overflow handling Once a Fix object has been initialized its precision does not change as long as the object exists The assignment operator is overloaded so that it checks whether the value of the object to the right of the assignment fits into the precision of the left object If not then it takes the appropriate overflow response is taken and set the overflow error bit If a Fix object is created using the constructor that takes no arguments as in the pro tected declaration above then that object is an uninitialized Fix it can accept any assign ment acquiring not only its value but also its precision and overflow handler The behavior of a Fix object on an overflow depends on the specifications and the
195. hod causes all threads to begin or continue execution virtual void terminate 0 This method causes execution of the thread to terminate The class Pt Thread has one protected method virtual void run 0 This method defines the functionality of the thread It is invoked when the thread begins execution 10 2 2 The PosixThread Class The class PosixThread provides an implementation for the interface defined by Pt Thread It does not implement the pure virtual method run so it is not possible to create an instance of PosixThread This class adds one protected method and one protected data member to those already defined in Pt Thread static void runThis PosixThread This static method invokes the run method of the referenced thread This provides a C interface that can be used by the POSIX thread library pthread_t thread A handle for the POSIX thread associated with the PosixThread object pthread_attr_t attributes A handle for the attributes associated with the POSIX thread int detach A flag to set the detached state of the POSIX thread The initialize method shown below initializes attributes then creates a thread The thread is created in a non detached state which makes it possible to later synchronize with the thread as it terminates The controlling thread usually the main thread invokes the terminate method of a thread and waits for it to terminate The priority and scheduling pol icy for the t
196. homogenous single processor targets of arbitrary type connected in either a fully connected or shared bus topology with parametrized commu nication costs These targets however use only the CG domain stars and hence do not actu ally generate code recall that CG domain stars are comment generators Some other actual implementations of multiprocessor systems include the CM 5 CGCCm5Target in the CGC domain the Sproc multiprocessor DSP Mur93 and the ordered transaction architecture Sri93 Refer to the CG56 domain documentation for CG56MultiSim target or the CGC domain documentation for CGCMultiTarget class as examples of concrete multi proces sor targets In this section we concentrate on the abstract multiprocessor target classes that are in the PTOLEMY src domains cg targets directory CGMultiTarget is the base target class for all homogeneous targets By default it models a fully connected multiprocessor architecture when a processor wants to communi cate with another processor it can do immediately The scheduleComm method returns the time when the required communication is scheduled In the CGMultiTarget class it returns the same time as when the communication is required On the other hand cGShared Bus which is derived from the CGMultiTarget class is the base target class for all multi processor targets having a shared bus topology In the CGSharedBus class the scheduleComm method schedules the r
197. hread are inherited from the thread that creates it usually the main thread A func tion pointer to the runThis method and the this pointer which points to the current PosixThread object are passed as arguments to the pthread_create function This cre ates a thread that executes runThis and passes this as an argument to runThis Thus the run method of the PosixThread object is the main function of the thread that is created The runThis method is required because it would not be good practice to pass a function pointer to the run method as an argument to pthread_create Although the run method has an implicit this pointer argument by virtue of the fact that it is a class method this is really an implementation detail of the C compiler By using the runThis method we make the pointer argument explicit and avoid any dependencies on a particular compiler implementa tion void PosixThread initialize U C Berkeley Department of EECS The Almagest 10 5 Initialize attributes pthread_attr_init amp attributes Detached threads free up their resources as soon as they exit non detached threads can be joined detach 0 pthread attr setdetachstate amp attributes amp detach New threads inherit their priority and scheduling policy from the current thread pthread attr setinheritsched amp attributes PTHREAD INHERIT SCHED Set the stack size to something reasonably large 32K pthrea
198. icated functions can be realized by a galaxy Nonetheless no star library can possibly be complete you may need to design your own stars The Ptolemy preprocessor language makes this easier than it could be This chapter is devoted to the use of the preprocessor language Newly designed stars can be dynamically linked into Ptolemy avoiding frequent recompilation of the system If the new stars are generic and useful however it might be bet ter to add them to the list of compiled in stars and rebuild the system See Creating Custom Versions of pigiRpc on page 1 6 2 2 Adding stars dynamically to Ptolemy To get a quick sense of what it means to create a new star you can use one of the exist ing stars as a template Create a new directory in which you have write permission Copy the source code for an existing Ptolemy star For example cd my_directory cp SPTOLEMY src domains sdf stars SDFSin pl SDFMyStar pl chmod w SDFMyStar pl The p1 extensions on the file names stand for Ptolemy language or preproces sor language The file name must be of the form DomainStarname p1 for dynamic linking and the look inside command to work The last command just ensures that you can modify the file Edit the file to change the name of the star from Sin to MyStar This is necessary so that the name does not conflict with the existing Sin star in the SDF domain You can now dynamically link your new star Start pigi the graphica
199. ice that the procedure body is enclosed quotation marks U C Berkeley Department of EECS The Almagest 5 11 5 4 Creating new stars derived from the TclScript star A large number of useful stars can be derived from the TclScript star The TkShowValues star used in example 1 on page 5 2 is such a star That star takes inputs of any type and displays their value in a window that is optionally located in the control panel It has three parameters settable states label A string valued parameter giving a label to identify the display put_in_control_panel A Boolean valued parameter that specifies whether the display should be put in the control panel or in its own window wait between outputsA Boolean valued parameter that specifies whether the execu tion of the system should pause each time a new value is dis played If it does then a mouse click in the display restarts the system Conspicuously absent is the fcl_file parameter of the TclScript star from which this is derived The file is hard wired into the definition of the star by the following C statement included in the setup method tcl_file SPTOLEMY src domains sdf tcltk stars tkShowValues tcl The parameter is then hidden from the user of the star by the following statement included in the constructor tcl_file clearAttributes A_SETTABLE Thus the user sees only the parameters that are defined in the derived star This is a key part of cus
200. ies ds se eer seg hens 13 13 A CONSTANT oaren ee se ee ee 13 13 A GLOBAL ee GE Ge eg 13 12 A LOCA nF SENSE RE RE ES De ge es 13 12 A MEMORY ee esse se ese se ee ee ke ee ee 13 13 A NOINIT ies EE EE ES EG DE RE ev 13 13 A NONCONSTANT ees se ees see 13 13 A NONSETTABLE ees sees ese ee ees see 13 13 APRIVATES SEGE GE ee 13 12 ARAM nonne a es 13 14 A SETTABLE ees esse sesse 13 13 13 13 A SHARE D se oes Re ge iene ee dee oge ee 13 12 A UMEM ii iese see es eg ee aig aie ein 8 16 1 PSR MIBI ei es ie ee Re 15 1 16 1 A YMEM RA n Ee NAR Ee 15 1 P BMEM ie GE sei RS 16 1 Pe GIR tese Vrese egg Ee Sk se 13 14 P NOINIT Eie SEGE GED Ee GER EVER as 13 14 P SHARED sessies sees ge ese ee Se Ee SR ee pe de 13 14 P SYMMETRIC eee esse esse ee ese ee ee se ee 13 14 P UMEM Eis tree Es EE a Ee Ee 16 1 PE XMEM EE Si Ee ee ee 15 1 PLY MEM ie sers ees see Eg ees Ee Eve GE Ge events 15 1 attribute A BMEM ie ese se ee ee se ee ee ee 16 1 attribute A UMEM i dese ee se ee ee se ee ee ee 16 1 attribute A XMEM eee sees ese se ee ee ee ee ee ee 15 1 attribute A YMEM iese se ee se ee se ee ee ee 15 1 AttriDUteS ee ee ee ee ee ee ee ee Re ee ee 13 12 author ptlang directive ee ee ee ee 2 6 2 8 B bad format parameters Pix GLASS ESEG EE EE DS EE cite EE 4 4 BarGraph class sees isles dei ich Bas ses ER arcs 3 4 baseAddr method ee ee ee 13 12 Baselmage Class ee ee ee ee ee ee 4 40 BDFPortHole class
201. ified port In the above example the setup method specifies that the star should first wait fora control input When a cont rol input arrives the go method reads the control value and uses wait For to specify that the star should fire next when the specified number of inputs have arrived at input The private member readyToGo is used to keep track of which input we are wait ing for The line for int i num i gt 0 i input receiveData causes the appropriate number of inputs given by num to be consumed The next example is a DDF star with a dynamic output porthole a DownCounter star defstar name DownCounter domain DDF desc Count down from the input value to zero input name input type int output name output type int num 0 go input receiveData for int i int input 0 1 i gt 0 i output S0 lt lt i output sendData U C Berkeley Department of EECS The Almagest 8 3 The DownCounter star has a dynamic output porthole that will generate the down counter sequence of integer data starting from the value read through the input porthole The code in the go method is self explanatory It is possible if a bit strange for a star to alternate between SDF like behavior and DDF like behavior To assert that its next firing should be under SDF rules the star calls The following example shows a star that uses the same input for control and data An int
202. ill then be deleted automatically It is possible for an Envelope to be empty If it is the empty method will return TRUE and the data field will point to a special dummy message with type DUMMY that has no data in it The dataType method of Envelope returns the datatype of the contained Message object the methods asInt asFloat asComplex and print are also passed through in a similar way to the contained object Two Envelope methods are provided for convenience to make type checking simpler typeCheck and typeError A simple example illustrates their use if envelope typeCheck IntVecData Error abortRun this envelope typeError IntVecData return The method t ypeCheck calls isA on the message contents and returns the result so an error will be reported if the message contents are not Int VecData and are not derived from Int v ecData Since the above code segment is so common in stars a macro is included in Mes sage h to generate it the macro TYPE CHECK envelope IntVecData expands to essentially the same code as above The typeError method generates an appro priate error message Expected message type arg got type To access the data two methods are provided myData and writableCopy The myData function returns a pointer to the contained Message derived object The data pointed Pt
203. ime needed to execute the main loop code of a code generation star in processor cycles or instruction steps These num bers are used by the parallel schedulers In the assembly code generation domains the integer returned is the main loop code execution time in DSP instruction cycles The better the exec Time estimates are for each star the more efficient the parallel schedule becomes If a star is invoked more than once during an iteration period the precedence relation between stars should be known to the parallel scheduler If there is no precedence relation between invocations the parallel scheduler will try to parallelize them By default there is a precedence relation between invocations for any star this is equivalent to having a self loop To assert that there is no such self loop for a star we have to call the noInternalState method in the constructor constructor noInternalState It is strongly recommended that the star designer determine whether the star is parallelizable or not and call noInternalState if it is U C Berkeley Department of EECS The Almagest 13 3 The CGStar class is the base class for all code generation stars such as high level lan guage code generation stars and assembly language code generation stars In this section we will explain the common features that the CGStar class provides for all derivative code gen eration stars As a simple example to see how code generation
204. in Ptolemy The available colors can be found in the file SPTOLEMY 1lib tcl ptkColor tcl To access this color database use the Tcl function ptkColor name which returns a color defined in terms of RGB components This color can be used anyplace that Tk expects a color If the given name is not in the color database the color returned is black 5 6 Writing Tcl stars for the DE domain In the discrete event DE domain stars are fired in chronological order according to the time stamps of the new data that has arrived at their input ports The Tcl interface class TclStarIfc which was originally written with the SDF domain in mind works well for some types of DE stars Specifically any star with an input in the DE domain can use this class effectively Consequently a basic Tcl Tk star TclScript has been written for the DE domain The TclScript star can have any number of input or output portholes As of this writing it will not work if it is instantiated with no inputs The problem is that with no inputs there will be no events to trigger a firing of the star This will be corrected in the future U C Berkeley Department of EECS Chapter 6 Using the Cluster Class for Scheduling Authors Jos Luis Pino 6 1 Introduction The Ptolemy kernel has three main facilities to aid in the implementation of schedul ing algorithms generic clustering mechanisms graph iterators and classical graph algo rithms In this chapt
205. in a subpanel of the control panel for the system Suppose we spec ify the following Tcl script for the Tcl Script star set s SptkControlPanel middle button_S starID if winfo exists Ss button Ss text PUSH ME pack append SptkControlPanel middle s top bind s lt ButtonPress 1 gt setOutputs_SstarID 1 0 bind s lt ButtonRelease 1 gt setOutputs_SstarID 0 0 setOutputs_SstarID 0 0 unset s This script creates a pushbutton in the control panel When the button is depressed the star outputs the value 1 0 When the button is released the star outputs value 0 0 The resulting control panel is shown below A Bun tel script deme Control panel for tel_script_demo when to stopsfaaeod r penug GO Raru PAUSE tSpare STOF Escapes FUSH ME inpats to the ThShow Wales star 0 0 OPSHrss While the system is running depressing the button labeled PUSH ME will cause the value displayed at the bottom to change from 0 0 to 1 0 Releasing the button will change the value back to 0 0 The lines in the Tcl script are explained below U C Berkeley Department of EECS The Almagest 5 3 set s SptkControlPanel middle button_S starID This defines a Tcl variable s whose value is the name of the window to be used for the button The first part of the name SptkControlPanel is a global variable giv ing the name of the control panel window itsel
206. include HTML format directives The Tycho system includes an HTML viewer that can be used to display star docu mentation The HTML output of ptlang can be viewed by any HTML viewer but certain features such as the lt tcl gt lt tcl gt directive are only operational when viewed with Tycho For complete documentation for the Tycho HTML viewer see the HTML viewer Help menu This item is used to define a state or parameter Recall that by definition a parameter is the initial value of a state Here is an example of a state definition state name gain type int default 10 desc Output gain attributes A_CONSTANT A_SETTABLE There are five types of subitems that may appear in a state statement in any order The name field is the name of the state the type field is its type which may be one of int float string complex fix intarray floatarray complexarray precision or stringarray Case is ignored for the type argument The default item specifies the default initial value of the state its argument is either a string enclosed in quotation marks or a numeric value The above entry could equivalently have been written default 1 0 Furthermore if a particularly long default is required as for example when initializing an array the string can be broken into a sequence of strings The following example shows the default for a ComplexArray Last updated 8 26 97 2 10 Writing Stars
207. ined A_CIRC If set the memory for this state is allocated as a circular buffer whose address is aligned to the next power of two greater than or equal to its length A_CONSEC If set allocate the memory for the next state in this star consecutively starting immediately after the memory for this star A_MEMORY If set memory is allocated for this state A_NOINIT If set the state is not be automatically initialized The default is that all states that occupy memory are initialized to their default values A_REVERSE If set write out the values for this state in reverse order A_SYMMETRIC If set and if the target has dual data memory banks e g M56000 Analog Devices 2100 etc allocate a buffer for this object in both memories Ptolemy Last updated 10 17 97 13 14 Code Generation Given these attributes technically the above also have bit representations of the form AB_xxx A_xxx just turns the bit AB xxx on the following attributes correspond to requests to turn some attributes off and to turn other attributes on For example A_ROM Allocate memory for this state in memory and the value will not change A_MEMORY and A_CONSTANT set A_RAM A_MEMORY set A_CONST not set For portholes in code generation stars we have P_CIRC If set then allocate the buffer for this porthole as a circular buffer even if this is not required because of a
208. ing procedures when using non COFF assemblers like the TI DSK assembler or defining tables of coefficients in program memory as an example the C50 instruction macd needs one of the operands to be in program mem ory 16 5 Symbols The DSKC50 targets defines certain symbols that are meant to be unique They are AIC_INIT SETUPX SETUPR XINT RINT and TINT The C50Sin star defines a glo bal symbol SINTBL used to store a sine table that is shared by all C50Sin stars The user should avoid redefining these symbols in the output assembly file 16 6 Reserved Memory The DSKC50 target reserves the last 9 words in DARAM block 1 to store data needed to configure the Analog Interface Chip in the DSK board U C Berkeley Department of EECS Chapter 17 Creating New Domains Authors Mike Chen Christopher Hylands Thomas M Parks Other Contributors Wan Teh Chang Michael C Williamson 17 1 Introduction One of Ptolemy s strengths is the ability to combine heterogeneous models of compu tation into one system In Ptolemy a model of computation corresponds to a Domain The code for each Domain interacts with the Ptolemy kernel This overview describes the general structure of the various classes that are used by a Domain in its interaction with the kernel The Ptolemy User s Manual has a more complete overview of this information A functional block such as an adder or an FFT is called a Star i
209. int length i output int length i 1 lt lt pd datal i Because the domain is SDF we must always produce the same number of outputs regardless of the size of the messages The simple approach taken here is to require at least a certain amount of data or else to trigger an error and abort the run The operations here are to declare an envelope get the data from the particle into the envelope with getMessage check the type and then access the contents Notice the cast operation this is needed because myData returns a const pointer to class Message It is important that we converted the pointer to const IntVecData and not IntVecData because we have no right to modify the message through this pointer Many C compilers will not warn by default about casting away const we recommend turning on compiler warnings when compiling code that uses messages to avoid getting into trouble for g say Wcast agual for cfront derived compilers say w If we wished to modify the message and then send the result as an output we would call writableCopy instead of myData modify the object then send it on its way as in the U C Berkeley Department of EECS The Almagest 4 21 previous star 4 4 The Matrix Data Types The primary support for matrix types in Ptolemy is the PtMat rix class PtMatrix is derived from the Message class and uses the various kernel support functions for working with the Message data type
210. ion void append Pointer p add the element p to the end of the list Pointer elem int n return the n th element on the list zero if there are fewer than n eurn T emp Dar Pointer getAndRemove return and remove the first element on the list Pointer getTailAndRemove return and remove the last element on the list return Pointer head return the first element on the list zero if empty t member 1 return l if the list has a pointer equal to p 0 if not void prepend add the element p to the beginning of the list t remove 1 if the list has a pointer equal to p remove it and return l 0 if not size return the number of elements on the list Pointer tail return the last element on the list zero if empty TABLE 3 10 The most useful basic list structure defined in the Ptolemy kernel Ptolemy Last updated 8 26 97 3 12 Infrastructure for Star Writers first out LIFO queue The second implements a stack which is also a LIFO queue Queue class include DataStruct h method description Pointer getHead return and remove the first element on the list return zero if empty Pointer getTail return and remove the last element on the list return zero if empty void initialize remove all elements from the list add the element p to the beginning of the list void putTail 1 t add the element p to the end of the list p int size
211. ion the OverflowHandler will be called protected Fix fixiIn out begin SDFFix begin if int ArrivingPrecision fixIn Fix const char InputPrecision if fixIn invalid Error abortRun this Invalid InputPrecision out Fix const char OutputPrecision if out invalid Error abortRun this Invalid OutputPrecision out set_ovflow const char OverflowHandler if out invalid Error abortRun this Invalid OverflowHandler go all computations should be performed with out since that is the Fix variable with the desired overflow handler out Fix gain if int ArrivingPrecision U C Berkeley Department of EECS The Almagest 4 9 out Fix input 0 else fixIn Fix input 0 out fixin checkOverflow out output 0 lt lt out a wrap up method is inherited from SDFFix if you defined your own you should call SDFFix wrapup Note that the SDFGainFix star and many of the Fix stars are derived from the star SDFFix SDFFix implements commonly used methods and defines two states OverflowHandler selects one of four overflow handlers to be called each time an overflow occurs and Repor tOverflow which if true causes the number and percentage of overflows that occurred for that star during a simulation run to be reported in the wrapup method Constructors Fix Create a Fix num
212. ion num ber 1 25 You can now edit the file safely nobody else will be allowed by sccs to edit it When you are done and have fully tested your changes and obtained clearance from the Ptolemy group if necessary you can check the file back in o sccs delget DDFRepeater pl Comments You should enter an explanation of your changes If you wish to nullify your changes restor U C Berkeley Department of EECS The Almagest 1 19 ing the official version sccs unedit DDFRepeater pl and if you wish to create a new file and put it under SCCS control sccs creat fi NewFileNam 1 6 Building standalone programs that use Ptolemy libraries Sometimes it is necessary to create small standalone programs that use part of the Ptolemy libraries Examples of this are the desire to use Ptolemy kernel classes such as StringList or the need to isolate an obscure bug or memory leak The PTOLEMY mk standalone mk file provides the make definitions to make this possible This file provides make rule definitions to build various binaries some using the Pure Sofware Inc utilities The usage for this makefile is make f SPTOLEMY mk standalone mk stars mk_variable_defs file name suffix Where stars mk_variable_defs is zero or more makefile variables used in SPTOLEMY mk stars mk such as SDF 1 filename is the base name of the file to be com piled and the basename of the output file and suffix is one of the forms listed
213. is process an event is placed on the feedback arc by the DERepeatStar begin method before the scheduler runs The DERepeat Star class can also be used for other purposes besides event genera tion For example a sampler star might be written to fire itself at regular intervals using the refireAtTime method Another strangely named method canGetFired is seldom used in the star defini tions The method checks for the existence of a new feedback event and returns TRUE if it is there or FALSE otherwise The internal feedback arc consists of an input and an output porthole that are automat ically created and connected together with a delay marker added to prevent the scheduler from complaining about a delay free loop This effectively assumes that refire requests will always be for times greater than the current time Sometimes the programmer of a star derived from DERepeat Star needs to be explic U C Berkeley Department of EECS The Almagest 12 11 itly aware of these portholes In particular they should be taken into account when consider ing whether a star is delay type Setting delayType in a DERepeatStar derivative asserts that not only do none of the star s visible input portholes trigger output events with zero delay but refire events do not either Frequently this is a false statement It s usually safer to write triggers directives that indicate that specific input portholes cannot trigger zero delay out
214. ith the error message Note that the abortRun call does not cause an immediate halt It simply marks a flag that the scheduler must test for The table uses standard C notation to indicate how to use the methods The type of the return value and the type of the arguments is given together with an explanation of each When an argument has the annotation something then this argument is optional If it is 3 2 Infrastructure for Star Writers omitted from the call then the value used will be something Error class include Error h method description static void abortRun signal a fatal error and request a halt to the run const NamedObj amp the object triggering the error obj const char the error message const char optional additional message to concatenate to the error mes sage char optional additional message to concatenate to the error mes sage static void abortRun signal a fatal error and request a halt to the run const char the error message const char optional additional message to concatenate to the error mes sage char optional additional message to concatenate to the error mes sage tic void error signal an error without requesting a halt to the run bes tic void message output a message to the user sae tic void warn generate a warning message bete TABLE 3 1 A summary of the static methods in the Error class Each method
215. itialize InterpGalaxy initialize Galaxy initSubblocks DataFlowStar initialize Block initialize PortHole initialize Geodesic initialize Ptolemy Initialize the galaxy Causes the initialization of delays and the setup of bus widths Calls initialize of each star This is a general initialize function for data flow stars Your own Star class might redefine it Sets the number of input Ports and clears some parameters Initializes the PortHoles and States of the Block Star Calls the user defined setup function of each star after the portholes and geodesics have been initialized General PortHole initialization again you can redefine it fora domain specific PortHole Resolves the type of Particles to be sent Allocates a buffer and a Plasma Request empty Particles from the Plasma to initialize the buffer General Geodesic initialization Last updated 10 10 97 17 8 Creating New Domains called by output PortHole only Clears the buffer and adds any initial Particles for delays After the schedule is set up and all the actors in the Universe have been initialized the flow of control is as follows PTcl run PTcl computeSchedule Described above PTcl cont universe gt setStopeTime Used to set the number of iteration
216. ive are summarized in table 2 2 together with subitems of other directives input output inout inmulti outmulti inoutmulti These keywords are used to define a porthole which may be an input output inout bidirectional porthole or an input output or inout multiporthole Bidirectional ports are not supported in most domains The Thor domain is an exception Like state it contains subitems Here is an example input name signalIn type complex numtokens 2 desc A complex input that consumes 2 input particles Here name specifies the porthole name This is a required item type specifies the particle type The scalar types are int float fix complex message or any type Again case does not matter for the type value The matrix types are int_matrix_env float matrix env complex matrix env and sub item summary reguired page inmulti name name of the port or group of ports inout type data type of input amp output particles inoutmulti i descriptor summary of the function of the input input numtokens number of tokens consumed by the port use ful only for dataflow domains method name the name of the method yes virtual method access private protected or public no inline method pure method pure virtual method inline virtual method arglist the arguments to the method no type the return type of the method no code C code defining the method if not pure name name of the port or
217. ived from Message and Particle It contains an InfString object InfString is a version of StringList that allows limited modification and is used to interface C to Tcl Again It uses the reference counting mechanism of the Message and Envelope classes to ensure that strings are not deleted until no longer needed St ringMes sage is currently very simple it adds the following functions to Message Constructors StringMessage Create a new string message an empty string StringMessage const char name Create a new string message with a copy of the given string The given string can be deleted since the new message does not reference it StringMessage const StringMessage amp src Create a new string message containing the same string as the given string message Again the string is copied Operations StringList print Return the string contained in this message in a StringList object 4 6 Writing Stars That Manipulate Any Particle Type Ptolemy allows stars to declare that inputs and outputs are of type ANYTYPE A star may need to do this for example if it simply copies its inputs without regard to type as in the case of a Fork Star or if it calls a generic function that is overloaded by every data type such as sink stars which call the print method of the type The following is an example of a star that operates on ANYTYPE particles defstar name Fork domain SDF desc Copy input particle
218. ized in table 3 7 These functions are for expanding file names that might begin with a refer ence to a user s home directory username or an shell environment variable SVARIABLE Also provided is a function for verifying that an external program to be invoked is available and a function for searching the user s path ordinary functions for path search include paths h method description int progNotFound flag an error and return TRUE if a program is not found char program the name of the program to find in the user s path char extramsg message to add to error message if the program isn t found const char pathSearch find a file in a Unix style path returning the direc tory name char file file name to find in the path char path 0 if non zero the path to use instead of the user s path TABLE 3 7 Non class ordinary functions available in the Ptolemy kernel for certain pathname manipulations U C Berkeley Department of EECS The Almagest Two classes are provided for manipulating strings 1 3 9 classes are summarized in figure 3 8 StringList class StringL non method ist include StringList h description constructors can take any of the following possible argu ments return an empty StringList const StringList amp copy s and return a new identical StringList s cha ad return a StringList with
219. k CG 1 bar bin If you are going to do this often it may be useful to create a new directory in which to test this program In this directory execute the commands By having these ln s SPTOLEMY mk standalone mk makefile ln s SPTOLEMY mk standalone mk make template symbolic links you will not have to supply the make argument f SPTOLEMY mk standalone mk as before 1 6 2 Standalone example that tests a Scheduler Here is an example of a minimal file that can be used to call the setup in a Scheduler for instance If the file test AcyLoopSched cc contains include lt iostream h gt include Galaxy h include SDF Star h include AcyCluster h include Acy include SDF main Firs SDFStar Galaxy LoopScheduler h PortHole h t create a simple galaxy and some stars star 3 topGalaxy topGalaxy setDomain SDF topGalaxy setName topGalaxy topGalaxy addBlock star 0 star0 topGalaxy addBlock star 1 starl topGalaxy addBlock star 2 star2 Add ports to stars OutSDFPort p0 pl InSDFPo TE PP initialize the ports pO setPort outputl1 amp star 0 FLOAT 2 star 0 addPort p0 pl setPort output2 amp star 0 FLOAT 3 star 0 addPport pl p2 setPort input amp starl 1l FLOAT 3 U C Berkeley Department of EECS The Almagest 1 21 p3 setPort input amp starl 2 FLOAT 2 star
220. ke this indication either globally it never produces any immediate output event or on a port by port basis only some of its input ports can produce immediate outputs perhaps on only a subset of its output ports For managing time stamps the DESt ar class has two DE specific members arriv alTime and completionTime summarized in table 12 1 Before firing a star a DE sched uler sets the value of the arrivalTime member to equal the time stamp of the event triggering the current firing When the star fires before returning it typically sets the value of the complet ionTime member to the value of the time stamp of the latest event produced by the star The schedulers do not use the complet ionTime member however so it can actually be used in any way the star writer wishes DEStar also contains a field delayType anda method setMode that are used to signal the properties of the star as described below 12 2 1 Delay stars Delay stars manipulate time stamps Two types of examples of delay stars are pure delays and servers A pure delay star generates an output with the same value as the input sample but with a time stamp that is greater than that of the input sample The difference between the input sample time stamp and the output time stamp is a fixed user defined value Consider for example the Delay star defstar name Delay domain DE desc Delays its input by a fixed amount input name input type anytype o
221. ks EE EE ee eee 13 1 13 2 Writing Code Generation StarS sesse EE ee 13 2 Codeblocks 13 3 Codeblocks with arguments 13 5 In line codeblocks 13 7 Macros 13 8 Assembly PortHoles 13 12 Attributes 13 12 Possibilities for effective buffering 13 14 13 3 Tatdele ia EE RE GE Rd GR itech ime Baie te a 13 16 Single processor target 13 16 Assembly code streams 13 17 Multiprocessor targets 13 18 134 Schedulers eisini arkea as DEE ETE WES DEE DER GE 13 20 Single processor schedulers 13 20 Multiprocessor schedulers 13 21 13 5 Interface Issues iss EE cece eee eee 13 25 14 CGC DOMAIN EE DS ED es SG EE DE De GE nnna 14 1 14 1 Introduction sees Es EE eee ER EE ER ER EE EER EE 14 1 14 2 Code Generation Methods sis Es EE EE Ee see 14 1 14 3 Buffer Embedding 000 cece eek RR Rae 14 2 14 4 Command line Settable States is ss EE EE se Ee 14 3 C code generated to support command line arguments 14 3 Changes in pigiRpc to support command line arguments 14 4 Limitations of command line arguments 14 5 14 5 CGC Compile time Speed ss si kk RR RR RE 14 6 14 6 BDF Stars sis EREGAS GE nee OE eae 14 6 14 7 Tcl Tk Stats ii Ee EA ER wha ee ale be ORE SERE 14 7 14 8 Tycho Target es te tein ek GR od did WE RENE ER 14 8 15 GG56 DOMAIN si ss ED GR EE ee ee Ee de ve 15 1 15 1 vnirOAdUENOR Si REEDE GR EG RED DEE D ER GE teehee 15 1 15 2 Data Types wis uas deck ews ee RE ee RES Ve EN EE EN 15 1 15 3 Aftribute OS
222. l editor If you start pigi in your new directory you will get a blank init pal facet Place your mouse cur sor in this facet and issue the make star command the shortcut is A dialog box like 2 2 Writing Stars for Simulation the following will appear Make Star Star mant Dorsin Sik Star grc dir mel Tory Lorie kerf heal G Pathoame of Palette User pal Enter the name of the star MyStar its domain SDF the location of the directory that defines it such as user_name my_directory and the name of palette in which you would like its icon to appear user pal The star will be compiled and dynamically linked with the Ptolemy executable An icon for it will appear in the facet user pal Try using this in a simple system Three details about dynamic linking may prove useful e Ifthe name of the star source directory has a src component pigi will replace this with obj PTARCH depending on the type of machine you are running to get the name of the directory in which to store the object file This is especially useful if you are jointly doing development with others who use a different type of machine If there is no src component in the name then the object file is placed in the same directory with the source file e If there is a file named Makefile or makefile in the object file directory pigi will run the make program using the makefile to create the object file or make sure it is up to d
223. l function substChar defined in CGStar to return a differ ent character It is also possible to introduce processor specific macros by overriding the virtual function processMacro rooted in CGSt ar to process any macros it recognizes and defer substitution on the rest by calling its parent s processMacro method 13 2 5 Assembly PortHoles Here are some methods of class AsmPortHole that might be useful in assembly code generation stars bufSize Returns an integer the size of the buffer associated with the porthole baseAddr Returns the base address of the porthole buffer bufPos Returns the offset position in the buffer which ranges from 0 to buf Size l circAccessThisTime This method returns true nonzero if the data to be read or written on this execution wrap around so that accessing them in a linear order will not work 13 2 6 Attributes Attributes are assertions about the object they are applied to Both states and portholes can have attributes Attributes that apply to states have the prefix A_ Attributes that apply to portholes have the prefix p The following attributes are common to all code generation domains A_GLOBAL If set this state is declared global so that it is accessible everywhere Currently it is only supported in the CGC domain A_LOCAL This is the opposite of A_GLOBAL A SHARED A state that is shared among all stars that know its name type size A_
224. l macro described in the code genera tion macros section To add this code to the procedures stream in the initCode method of the star we can call either addProcedure sillyMultiply mult or addCode sillyMultiply procedures mult or getStream procedures gt put sillyMultiply mult As with addCode addProcedure returns a TRUE or FALSE indicating whether the code was inserted into the code stream Taking this into account we could have added the code line by line if addProcedure A silly function n mult addProcedure double SsharedSymbol silly mult double a double b n addProcedure Nn addProcedure tdouble m n addProcedure tm a b n addProcedure treturn m n addProcedure n 13 3 2 Assembly code streams Code is generated in the assembly language domains into four streams The streams inherited from CGTarget are the CODE and PROCEDURES stream The two new streams are Ptolemy Last updated 10 17 97 13 18 Code Generation mainLoop Code added to this stream comprises the main loop of the generated algorithm All addCode calls from a star s go function automatically are concatenated to this stream unless another stream is supplied as an argument trailer Code added to this stream comprises the wrapup section of the gener ated algorithm All addCode calls from a star s wrapup method auto matic
225. lay The pxgraph program and all its options are docu mented in the User s Manual An example of the output from pxgraph is shown in figure 3 1 The most useful methods of the class are summarized in table 3 2 Using the XGraph class involves an invocation of the initialize method some number of invocations of the addPoint method followed by an invocation of the termi A modulator deno ila dh lh EE FIGURE 3 1 An example of the output from the pxgraph program which can be accessed using the XGraph class Ptolemy Last updated 8 26 97 3 4 Infrastructure for Star Writers nate method Multiple data sets currently up to 64 may be plotted together They will each be given a distinctive color and or line pattern Within each data set it is possible to break the connecting lines between points by calling the newTrace method XGraph class include Display h method description void initialize start a fresh plot Block parent pointer to the block using the class int noGraphs the number of data sets to plot const char options to pass to the pxgraph program options nst char title to put on the graph itle const char name of a file to save data to saveFile 0 int ignore 0 number of initial points to ignore add the next point to the first data set with implicit x position y the vertical position add a single point to the first data set Ee the horiz
226. ld Ptolemy is not the same as the version used to compile your star This should not occur if you are using the compiler distributed with Ptolemy but can occur if the compiler has been updated since Ptolemy was last built or if you are not using the compiler distributed with Ptolemy e You have a src component in the directory name but the corresponding obj PTARCH directory does not exist or cannot be written A common error is to put the Ptolemy sources in usr local src ptolemy which confuses Ptolemy since a star might be in usr local src ptolemy src domains sdf stars which has two src directories in the path You may find it helpful to refer to the Appendix A Installation and Troubleshooting in the User s Manual The star you just created performs exactly the same function as an existing star in the Ptolemy library and hence is not very interesting Try modifying the star For example you could add 1 0 to the sine before producing the output Find the definition of the go method which should look like this go output 0 lt lt sin double input 0 The one line of code is ordinary C code although the lt lt and operators have been overloaded This line means that the current value 0 of the output named output should be assigned the value returned by the sin function applied to the current value of the input named input The cast to double indicates that we are not really interested in
227. le as well There might be variations like sol2 cfront or hppa cfront to store an object tree created by the Cfront C compiler or some other non g compiler The script SPTOLEMY bin ptarch will return the architecture of the machine on which it is run For example if you were on a machine running SunOS4 1 3 you would type setenv PTARCH sun4 You can use the following fragment in your cshrc file to set SPTOLEMY and SPTARCH The SPTOLEMY cshrc file contains the fragment below and many other csh setup commands you may find useful setenv PTOLEMY users ptolemy if S SPTARCH setenv SPTARCH SPTOLEMY bin ptarch set path SPTOLEMY bin SPTOLEMY bin SPTARCH path Note that if you are using a prebuilt Gnu compiler that you obtained from the Ptolemy project you must either place the Ptolemy distribution at users ptolemy or you must set certain environment variables so that the Gnu compiler can find the necessary pieces of itself Appendix A Installation and Troubleshooting of the Ptolemy User s Manual discusses these variables in detail The variables change with different releases of the compilers so we do not document them here The User s Manual also documents other useful environment variables such as LD_LIBRARY_PATH For every directory under the src tree see figure 1 2 that contains source code that is compiled there is a corresponding directory under the obj SPTARCH tree Many develo
228. le prefer to interface with gdb through emacs which provides much more sophisticated interaction between the source code and the debugger To get an emacs interface to gdb assuming emacs is installed on your system set the following environment variable setenv PT_DEBUG ptgdb To find out more about using gdb from within emacs start up emacs and type M x info Then type m emacs Then go down to Running Debuggers Under Emacs Starting GUD How to start a debugger subprocess Debugger Operation Connection between the debugger and source buffers Commands of GUD Key bindings for common commands GUD Customization Defining your own commands for GUD Gdb and the environment Note that the documentation for gdb says the following Warning GDB runs your program using the shell indicated by your SHELL environment variable if it exists or bin sh if not If your SHELL variable names a shell that runs an initialization file such as cshrc for C shell or bashrc for BASH any variables you set in that file affect your program You may wish to move setting of environment variables to files that are only run when you sign on such as login or profile Optimization By default Ptolemy is compiled with the optimizer turn up to a very high level This can result in strange behavior inside the debugger as the compiler may evaluate instructions in a different order
229. led on the object If the value from the source will not fit an error bit is set so that the ovf_occurred method will return TRUE Functions to set or display information about the Fix number int len int intb const Return the total word length of the Fix number const Return the number of bits to the left of the binary point int precision const Return the number of bits to the right of the binary point int overflow const U C Berkeley Return the code of the type of overflow response for the Fix number The possible codes are 0 ovf saturate 1 ovf zero saturate 2 ovf_wrapped 3 ovf warning 4 ovf n types Department of EECS The Almagest 4 11 int roundMode const Return the rounding mode 1 for rounding 0 for truncation int signBit const Return TRUE if the value of the Fix number is negative FALSE if it is positive or zero int is_zero Return TRUE if the value of the Fix number is zero double max Return the maximum value representable using the current precision double min Return the minimum value representable using the current precision double value The value of the Fix number as a double void setToZero Set the value of the Fix number to zero void set_overflow int value Set the overflow type void set_rounding int value Set the rounding type TRUE for rounding FALSE for truncation void initialize
230. lete the invalid Clusters This function will cost O N E x E to execute but since it is not done at each clustering step the result on the overall complexity will be additive versus being multiplicative For an example of how this is done refer to SPTOLEMY src domains cg hierScheduler Hier Scheduler cc TABLE 6 1 Complexity cost of absorb merge step 6 4 3 Cluster Iterator Classes The Cluster iterator classes assume that all Blocks in the Galaxy being iterated on are Clusters This property is TRUE assuming that the Galaxy or one of its parent Galax ies has been properly initialized section 6 4 1 and merge absorb have been the only func tions that have modified the topology of the graph since the initialization These iterators ignore pointers to invalid Clusters which have been left in the Galaxy using merge absorb with the removeFlag set to FALSE last two cases in table 6 1 The cluster iterators are listed in table 6 2 Iterator Description ClusterIter Iterate over all valid Clusters in the given Galaxy SuccessorClusterIter Iterate over all successor adjacent Clusters fora given Cluster TABLE 6 2 Cluster Iterators Ptolemy Last updated 10 10 97 6 6 Using the Cluster Class for Scheduling Iterator Description PredecessorClusterl Iterate over all predecessor Clusters for a given Clus ter TABLE 6 2 Cluster Iterators 6 5 Block state an
231. lex data type is partially supported None of the currently defined stars that take anytype input except Fork are compatible with the complex data type It would be possible to write a star that supports a complex token read into an anyt ype input To do this the star writer would have to check on the input type and make sure to do the intended function on both the X and Y memory components of the complex input token 15 3 Attributes In addition to the code generation attributes detailed in 13 2 6 for CG56 attributes are defined to specify the X and Y memory banks They are A_XMEM Allocate this state in X memory A_YMEM Allocate this state in Y memory The underlying bits are AB_XMEM and AB_YMEM Each attribute above turns one off and turns the other on e g A_YMEM turns AB YMEM on and AB XMEM off Also for CG56 stars portholes can assert attributes P_XMEM and P_YMEM which work in exactly the same way as A_XMEM and A_YMEM The default attribute for a 56001 porthole is P_XMEM which allocates the porthole buffer in X memory Specifying the P_YMEM attribute places the porthole buffer in Y memory Ptolemy Last updated 10 10 97 15 2 CG56 Domain 15 4 Code Streams The CG56 domain uses the default assembly language code streams discussed in Assembly code streams on page 13 17 There are few target specific code streams detailed by target below 15 4 1 Sim56Target Code St
232. lib ptlang pxgraph tcltk thread tycho utils XV header files for non standard configurations the code for each of the domains outside filter design programs source for Gnu tools optional the Ptolemy kernel source for our subset of the Berkeley oct tools example showing how to make a custom pigi source for pigiRpc program source for most of pigi source for ptcl some Tcl Tk code used in various places source for the preprocessor for star writing source code for the pxgraph program source for Tcl and Tk optional code used by the PN domain source for the tysh Tycho Ptolemy binary external software package interface libraries image viewer sources optional The structure of the PTOLEMY src directory Department of EECS The Almagest 1 5 There are three primary Ptolemy binaries pigiRpe The graphical version that uses vem as a front end pigiRpc contains an interface to Octtools the package that is used to store facets When you run pigi you actually run a script called SPTOLEMY bin pigiEnv csh which calls vem which in turn starts up pigiRpc piel A prompt version that contains most of the functionality in pigiRpc not including the Tk stars ptc1 does not contain an interface to Octtools tysh The Tycho shell version which is similar to pigiRpc except that tysh does not contain an interface to Octtools Note that Tycho can be run from a basic it kwish binary that contai
233. lizing and if applicable terminating the generated executable One pair of communication stars must communicate from the target to the CGC code that will run on the Ptolemy host workstation The other pair must communicate in the oppo site direction The CGC send receive stars are typically defined from a common base commu nication star specific for each target This common base defines the C code to control a target that was discussed in the previous paragraphs Examples of send receive stars that support this infrastructure can be found in For the 56XTarget Ariel S 56X DSP card SPTOLEMY src domains cg56 targets CGCXBase pl SPTOLEMY src domains cg56 targets CGCXSend pl SPTOLEMY src domains cg56 targets CGCXReceive pl SPTOLEMY src domains cg56 targets CG56xXCSend pl SPTOLEMY src domains cg56 targets CG56XCReceive pl For the SimVSSTarget Synopsis VSS Simulator SPTOLEMY src domains vhdl targets CGCVSynchComm pl U C Berkeley Department of EECS The Almagest 18 27 SPTOLEMY src domains vhdl targets CGCVSend pl SPTOLEMY src domains vhdl targets CGCVReceive pl SPTOLEMY src domains vhdl targets VHDLCSend pl SPTOLEMY src domains vhdl targets VHDLCReceive pl After defining both pairs of communication stars methods to instantiate these stars must be defined in the target CommPair fromCGC PortHole amp CommPair toCGC PortHole amp A CommPair is a communication pair where one of the communication s
234. ll see the data type they expect and the necessary type conversion is handled transparently e The component portholes of a multiporthole are type resolved separately Thus if an input multiporthole is declared ANYTYPE its component portholes might have differ ent types at runtime This was not true in Ptolemy versions preceding 0 7 The com ponent portholes of an output multiporthole can have different resolved types in any case because they might be connected to inputs of different types e It is rarely a good idea to declare a pure ANYTYPE output porthole rather its type should be equated to some input porthole using the ptlang port notation or an explicit inherit ypeFrom call This ensures that the type resolution algorithm can suc ceed A pure ANYTYPE output will work only if connected to an input of determin able type if it s connected to an ANYTYPE input the kernel will be unable to resolve a type for the connection By providing an type declaration you allow the kernel to choose an appropriate particle type for an ANYTYPE to ANYTYPE connection 4 7 Unsupported Types There are a number of data types in Ptolemy that we recommend not be used by exter nal developers because they are either insufficiently mature or likely to change This section briefly describes those classes 4 7 1 Sub matrices The Ptolemy kernel contains a set of matrices to support efficient computation with sub matrices
235. lock sharedInit Initialize PCM offset table ATE ds double x 0 0 double dx 0 125 for i 0 i lt 8 i x dx SsharedSymbol PCM offset i SsharedSymbol PCM mulaw x initCode if addGlobal sharedDeclarations SsharedSym bol PCM PCM addCode sharedlInit The above code creates a conversion table and a conversion function from linear to mu law PCM encoder The conversion table is named offset and belongs to the PCM class The conversion function is named mulaw and belongs to the same PCM class Other stars can access that table or function by saying sharedSymbol PCM off set or sharedSymbol PCM mulaw The initCode method tries to put the sharedDeclarations codeblock into the global scope by addGlobal method in the CGC domain That code block is given a unique label by sharedSym bol PCM PCM If the codeblock has not been previously defined addGlobal returns true thus allowing addCode sharedInit If there is more than one instance of the PCM star only one instance will succeed in adding the code Slabel name ScodeblockSymbol name Returns a unique symbol in the codeblock scope Both label and code blockSymbol refer to the same macro expansion The codeblock scope only lives as long as a codeblock is having code generated from it Thus if a star uses addCode more than once on a particular codeblock all codeblock U C Berkeley D
236. lt berkeley edu Elapsed time is 1538 seconds The message segmentation fault core dumped may appear in the window from which you started pigi The first line in the above message might alternatively read RPC Error fread of long failed Vem is trying to tell you that it is unable to get data from the link to the Ptolemy kernel In either case it will create a large file in your home directory called core The co re file is Ptolemy Last updated 10 10 97 1 22 Extending Ptolemy Introduction useful for finding the problem 1 7 1 A duick scan of the stack Assuming you are using Gnu tools and assuming the pigiRpc executable that you are using is in your path go to your home directory and type gdb pigiRpc The Gnu symbolic debugger gdb will show the state of the stack at the point where the pro gram failed Note that gdb is not distributed with Ptolemy but is available free over the Inter net in many places including ftp prep ai mit edu pub gnu The most recently called function might give you a clue about the cause of the problem Here is a typical session cxh watson 197 gdb pigiRpc core GDB is free software and you are welcome to distribute copies of it under certain conditions type show copying to see the conditions There is absolutely no warranty for GDB type show warranty for details GDB 4 15 1 sparc sun solaris2 4 Copyright 1995 Free Software Foundation Inc
237. ludes the cases that arise when error messages are generated For an example implementation see the implementation of the SDFPrinter star given in Section 2 6 Another common mistake is not paying attention to the kinds of strings returned by functions The function savestring returns a new string dynamically allocated and should be deleted when no longer used The expandPathName tempFileName and makeLower functions return new strings as does the Target writeFileName method Therefore the strings returned by these routines should be deleted when they are no longer needed and code such as savestring expandPathName s is redundant and should be simplified to expandPathName s to avoid a memory leak due to not keeping track of the dynamic memory returned by the function savestring Occasionally dynamic memory is being used when instead local memory could have been used For example if a variable is only used as a local variable inside a method or func tion and the value of the local variable is not returned or passed to outside the method or func tion then it would be better to simply use local memory For example char localstring new char len 1 if person absent return strcpy localstring otherstring delete localstring Ptolemy Last updated 8 26 97 2 30 Writing Stars for Simulation return could easily return without deallocating Localstring The code should be rewritten to use either the
238. lue For example a clock or some other source can be attached to the star to set its firing pattern defstar name Identity_M domain DE desc Output a floating point identity matrix author Brian L Evans input name input type anytype output name output type FLOAT_MATRIX_ENV defstate name rowsCols type int default 2 desc Number of rows and columns of the output square matrix ccinclude Matrix h go Functional Star pass timestamp without change completionTime arrivalTime For messages you must pass dynamically allocated data FloatMatrix amp result new FloatMatrix int rowsCols int rowsCols Set the contents of the matrix to an identity matrix result identity Send the matrix result to the output port output put completionTime lt lt result Ptolemy Last updated 10 17 97 12 14 DE Domain This is a functional star because the time stamp on the input particle is not altered The output is a matrix message The matrix is a sguare matrix In order for the matrix to remain defined after the go method finishes the matrix result cannot be allocated from local mem ory Instead it must be allocated from global dynamic memory via the new operator In the syntax for the new operator the int cast in int rowsCols extracts the value from rowsCols which is an instance of the State data structure The d
239. lue that offset can take in any expression of the form name offset For example if the go method references name 0 and name 1 then past would have to be at least one It is zero by default Multiple PortHoles Sometimes a star should be defined with n input portholes or n output portholes where n is variable This is supported by the class MultiPortHole and its derived classes An object of this class has a sequential list of PortHoles For SDF we have the specialized derived class MultiInSDFPort Which contains InSDFPorts and MultiOutSDFPort which contains Out SDFPorts Defining a multiple porthole is easy as illustrated next defstar inmulti name input_name Ptolemy Last updated 8 26 97 2 20 Writing Stars for Simulation type input type outmulti name output_name type output_type To successively access individual portholes in a MultiPortHole the MPHIter itera tor class should be used Iterators are explained in more detail in Iterators on page 3 10 Consider the following code segment from the definition of the SDF Fork star input name input type ANYTYPE outmulti name output type input go MPHIter nextp output PortHole p while p nextp 0 p 0 input 0 A single input porthole supplies a particle that gets copied to any number of output portholes The type of the output Mult iPortHole is inherited from the type of the input
240. m the input to the output It is important therefore that the star writer not miss any triggering relation when triggers directives are provided If an input triggers some but not all outputs then the constructor for the star should contain several triggers directives one for each output that is triggered by that input If an input triggers all outputs then no directive is necessary for it If delayType is set to TRUE it is not necessary to write any triggers directives a delay star by definition never triggers zero delay output events 12 2 4 Simultaneous events An input port may have a sequence of simultaneous events events with identical time stamps pending Normally the star will be fired repeatedly until all such events have been consumed Optionally a DE star may process simultaneous events during a single firing The getSimulEvent method can be used as in the following example taken from an up down counter star go while countUp dataNew countt countUp getSimulEvent Ptolemy Last updated 10 17 97 12 8 DE Domain Here countUp is an input porthole The get SimulEvent method examines the glo bal event queue to see if any more events are available for the porthole with the current times tamp If so it fetches the next one and sets the dat aNew flag to TRUE if none remain it sets the dat aNew flag to FALSE In this example the actual values of the input events are uninter esting but the
241. m the Plasma U C Berkeley Department of EECS The Almagest 17 9 17 4 Recipe for writing your own domain This section describes some of the template files we have made so that you don t have to start coding from scratch We also discuss which classes and methods of those classes that a new domain must define 17 4 1 Introduction The first thing to do is to think through what you want this domain to do You should have some idea of how the your Stars will exchange data and what kind of Scheduler is needed You should also understand the existing Ptolemy domains so that you can decide whether your domain can reuse some of the code that already exists Also read Chapter 1 so you understand the general classes in the Ptolemy kernel and how the domain methods inter act 17 4 2 Creating the files The mkdon script at SPTOLEMY bin mkdom can be used to generate template files for a new domain mkdom takes one argument the name of the domain which case insensitive mkdom converts the what ever you pass to it as a domain name to upper and lower case inter nally Here we assume that you have set up a parallel development tree as documented in chapter 1 or you are working in the directory tree where Ptolemy was untar d 1 To use mkdom create a directory with the name of your domain in the src domains directory In this example we are creating a domain called yyy mkdir SPTOLEMY src domains yyy 2 cd to that direct
242. mCols with indices ranging from 0 to num 1 We recommend however that you do not adapt this method to your own types but use the standard method of adding new message types described in Section 4 3 The method currently used for the matrix classes may not be supported in future releases U C Berkeley Department of EECS The Almagest 4 23 Rows numCols 1 This function returns a reference to the actual entry in the matrix so that assignments can be made to that entry In general functions that wish to linearly reference each entry of a matrix A should use this function instead of the expression A data i because classes which are derived from PtMatrix can then overload the entry method and reuse the same functions xxx operator int row Constructors XXXMatrix Example A row column Return a pointer to the start of the row in the matrix s data storage This operation is different to matrix classes defined as arrays of vec tors in which the operator returns the vector representing the desired row This operator is generally not used alone but with the operator defined on C arrays so that A i j will give you the entry of the matrix in the i row and 3 column of the data storage The range of rows is from 0 to numRows 1 and the range of columns is from 0 to numCols 1 Example IntMatrix A Create an uninitialized matrix The number of rows and columns are set to zero and no
243. memory is allocated for the storage of data XXXMatrix int numRow int numCol Example FloatMatrix A 3 2 Create a matrix with dimensions numRow by numCol Memory is allo cated for the data storage but the entries are uninitialized XXXMatrix int numRow int numCol PortHole p Example ComplexMatrix 3 3 myPortHole Create a matrix of the given dimensions and initialize the entries by assigning to them values taken from the porthole myPortHole The entries are assigned in a rasterized sequence so that the value of the first particle removed from the porthole is assigned to entry 0 0 the sec ond particle s value to entry 0 1 etc It is assumed that the porthole has enough particles in its buffer to fill all the entries of the new matrix XXXMatrix int numRow int numCol XXXArrayState amp dataArray Example IntMatrix A 2 2 myIntArrayState Create a matrix with the given dimensions and initialize the entries to the values in the given ArrayState The values of the ArrayState fill the matrix in rasterized sequence so that entry 0 0 of the matrix is the first entry of the ArrayState entry 0 1 of the matrix is the sec ond etc An error is generated if the ArrayState does not have enough values to initialize the whole matrix XXXMatrix const XXXMatrix amp src Ptolemy Last updated 10 10 97 4 24 Data Types Example FixMatrix A B This is the copy constructor A new matrix is formed with th
244. meter The callback function sets the meter and updates the numeric display to the left of the slider Notice that the body of the procedure is enclosed in quotation marks rather than the usual braces This ensures that the variables ptkControlPanel and starID will be evaluated at the time the procedure is defined rather than at the time it is invoked To make sure that new_value is not evaluated until the procedure is invoked we use a preceding backslash as in new_value We could have alterna tively passed the ptkControlPanel and starID values as arguments ptkMakeScale SptkControlPanel high scale_S starID my scale 50 scale_update_S starID This makes the slider itself and sets its initial value to 50 half of full scale ptkMakeButton SptkControlPanel middle button_SstarID my button button_update This makes a button labeled my button proc button_update ptkImportantMessage msg Hello This defines the callback function connected with the button This callback function opens a new window with the message Hello and grabs the focus The user must dismiss the new window before continuing ptkMakeEntry SptkControlPanel low entry_SstarID my entry 10 entry_update_SstarID This makes the entry box with initial value 10 proc entry_update_SstarID new_value setOutputs_SstarID Snew_value This defines the callback function associated with the entry box Again not
245. method ptlang directive c0000 2 11 POTEEOV A ee reached baie evens 1 19 pure delay star in DE ees ee ee ee ee ee ee ee 12 2 Puny OE NE N 1 19 put method ee ee eek Re RR 12 5 12 6 pxgraph Program ee seen see see ee ee Re RR ee 3 3 3 6 Q Quantify Ee A EE dee 1 19 quantization ed OR OO duct tenes N 4 4 Queue C1aS8 ee ee ee ee ee ee ee ee ee ee ee ee ee 3 11 Koi N OE Nees 12 1 queueing NEtWOTKS e ee ee ee ee ee ee ee ee ee ee eg 12 1 R Ramp SDF block ee ee ee ee ee ee ee ee ee 2 26 random nUMDETS iese ee ee ee ee ee ee ee ee 3 17 ed SA EE N N 13 23 receiveData method ee ee ee ee ee ee ee 8 2 Rect SDF block ee ee ee ee ee ee ee ee ee ee 2 4 reference Count ee ee ee 4 14 4 17 4 30 refireAtTime method ee 12 9 12 9 Tin EO AA OO ek 1 12 rounding a EE ee ee ee ee ee 4 4 RPC Errore a Be ee Ee ee ee ee ee oe 1 21 runCode method ee ee 13 18 S saturation Fi CLASS eed ese ER veeg oe caves Age 4 4 savestring FunCHON sees ee ek ek ee RR RR 3 8 es OIE EE EE OE 1 18 schedulers SALE AS ee ee r act oelefed 7 1 schedulers CG domain ee ee se 13 20 SDF domain ices hie ies 7 1 porthole parameters iese eee eee se ee ee 7 1 Writing SATS ee ee ee ee ee ee ee ee ee ee ee ee 7 1 12 1 Ptolemy l 7 SDF synchronous dataflOW esse ee ee ee 7 1 SPERE Class ER lise ee EE eg Re eg ED 4 9 seed of a random number ee ee 3 17 segmentation fault ccccscescsesesessescscsesesssessesen
246. moves them into the Cluster pointed to by the this pointer A merge operation is communi cative A series of merge steps is shown in figure 6 1 frames 3 and 4 The Cluster absorb method takes the Cluster being absorbed and moves it into the Cluster pointed to by the this pointer Unlike merge absorb is not communicative as shown in figure 6 1 frames 5 and 5 The absorbed or merged Cluster is removed from the original parent Galaxy by default when Cluster merge or Cluster absorb is called We provide three ways to update the graph after a clustering operation with differing levels of efficiency These meth ods are detailed in the table 6 1 We first list some variable definitions e Let N be defined as the number of Clusters in the parent Galaxy e Let E be defined as the number of PortHoles in this Cluster e Let E be defined as the number of PortHoles in the Cluster to absorb or merge Complexity to Deletion Update Method update at each clustering step Using merge absorb in their default mode of operation This is the most O N E x E inefficient way to do clustering TABLE 6 1 Complexity cost of absorb merge step Ptolemy Last updated 10 10 97 6 4 Using the Cluster Class for Scheduling 1 Initial Graph 2 initializeForClustering 5 ABC absorb D FIGURE 6 1 A five step clustering example By convention a Cluster in this figure will be named by the listing of its innermost atomic Blocks I
247. mp typ IntVecData 0 return TRU else return Message isA typ GI constructor makes an uninitialized array IntVecData int length len length data new int length constructor makes an initialized array from a int array IntVecData int length int srcData init length srcData Last updated 10 10 97 4 16 Data Types copy constructor IntVecData const IntVecData amp src init src len src data clone make a duplicate object Message clone const return new IntVecData this destructor IntVecData delete data Vi This message object can contain a vector of integers of arbitrary length Some functions in the class are arbitrary and the user may define them in whatever way is most convenient however there are some reguirements The class must redefine the dataType method from class Message This function returns a string identifying the message type This string should be identical to the name of the class In addition the isA method must be defined The isA method responds with TRUE 1 if given the name of the class or of any base class it returns FALSE 0 otherwise This mech anism permits stars to handle any of a whole group of message types even for classes that are defined after the star is written Because of the regular structure of isA function bodies macros are provided to gener ate them The ISA_INLINE macro exp
248. ms in pigi statename will not appear as one of the parameters of the star Of course the state can still be set and used within the code defining the star The same effect can be achieved with outputs or inputs For instance given an output named output you can use the following code constructor output setAttributes P_HIDDEN This means that when you create an icon for this star no terminal will appear for this port This is most useful when output is a multiporthole because this means simply that there will be zero instances of the individual portholes This technique can also be used to hide individual portholes however the porthole will still be present so it must be used with caution Most domains do not allow disconnected portholes and will flag an error You can explicitly connect the port within the body of the star see the kernel manual 2 6 Programming examples The following star has no inputs just an output The source star generates a linearly increasing or decreasing sequence of float particles on its output The state value is initialized to define the value of the first output Each time the star go method fires the value state is updated to store the next output value Hence the attributes of the value state are set so that the state can be overwritten by the star s methods By default the star will generate the output sequence 0 0 1 0 2 0 etc defstar name Ramp domain SDF
249. n Ptolemy terminol ogy see Writing Stars for Simulation on page 2 1 for more information A collection of connected Stars form a Galaxy see Chapter 2 of the User s Manual for more information Ptolemy supports graphical hierarchy so that an entire Galaxy can be formed and used as a single function block icon The Galaxy can then be connected to other Stars or Galaxies to create another Galaxy Usually all the Stars of a Galaxy are from the same Domain but it is possible to connect Stars of one domain to a Galaxy of another domain using a Worm Hole A Universe is a complete executable system A Universe can be either a single Galaxy or a collection of disconnected Galaxies To run a Universe each Galaxy also needs a Target In simulation domains a Target is essentially a collection of methods to compute a schedule and run the various Stars of a Galaxy Some Domains have more than one possible scheduling algorithm available and the Target is used to select the desired scheduler In code generation domains a Target also computes a schedule and runs the indi vidual Stars but each Star only generates code to be executed later Code generation Tar gets also handle compiling loading and running the generated code on the target architecture At a lower level are the connections between Blocks A Block is a Star or Galaxy Each Block has a number of input and output terminals which are attached to a Block through its PortHoles A sp
250. n frame 1 the user specified graph is shown Cluster initializeForClustering is called and the resultant graph is shown in frame 2 this step adds a Cluster around all atomic Blocks Frames 3 5 show a series of merge absorb operations The ordering is important only with absorb operation as shown by frames 5 and 5 U C Berkeley Department of EECS The Almagest 6 5 Complexity to Deletion Update Method update at each clustering step GalTopBlockIter remove OE x E We can use this method if the Cluster to absorb merge was found using a GalTopBlockIter or derived iterator class on the parent Galaxy The scheduler writer needs to do two things e remove the absorbed merged cluster using from the parent Gal axy using the iterator s remove method e delete the removed Cluster using the C operator delete This is the most efficient way of updating the graph after a clustering operation but it is not always possible because we may be traversing the graph in some other way such as using a SuccessorIter cleanupAfterCluster defined in Cluster h cc O E x E If we cannot use the previous method we can leave the Cluster in the parent Galaxy list it will be marked invalid automatically The Clus ter iterator classes automatically skip these invalid Clusters Periodi cally but not at each clustering step the cleanupAfterCluster function should be invoked to remove and de
251. n is specified by an associated precision state using either of two syntaxes U C Berkeley Department of EECS The Almagest 4 5 e Specifying just a value itself in the dialog box creates a fixed point number with the default length of 24 bits and with the position of the binary point set as required to store the integer value For example the value 1 0 creates a fixed point object with precision 2 22 and the value 0 5 would create one with precision 1 23 e Specifying a value precision pair create a fixed point number with the specified pre cision For example the value 2 546 3 5 creates a fixed point object by casting the double 2 546 to a Fix with precision 3 5 Fixed point inputs and outputs Fix types are available in Ptolemy as a type of Particle The conversion from an int or a double to a Fix takes place using the Fix Fix double constructor which makes a Fix object with the default word length of 24 bits and the number of integer bits as needed required by the value For instance the double 10 3 will be converted to a Fix with precision 5 19 since 5 is the minimum number of bits needed to represent the integer part 10 including its sign bit To use the Fix type in a star the type of the portholes must be declared as fix Stars that receive or transmit fixed point data have parameters that specify the precision of the input and output in bits as well as the overflow behavior Here is a simplified version of SDFA
252. name mySubset default subset A type string private static HashTable listOfLists SequentialList myList code HashTable SDFBetterShare listOfLists begin if listOfLists hasKey char mySubset myList listOfLists lookup char mySubset else myList new SeguentialList listOfLists insert char mySubset myList myList gt append this go howmany 0 lt lt myList gt size wrapup if listOfLists hasKey char mySubset listOfLists remove char mySubset delete myList In addition to the static private member 1istOfLists we also have a pointer myList toa SequentialList The begin method is a bit more complicated now It first checks to see whether an entry in the hash table has already been created with a key equal to the value of the state mySubset If it has then the SequentialList pointer myList is set equal to the value of that entry If it has not then a new SequentialList is allocated and inserted into the hash table with the appropriate key The last action is simply to insert a pointer to the star instance into myList The go method is similar to before The wrapup method is slightly more complicated because it needs to free the mem ory allocated when the new SequentialList was allocated However it should free that U C Berkeley Department of EECS The Almagest 3 17 memory only once and there may be several
253. nce of the TclScript star The starID global variable is set by the TclScript star set S starID numInputs This evaluates to the number of inputs that are connected to the star set S starID numOutputs This evaluates to the number of outputs that are connected to the star set starID tcl_file This evaluates to the name of the file containing the Tcl script associated with the star set starID fullName This evaluates to the full name of the star which is of the form universe galaxy galaxy star 5 3 Tcl utilities that are available to the programmer A number of Tcl global variables and procedures that will be useful to the Tcl programmer have been incorporated into Ptolemy Any of these can be used in any Tcl script associated with an instance of the TclScript star For example in example 1 on page 5 2 the global variable ptkControlPanel specifies the control panel that is used to run the system Below is a list of the useful global variables that have been set by the graphical interface pigi when the Tcl script is sourced or when the goTcl_ starID procedure is invoked S ptkControlPanel A string giving the name of the control panel window associ ated with a given run This variable is set by pigi U C Berkeley Department of EECS The Almagest 5 7 SptkControlPanel high The uppermost panel in the control panel that is intended for user defined entries SptkControlPanel mi
254. nce termination Ptolemy Last updated 4 17 97 10 6 PN domain of that thread is complete the current thread resumes and deallocates resources used by the terminated thread by calling pthread_detach Thus one thread can cause another to termi nate by invoking the terminate method of that thread void PosixThread terminate Force the thread to terminate if it has not already done so Is it safe to do this to a thread that has already terminated pthread_cancel thread Now wait pthread_join thread NULL pthread_detach amp thread 10 2 3 The DataFlowProcess Class The class DataFlowProcess is derived from PosixThread It implements the map higher order function see the PN Domain chapter in the User s Manual A DataFlowStar is associated with each DataFlowProcess object DataFlowStar amp star This protected data member refers to the dataflow star associ ated with the DataFlowProcess object The constructor shown below initializes the star member to establish the association between the thread and the star DataFlowProcess DataFlowStar s star s The run method shown below is defined to repeatedly invoke the run method of the star associated with the thread just as the map function forms a process from repeated firings of a dataflow actor Some dataflow stars in the BDF domain can operate with static scheduling or dynamic run time scheduling Under static scheduling a BDF star
255. ncreaseBuffers PNThread runAll currentTime schedulePeriod return SimControl haltRequested void SyncDataFlowProcess run int i 0 Configure the star for dynamic execution star setDynamicExecution TRUE Fire the star ad infinitum do Wait for notification to start CriticalSection region start monitor while iteration lt i start wait i iteration if star waitPort star waitPort gt receiveData while star run The increaseBuffers method is used during the course of execution to adjust the channel capacities according to the theory presented in Par95 ch 4 Each time execution stops the program graph is examined for full channels If there are any full channels then the capacity of the smallest one is increased Increase buffer capacities Return number of full buffers encountered int PNScheduler increaseBuffers int fullBuffers 0 PNGeodesic smallest NULL Increase the capacity of the smallest full geodesic GalStarIter nextStar galaxy Star star while star nextStartt NULL BlockPortiIter nextPort star PortHole port while port nextPort NULL PNGeodesic geo NULL U C Berkeley Department of EECS The Almagest 10 15 if port gt isItOutput amp amp geo PNGeodesic port geo NULL if geo gt size gt geo gt capacity fullBuffe
256. need to be defined or are used by a Domain Note that we only provide a functional description of some of the major methods of each class and not a complete description of all methods U C Berkeley Department of EECS The Almagest 17 3 17 2 1 Target A Target is an object that manages the execution of the Stars in a Domain Major methods run Called to execute a schedule wrapup Called at the end of an execution to clean up setup Called by initialize which is inherited from the Block class which is a common base class for many of Ptolemy s classes Sets each Star to point to this Target and sets up the Scheduler Major objects contained are gal A pointer to the Galaxy being executed sched A pointer to the Scheduler that is being used For further information about Targets see some of the existing domains 17 2 2 Domain Declares the type of various components of the Domain like which type of Worm Hole PortHole Star etc is used by the Domain Major methods newWorm Create a WormHole of the appropriate type for this Domain newF rom Create an Event Horizon an object that is used to interface to other Domains used with WormHoles that translates data from a Universal format to a Domain specific one newTo Create an EventHorizon that translates data from a Domain specific format to a Universal one newNode Returns a Geodesic of the appropriate type for this Domain 17 2 3 S
257. ng function help message and assignment respectively of the new state variable Also there is no provision to check for duplicate command line names If there are duplicates Ptolemy will simply generate multiple st ruct members with the same name and error will result in the generated code To get around this a new Tk interface could be written to specify and set the settable states and checking can be done at that level Alternatively it might be a better idea to use the put method in CodeSt ream to add the st ruct member with its unique handle to the appropriate CodeSt ream That way there will not be duplicate struct members and state variables could still reference the same member so that two or more states could be set to the same value from a single argument on the command line Another limitation is that the command line capability only works for states of blocks at the top level It will not work for states of Galaxies and Universes and states that refer Ptolemy Last updated 8 26 97 14 6 CGC Domain enced other settable states This could probably be solved by modifying the pragma mecha nism to ensure that pragmas at the top level propagate all the way down to the contained blocks By doing this states will inherit pragmas from their parent galaxies so that these can be picked up by the isCmdArg function and the appropriate codes can be generated Certain states will affect the overall scheduling of the whole syst
258. ng the pxgraph program TABLE 3 5 Ptolemy return the variance of the observed data so far A class for displaying histograms Last updated 8 26 97 3 8 Infrastructure for Star Writers 3 4 String Functions and Classes The Ptolemy kernel defines some ordinary functions not classes plus two classes that are useful for building and manipulating strings The non class string functions are summa rized in table 3 6 These include functions for copying strings adding strings to a system ordinary functions for strings include miscFuncs h method description char savestring create a new copy of the given text and return a const char text pointer to it the caller must eventually delete the string const char hashstring save a copy of the text in a system wide hash table const char text if it isn t already there and return a pointer to the entry char tempFileName return a new unique temporary file name the caller must eventually delete the string const char expandPathName return an expanded version of the filename argu const char filename ment which may start with user or var the expanded result is in static storage and will be overwritten by the next call TABLE 3 6 Non class ordinary functions available in the Ptolemy kernel for string manipulation wide hash table creating temporary file names The non class pathname functions are summa r
259. ng the pxgraph program An example of such a plot is shown in figure 3 3 The most useful methods of both classes are summarized in tables 3 4 and 3 5 The Histogram class counts the number of occurrences of data values that fall within each of a number of bins Each bin represents a range of numbers All bins have the same width and the center of each bin will be an integer multiple of this width Bin number 0 is always that with the smallest center Bins are added if new data arrives that does not fit within any of the existing bins The getData method is used to read out the contents of a bin If you start with bin number 0 and proceed until getData returns FALSE you will have read all the bins Histogram class include Histogram h description Histogram constructor double width the width of each bin bins are centered at integer multiples of Let this int maxBins since bins are added as needed it is wise to limit their number 1000 void add add to the count of the bin within which the given data falls double x a data point for the histogram t numCounts return the number of data values used so far in the histogram uble mean return the average value of all observed data so far uble variance return the variance of the observed data so far tData get the count for a given bin return FALSE if the bin is out of range t binno starting at 0 the bin number t amp c
260. ns in the above example star B produces one token and star A consumes two tokens We have to insert a collect star at the input porthole of star A to collect tokens from star B and a receive star that receives a token from processor 2 The spread and collect stars are automatically inserted by the scheduler and are invisible to the user Moreover these stars can not be scheduled They are added to sub galax ies only for the allocation of memory and other resources before generating code The spread and collect stars themselves do not require extra memory since in most cases we can overlay memory buffers For example in the first example a buffer of size 2 is assigned to the output of star A Star B obtains the information it needs to fetch a token from the first location of the buffer via the spread star while the send star knows that it will fetch a token from the second location Thus the buffers for the outputs of the spread star are over laid with the output buffer of star A U C Berkeley Department of EECS The Almagest 18 25 User Specification Sparc DSP VHDL Sparc gt EE Dam gt gt as gt ME i Spliced in send receive pairs Sparc a an O Ee ss IG Sparc VHDL FIGURE 13 1 An interface constructed between three code generation domains The in
261. ns no Ptolemy functionality bdf c50 cg cg56 cgc ddf de SPTOLEMY is src domains hof pn sdf sr vhdl vhdl XXX Boolean controlled dataflow domain code generation for the Texas Instruments C50 the base class domain for all code generation code generation for the Motorola DSP56000 code generation in C dynamically scheduled dataflow the discrete event domain finite state machine domain higher order function domain the process network domain synchronous dataflow statically scheduled synchronous reactive domain code generation for behavioral modeling in VHDL code generation for behavioral modeling in VHDL demonstration of how to define a new domain FIGURE 1 3 The structure of the PTOLEMY src domains directory demo demonstrations of the domain icons the oct facets defining the icons used by pigi SPTOLEMY kernel the core code defining the domain src domains xxx stars stars distributed with the domain targets optional additional targets used by the domain FIGURE 1 4 The structure of a typical domain directory within P TOLEMY src domains Ptolemy Last updated 10 10 97 1 6 Extending Ptolemy Introduction Each of the three binaries above has three different versions that contain different functionality Below we only list the different version of pigiRpc but ptcl and tysh have similar versions pigiRpe This binary contains all of the domains so it is the largest bina
262. nt Examples of such stars are Delay and Server These stars when fired produce output events that typi cally have larger time stamps than the input events They usually do not manipulate the value of the particles in any interesting way The other stars so called functional stars avoid time management usually by generating output events with the same time stamp as the input events They however do manipulate the value of the particles Delay stars should not be confused with the delay marker on an arc connecting two stars represented in pigi by a small green diamond The latter delay is not implemented as a star It is a property of the arc In the DE domain the delay marker does not introduce a time delay in the sense of an incremented time stamp It simply tells the scheduler to ignore the arc while assigning dataflow based firing priorities to stars A star whose outputs are all marked with delays will have the lowest firing priority and so will be fired last among those stars eli gible to be fired at the current time The scheduler s assignment of firing priority also uses properties of the individual 12 2 DE Domain stars each star type can indicate whether or not it can produce zero delay outputs If a star indicates that it does not produce any output events with zero delay then the scheduler can break the dataflow priority chain at that star This saves the user from having to add explicit delay markers A star class can ma
263. nt that we have called two domain specific methods namely SDFTarget setup and SDFScheduler setup The Target can have a choice of more than one Scheduler and in this case it called the default SDF Scheduler We continue here with a more detailed description of a very important function SDFScheduler setup checkConnectivity prepareGalaxy checkStars repetitions computeSchedule adjustSampleRates Q Checks that the galaxy is properly connected Initializes the portHoles of each star and the geodesics that connect them Verifies that the type of the Stars are compatible with this Scheduler Solves the balance equations for the system and calculates how many times each star should be fired for one iteration specific to dataflow Compute the actual schedule Set the number of tokens transferred between EventHorizons if this schedule is for a WormHole O The order of various operations can be different for each scheduler For example a new domain may require that the PortHoles be initialized after the repetitions were calcu lated but before the schedule was computed The domain writer may wish to define a new function prepareForSchedul without initializing the Star s PortHoles Ling that would call the setup function of each Star Expanding prepareGalaxy in more detail SDFScheduler prepareGalaxy galaxy gt in
264. nvironment variable SPTOLEMY set to the root directory of the official version of Ptolemy and that your private version is in Ptolemy If this is not the case then you should make suitable modifications to definition of the pt alias This alias is useful when you want to make a symbolic link to or otherwise access the official version of a file as in oe cd Ptolemy src domains sdf kernel ln s pt BEES oo This will create a symbolic link in your directory Ptolemy src domains sdf kernel to the directory PTOLEMY src domains sdf kernel SCCS For information on source code control see below The pt1 Alias The pt1 alias uses the pt alias to create in the current directory symbolic links to all the files in the corresponding official directory This is useful for quickly filling in the branches of a new directory in your private hierarchy pwd users me Ptolemy src domains ddf mkdir stars ptl ls F DDFCase cc DDFLastOfN cc DDFThresh cc DDFCase h DDFLastOfN h DDFThresh h DDFCase pl DDFLastOfN pl DDFThresh pl DDFDownCounter cc DDFRepeater cc SCCS DDFDownCounter h DDFRepeater h TAGS DDFDownCounter pl DDFRepeater pl ddfstars c DDFEndCase cc DDFSelf cc ddfstars mk DDFEndCase h DDFSelf h make template DDFEndCase pl DDFSelf pl makefile This creates a directory named stars and fills it with symbolic links to the contents of the corresponding
265. ny other consideration P_SHARED Equivalent to A_SHA ve ED only for portholes P_SYMMETRIC Similar to A_SYMMETRIC but for portholes P_NOINIT Do not initialize this porthole Attributes can be combined with the operator For example to allocate memory for a state but make it non settable by the user I can say AB_MEMORY A_NONSETTABLE 13 2 7 Possibilities for effective buffering In principle blocks communicate with each other through porthole connections In code generation domains we allocate a buffer for each input output connection by default There are some stars however that do not modify data at all A good and also ubiquitous example is a Fork star When a Fork star has N outputs the default behavior is to create N buffers for output connections and copy data from input buffer to N output buffers which is a very expensive and silly approach Therefore we pay special attention to stars displaying this type of behavior In the setup method of these stars the forkInit method is invoked to indicate that the star is a Fork type star For example the CGCFork star is defined as defstar name Fork domain CGC desc Copy input to all outputs version CGCFork pl 1 6 11 11 92 author E A Lee copyright 1991 1994 The Regents of the University of Cali fornia location CGC demo library explanation U C
266. o make your changes without affect ing the official version of Ptolemy In order to test your change you will have to build a pri vate version of the interpreter ptc1 or the graphical interface pigiRpc First create the root directory for your duplicate hierarchy o mkdir Ptolemy Then go into that directory and create symbolic links to all files in the corresponding offi cial Ptolemy directory ole cd Ptolemy ptl You will want to have a private version of the lib PTARCH directory so that you won t modify the official version of any library or object files oe cd Ptolemy exp lib SPTARCH This assumes your PTARCH environment variable is set You will also want a private U C Berkeley Department of EECS The Almagest 1 17 obj PTARCH directory for the same reason In this example the tree is expanded down to the sdf directory oe cd Ptolemy exp obj SPTARCH exp domains exp sdf oA ol oe If you are modifying code in the sdf kernel directory then you will want to expand it as well Once expanded you will want remove the make template and makefile links which point to the official Ptolemy files and replace them with links that use relative paths to refer to your private versions of these files in case you make changes to them oe exp kernel mkl ole If you make changes in the sdf kernel directory then there is a good chance that object files in sdf d
267. ocessor inde pendent hence these facilities are provided in the generic classes found in the SPTOLEMY src domains cg kernel directory A key feature of code generation domains is the notion of a target architecture Every application must have a user specified target architecture selected from a set of targets sup ported by the user selected domain Every target architecture is derived from the base class Target and controls such operations as scheduling compiling assembling and download ing code Since it controls scheduling multiprocessor architectures can be supported with Ptolemy Last updated 10 17 97 13 2 Code Generation automated task partitioning and synchronization In the following sections we will introduce the methods and data structures needed to write new code generation stars and targets However we will not document what is needed to write a new code generation domain that discussion can be found in chapter 17 We will first introduce what is needed to write a new code generation star introducing the concepts of code blocks code streams and code block macros Next we will describe the various methods which will generally use the addCode method to piece together the code blocks into the code streams We will then go into what is required to write single processor and multiple proces sor targets Finally we will document the various schedulers available in the code generation domains 13 2 Writing Code Generati
268. od which is called every time the simulation is started but after the scheduler setup method is called i e after any compile time scheduling is performed The syntax is 1 Note however that wrapup is not called if an error occurs See page 2 14 Ptolemy Last updated 8 26 97 2 14 Writing Stars for Simulation begin body This method can be used to allocate and initialize memory It is especially useful when data structures are shared across multiple instances of a star It is always called exactly once when a simulation is started go This item defines the action taken by the star when it is fired The syntax is go body The optional keyword inline may appear before the go keyword The go method will typically read input particles and write outputs and will be invoked many times during the course of a simulation The code syntax for the body is explained starting on page 2 16 wrapup This item defines the wrapup method which is called at the completion of a simula tion The syntax is wrapup body The optional keyword inline may appear before the wrapup keyword The wrapup method might typically display or store final state values The code syntax for doing this is explained starting on page 2 16 Note that the wrapup method is not invoked if an error occurs during execution Thus the wrapup method cannot be used reliably to free allocated memory Instead you should free memory from the previous r
269. odesic h cc Currently we set the Geodesic to be the kernel s AutoForkN ode If the kernel s Geodesic class offers all the functionality you need then this doesn t need to be changed Otherwise try looking at some of the pre existing domains for examples YYYPortHole h cc Define input PortHoles and output PortHoles as well as MultiPortHoles specific to your domain The only required methods are generated for you but you ll likely want to define many more support methods Look at the kernel PortHole DFPortHole and SDFPortHole for examples YYYStar h cc Domain specific class definition Again all the required meth ods have been defined but you ll want to add much more Refer to Star DataFlowStar an YYYScheduler h cc d SDFStar as examples This is where much of the action goes You ll need to define the function setup run and setStopTime 17 4 4 Building an object directory tree Ptolemy can support multiple machine architectures from one source tree the object files from each architecture go into SPTOLEMY obj PT ARCH directories Currently there are two ways to build the SPTOLEMY obj SPTARCH directory tree MAKEARCH and mkP tolemyTree To build object files for your new domain in SPTOLEMY obj PTARCH you will have to set up either or both of these ways Typically you first use MAKEARCH because it can operate on an existing Ptolemy tree and once everything works then you and
270. of a porthole this syntax is used in connection with ANYTYPE to specify a link between the types of two portholes The syntax is type name where name is the name of another porthole This indicates that this porthole inherits its type from the specified porthole For example here is a portion of the definition of the SDF Fork star input name input type ANYTYPE et outmulti name output type input desc Type is inherited from the input constructor This item allows the user to specify extra C code to be executed in the constructor for the class This code will be executed after any automatically generated code in the constructor that initializes portholes states etc The syntax is constructor body where body is a piece of C code It can be of any length Note that the constructor is invoked only when the class is first instantiated actions that must be performed before every simulation run should appear in the setup or begin methods not the construc tor U C Berkeley Department of EECS The Almagest 2 13 conscalls You may want to have data members in your star that have constructors that reguire arguments These members would be added by using the public private or pro tected keywords If you have such members the conscalls keyword provides a mechanism for passing arguments to the constructors of those members Simply list the names of the members followed by the list o
271. ofstream p_out constructor p_out 0 destructor LOG DEL delete p_out setup delete p out p_out new pt ofstream fileName go pt_ofstream amp output p out MPHIter nexti input PortHole p while p nexti 0 output lt lt p 0 print lt lt NET output lt lt n This star is polymorphic since it can operate on any type of input Note that the default value of the output filename is lt cout gt which causes the output to go to the standard output This and other aspects of the pt_ofstream output stream class are explained below in Extended input and output stream classes on page 3 2 The iterator nexti used to scan the input is explained in Iterators on page 3 10 2 7 Preventing Memory Leaks in C Code Memory leaks occur when new memory is allocated dynamically and never deallo cated In C programs new memory is allocated by the malloc or calloc functions and deallocated by the free function In C new memory is usually allocated by the new oper ator and deallocated by the delete or the delete operator The problem with memory leaks is that they accumulate over time and if left unchecked may cripple or even crash a pro gram We have taken extensive steps to eliminate memory leaks in the Ptolemy software envi ronment by following the guidelines below and by tracking memory leaks with Purify a U C Berkeley Department of EECS The Almagest 2 29
272. olemy Last updated 10 10 97 4 18 Data Types to by this pointer must not be modified since other Envelope objects in the program may also contain it If you convert its type always make sure that the converted type is a pointer to const see the programming example for UnPackInt below This ensures that the compiler will complain if you do anything illegal The writableCopy function also returns a pointer to the contained object but with a difference If the reference count is one the envelope is emptied set to the dummy message and the contents are returned If the reference count is greater than one a clone of the contents is made by calling its clone function and returned again the envelope is zeroed to pre vent the making of additional clones later on In some cases a star writer will need to keep a received Message object around between executions The best way to do this is to have the star contain a member of type Envelope and to use this member object to hold the message data between executions Mes sages should always be kept in envelopes so that the user does not have to worry about manag ing their memory 4 3 3 Use of the MessageParticle class If a porthole is of type message then its particles are objects of the class Mes sageParticle A MessageParticle is simply a particle whose data field is an Enve lope which means that it can hold a Message in the same way that Envelope objects do
273. on Stars Code generation stars are very similar to the C simulation stars The main differ ence is that the initialization setup run time go and termination wrapup meth ods generate code to be compiled and executed later Additionally code generation stars have two more methods called initCode and execTime The setup method is called before the schedule is generated and before any mem ory is allocated In this method we usually initialize local variables or states Note that the setup method of a star may be called multiple times This means that the user should be care ful so that the behavior of the star does not change even though setup method is called multi ple times The initCode method of a star is called after the static schedule has been generated and before the schedule is fired This method is used to generate the code outside of the main loop such as initialization code and procedure declaration code To generate start up code use the initCode method NOT the setup method since setup is called before schedul ing and memory allocation The main use of the setup method as in SDF is to tell the sched uler if more than one sample is to be accessed from a porthole with the set SDFParams call The go function is used to generate the main loop code for the star Finally the wrapup function is used to generate the code after the main loop The execTime method returns an integer specifying the t
274. one string of one character const char string copy the string and makes a one element StringList contain int dou uns i ble x igned u ing it create an ASCII representation of the number and return a one element StringList with that number as the element StringL arg ist amp operator assignment takes the same types of arguments as the con structors except none StringL lt lt arg ist amp operator add one or more elements to a StringList this takes the same types of arguments as the constructors except none operator const char join all elements together and return as a single string void in itialize t le t num gth Pieces delete all elements making the StringList empty return the length in characters sum of the lengths of the elements return the number of elements NSE C char n har head return the first element ewCopy InfString class method return the concatenated elements in a single newly allo cated string the caller must free the memory allocated include InfString h description all StringList methods see above join all elements together and return as a single string TABLE 3 8 Ptolemy A summary of the most useful methods of the StringList and InfString classes The 1 nfString class inherits all of the methods from St ringList add ing
275. only the cast to char Last updated 8 26 97 InfString and StringList these 3 10 Infrastructure for Star Writers Although these two classes are almost identical in design their recommended uses are guite different The first is designed for building up strings without having to be concerned about the ultimate size of the string New characters can be appended to the string at any time and memory will be allocated to accommodate them When you are ready to use the string perhaps by passing it to a function that expects the standard character array representation of the string then simply cast the object to char In fact InfString is publicly derived from StringList adding only the cast to char StringList is implemented as a list of strings where the size of the list is not bounded ahead of time St ringList is recommended for applications where the list structure is to be preserved The cast to char in InfString destroys the list structure consolidating all its strings into one contiguous string The most useful methods for both classes are summarized in table Since InfString differs by only one operator we show only that one operator A word of warning is in order If a function or expression returns a StringList or InfString and that value is not assigned to a StringList or InfString variable or refer ence and the const char or char cast is used it is possible likely under g that the StringList or In
276. ontal position of the point to plot toy the vertical position of the point to plot void addPoint add a single point to a particular data set int dataSet the number of the data set starting with 1 float the horizontal position of the point to plot float the vertical position of the point to plot void newTrace start a new trace disconnected from the previous trace int dataSet the data set for the new trace void terminate plot the data using the pxgraph program TABLE 3 2 A summary of the most useful methods of the XGraph class which provides a simple interface to the pxgraph program used for plotting data 3 3 3 Classes for displaying animated bar graphs The BarGraph class creates a Tk window that displays a bar graph that can be modi fied dynamically while a simulation runs An example with 12 data sets and 8 bars per data set is shown in figure 3 2 The most useful methods of the class are summarized in table 3 3 This class is directly usable only by stars linked into a pigi process not to stars linked into the interpreter ptc1 The reason for this is that ptc1 does not have the Tk code linked into it Correspondingly the class definition source code is in SPTOLEMY src pigilib rather than the more usual SPTOLEMY src kernel U C Berkeley Department of EECS The Almagest 3 5 BarGraph class include BarGraph h method description int setup start a fresh plot r
277. onversion and loading operators are designed to do the right thing when an attempt is made to convert between mismatched types Clearly we can convert an int to a double or Complex or a double to a Complex with no loss of information Attempts to convert in the opposite direction work as follows conversion of a Complex to a double produces the magnitude of the complex number Con version of a double to an int produces the greatest integer that is less than or equal to the double value There are also operators to convert to or from float and Fix Each particle also has a virtual print method so a star that writes particles to a file can accept anytype 2 4 3 States A state is defined by the state directive The star can use a state to store data values remembering them from one invocation to another They differ from ordinary members of the star which are defined using the public protected and private directives in that they have a name and can be accessed from outside the star in systematic ways For instance the graphical interface pigi permits the user to set any state with the A_SETTABLE attribute to some value prior to a run using the edit params command The interpreter provides similar functionality through the set state command The state attributes are set in the state direc tive A state may be modified by the star code during a run The attribute A_NONCONSTANT is used as a pragma to mark a state as one that gets modi
278. ortHole class is aMultiPorthole Connect this PortHole to a Geodesic create one if needed and tell that Geodesic to connect itself to both this PortHole and the destination PortHole Also provides the number of delays on this connection Initialize the PortHole In the case of output PortHoles this function will usually initialize the connected Geodesic as well Resolve the type of Particles with the PortHole it is connected to What to do to receive data from the Geodesic What to do to send data to the Geodesic Put a particle from the buffer into the Geodesic Get a particle from the Geodesic and put it into the buffer Returns numberTokens the number of Particles trans ferred per execution Returns the number of Particles inside the Geodesic Returns the number of initial delay on the Geodesic Returns a pointer to the Geodesic this PortHole is connected to Set the delay on the Geodesic Data type of particles in this porthole The Geodesic that this PortHole is connected to A pointer to the Plasma used to request new Particles Usually a CircularBuffer used to store incoming or outgo ing Particles The PortHole that we are connected to The size of the Buffer The number of Particles consumed or generated each time we access the Geodesic Note that PortHoles are generally separated into input PortHoles and output U C Berkeley Department of EECS The Almagest 17 5 PortHoles They aren
279. ory and then run mk dom cd PTOLEMY src domains yyy SPTOLEMY bin mkdom yyy 17 4 3 Required classes and methods for a new domain mkdom will create copies of key files in SPTOLEMY src domains yyy kernel and a Nop star in PTOLEMY src domains yyy stars The template files have various com ments about which methods you need to redefine The template files also define many function for you automatically If you aren t clear as to how to define the methods in each class it is best to try look at the existing Ptolemy domains as examples YYYDomain cc This file will be setup for you automatically so that you shouldn t need to modify much The various methods here return WormHoles and EventHorizons which should be defined in YYYWormhole A node is usually a type of Geode sic that allows multiple connections such as Aut oForkNode You can define your own YYYGeodesic or simply use the ker nel s AutoForkNode if that is suitable this is what SDF does YYYWormhole h cc Various methods to interface your new domain with others must be defined if you wish to use your domain with other domains Ptolemy Last updated 10 10 97 17 10 Creating New Domains However if you don t need to mix domains then you may skip these files Wormholes translate different notions of time or concurrency Since some domains are timed like DE and oth ers are not like SDF you must be able to convert from one to another YYYGe
280. other users run mkPtolemyTree to setup parallel development trees on the new domain MAKEARCH SPTOLEMY MAKEARCH is a bin csh script that c an already existing Ptolemy tree To add a domain to MAK reates or updates the object tree in FARCH edit the file and look for a similar domain and add appropriately A little trial and error may be necessary but the basic idea is simple MAKEARCH traverses directories and creates subdirectories as it sees fit Note that if MAKEARCH is under version control you may need to do chmod a x MAKEARCH when you check it back out or it won t be executable Continuing with our example 3 Edit MAKEARCH and add your domain yyy to the list of experimental domains set EXPDOMAINS cg56 cgc vhdlb vhdl mdsdf U C Berkeley hof ipus yyy Department of EECS The Almagest 17 11 This will cause a stars and kernel directory to be created in SPTOLEMY oDj SPTARCH domains yyy when MAKEARCH is run 4 Run MAKEARCH cd SPTOLEMY csh f MAKEARCH If you get a message like cxh watson 181 csh f MAKEARCH making directory users ptolemy obj sol2 domains yyy mkdir Failed to make directory yyy Permission denied yyy No such file or directory The you may need to remove your obj SPTARCH tree as MAKEARCH has probably traversed down a parallel tree created by mkPtolemyTree and come up in a direc tory that you do not own mkPtolemyTre
281. ount place to store the count for the given bin uble amp bin place to store the center of the given bin Center TABLE 3 4 A summary of the most useful methods of the Histogram class which creates his togram charts in a window and is available to stars running under pigi Histogram of noise samples FIGURE 3 3 An example of a histogram generated using the XHistogram Class U C Berkeley Department of EECS The Almagest XHistogram class method void initialize Block parent double binWidth cons hee LS options cons cons tc titie GC har r har har saveFile int max 1000 Bins void addPoint double y int numCounts return the number of data values used so far in the histogram double mean 3 7 include Histogram h description start a fresh histogram pointer to the block using the class the width of each bin bins are centered at integer multiples of this options to pass to the pxgraph program in addition to bar nl brw title to put on the histogram name of a file to save data to or 0 if none since bins are added as needed it is wise to limit their number add to the count of the bin within which the given data falls a data point for the histogram return the average value of all observed data so far double variance void terminate plot the histogram usi
282. ous event at a time This runtime overhead is reduced in the phase based firing mode In the phase based firing mode or simply the phase mode before executing a star the scheduler fetches all simultaneous events for the star The fetched events are stored in the internal queue of each input porthole The internal queue of inputs is created only if the star operates in phase mode In phase mode when a DE star fires it consumes all simultaneous events currently available It constructs a phase Afterwards other simultaneous events for the same star may be generated by a network of functional stars Then the star may be fired again with another set of simultaneous events which forms another phase We can set the operation mode of a star phase by calling method setMode PHASE in the constructor as summarized in table 12 1 on page 12 5 The following example is written in the simple mode go while input dataNew temp int input get input getSimulEvent If the star is re written using the phase mode it will look like constructor setMode PHASE go while input dataNew temp int input get Or go for int i input numSimulEvents i gt 0 i temp int input get The get method in phase mode fetches events from the internal queue one at a time After consuming all events from the queue now the queue is empty it resets the dat aNew flag If
283. owing events occur S CG 1 From the override mk file that the user specifies the script builds a tree with the directories as specified the value of the CUSTOM_DIRS makefile variable 2 Next the files in the PTOLEMY tree are copied over if the directory exists using tar to save modification times 3 For each directory specified by CUSTOM DIRS we create symbolic links to a ll the directories that we have not expanded from the SPTOLEMY tree the make tem plate and makefile symbolic links in the obj directories are set correctly Department of EECS The Almagest 1 11 4 The override mk file is copied into the new tree as NEW ROOT mk over ride mk where NEW ROOT is the root path name of the tree we are constructing 5 override mk files are constructed that reference NEW ROOT mk override mk specific to tysh ptcl and pigiRpc 6 make install is run in NEW_ROOT ob j PTARCH which creates the hard link for the libraries in NEW ROOT 1ib SPTARCH and builds the custom tysh ptcl and pigiRpc This new tree has all the symbolic links and directories necessary to act as a full fledged Ptolemy tree You should be able to set your PTOLEMY environment variable to this new tree and pigi will run your custom pigiRpc binary Currently the Tcl libraries and Tycho are not expanded but are accessible via symbolic links To have the utility expand the SPTOLEMY 1ib tc1 directory add the following line to your o
284. partment of EECS The Almagest 3 11 while string item 0 cout lt lt string lt lt n In this fragment myList is assumed to be a StringList previously set up 3 6 List Classes The StringList class is privately derived from the SequentialList class an extremely useful class used throughout Ptolemy This class implements a linked list with a running count of the number of elements It uses the generic pointer technique with typedef void Pointer Thus items in a sequential list can be pointers to any object with a generic pointer used to access the object In derived classes like StringList this generic pointer is converted to a specific type of pointer like const char The methods are summarized in table 3 10 An important point to keep in mind when using a SequentialList is that its destructor does not delete the elements in the list It would not be possible to do so since it has only a generic pointer Also note that random access by element number or any other method can be very inefficient since it would require sequentially chaining down the list SequentialList has an iterator class called List Iter The operator or next member function returns a Pointer In table 3 11 are two classes privately derived from SequentialList Queue and Stack The first of these can implement either a first in first out FIFO queue or a last in SequentialList class include DataStruct h method descript
285. pc depending on the kind of extensions you are making The first way uses src pigiExample and it is intended for users who just need to add new stars The second and third ways use the mkPtolemyTree script and csh aliases and are for users that are creating new domains or making other more extensive changes If you want to extend Ptolemy by modifying or adding a new scheduler target or even an entire domain it is recommended that you create a duplicate directory hierarchy This allows you to experiment with and fully test any changes separately rather than incorporating them into the official version of Ptolemy This way your experimentation will not interfere with other Ptolemy users at your site and your changes will not be overwritten by future installations of Ptolemy releases It also means that all of the existing makefiles will work without modification because all of the paths specified are relative to the root of the hierarchy The most direct way to do this is to copy the entire Ptolemy hierarchy This could be done with a command such as cp r SPTOLEMY ptolemy which would create a copy of the hierarchy in your home directory Because this method U C Berkeley Department of EECS The Almagest 1 7 reguires excessive disk space and makes cooperative development difficult many developers prefer to use symbolic links when creating a duplicate hierarchy mkPtolemyTree and the csh aliases can help you setup these sym
286. pecific to OutDEPort It sets the timeSt amp member of the port to the value given by its argument and returns a reference to the most recent particle from an output port Consider the line in the above example true put completionTime pp This says that we copy the particle pp to the output port with timeStamp completion Time We can send more than one output event to the same port by calling the put method repeatedly A new particle is returned each time 12 2 3 Sequencing directives A special effort has been made in the DE domain to handle simultaneous events in a rational way If two distinct stars can be fired because they both have events at their inputs with identical time stamps some choice must be made as to which one to fire A common strategy is to choose one arbitrarily This scheme has the simplest implementation but can lead to unexpected and counterintuitive results from a simulation The choice of which to fire is made in Ptolemy by statically assigning priorities to the stars according to a topological sort Thus if one of the two enabled stars could produce events with zero delay that would affect the other as shown in figure 12 1 then that star will be fired first The topological sort is actually even more sophisticated than we have indicated It follows triggering relationships between input and output portholes selectively according to assertions made in the star definition Thus the priorities are actually a
287. pers find it convenient to set the following aliases alias srcdir cd pwd sed s 0bj SPTARCH src 2 alias objdir cd pwd sed s 2 src 0bj SPTARCH For your convenience these can be found in the file SPTOLEMY alias They make it easy to move between the source directory and the corresponding object directory For example if you are running on a Sun machine running Solaris 2 4 U C Berkeley Department of EECS The Almagest 1 3 oe cd SPTOLEMY src kernel pwd users ptolemy src kernel objdir pwd users ptolemy obj sol2 kernel srcdir pwd users ptolemy src kernel AP oP AP NX oe oe 1 2 2 Directory Structure The documentation usually refers to the root of the Ptolemy directory tree as SPTOLEMY but occasional slips will refer to ptolemy Below this root you can find the directories indicated in figure 1 1 The src directory is key to much of what this volume deals with Its structure is shown in figure 1 2 Within the src directory the kernel directory is most important It con tains all the classes that define what Ptolemy is Second most important is the domains direc tory Its structure is shown in figure 1 3 This directory contains one subdirectory that defines each of the domains distributed with Ptolemy Each domain directory contains at least the sub directories shown in figure 1 4 If you are going to write stars for the SDF domain for exam pl
288. pgraded to use the new Cluster classes Thus the BDF and SDF schedulers should not be used as examples of how to do clustering in Ptolemy but rather the hierarchical SDF parallel scheduler PTOLEMY src domains cg hierScheduler can be used as a model The HierScheduler in the current version of Ptolemy is a prototype of the hierarchical parallel scheduler detailed in Pin95 In addition we have a specialized loop scheduler Mur94 which also uses the new cluster facilities The class Cluster is derived from the DynamicGalaxy and as such manages its own memory The Cluster classes use ClusterPorts which are derived from GalPort The main difference between the ClusterPorts and GalPorts is that ClusterPorts maintain a farSidePort pointer We need this change in ClusterPort in order to easily iterate over the Clusters at any level of the clustering hierarchy A ClusterPort far SidePort pointer will only be NULL if the ClusterPort is aliased to a Star PortHole connected at higher level of the clustering hierarchy 6 4 1 Initialization Flattening the User Specified Graph Clustering is done directly on the internal representation of the user specified graph Before we can begin to cluster the internal representation the irrelevant user hierarchy must be flattened The flattening is accomplished by creating a temporary Cluster instance and then invoking the Cluster initializeForClustering method on the Galaxy whose internals we want to cluste
289. pl You can now create your own version of DDFRepeater pl To later reinstate the official version e g you discovered that what you thought was a bug was in fact a feature o sw DDFRepeater pl The exp Alias When starting your experimentation the job of creating the parallel tree can be rather tedious The exp aliases combines the functions of the pt 1 and sw aliases into one making the common task of expanding a branch in the directory hierarchy easy Suppose you type o exp stars This is equivalent to the following sequence of commands mkdir stars sw stars cd stars DEL A JP oe de Note that the command leaves you in the new directory ready to issue another exp command For example to create a duplicate of the directory SPTOLEMY src domains ddf stars creating all subdirectories as you go and linking to all the appropriate files in the Ptolemy tree cd Ptolemy exp src exp domains exp ddf exp stars AJP AP AP AP de U C Berkeley Department of EECS The Almagest 1 15 The rm Alias The rm1 alias removes symbolic links in the current directory Without an argument it removes all the visible symbolic links Any arguments are passed on to the 1s command So to remove all symbolic links including those that are invisible use the a option o rml a You can also give file names as arguments to remove just some of the symbolic links o rml o The mk1 alias Suppose you wi
290. pported this function returns an error It is also an error if the argument is undefined or is a state that is not assigned to memory e g a parameter Note that this does NOT necessarily return the address of the beginning of a porthole buffer it returns the access point to be used by this star invocation and in cases where the star is fired multiple times this will typically be differ ent from execution to execution If the optional argument offset is specified the macro returns an expression that references the location at the specified offset wrapping around to the beginning of the buffer if that is necessary Note that this wrapping works inde pendent of whether the buffer is circularly aligned or not Sref name lt offset gt Ptolemy Last updated 10 17 97 13 12 Code Generation This macro is much like addr name only the full expression used to refer to this object is returned e g x 23 for a 56000 if name is in x memory If name is assigned to a register this expression will return the corresponding register The error conditions are the same as for addr Smem name Returns the name of the memory bank in which the given state or porthole has its memory allocated To have appear in the output code put in the codeblock For a domain where is a frequently used character in the target language it is possible to use a different character instead by redefining the virtua
291. proc goTcl_SstarID starID set inputVals grabInputs_SstarID set xin lindex SinputVals 0 set yin lindex SinputVals 1 setOutputs_SstarID expr xint yin U C Berkeley Department of EECS The Almagest 5 5 Unlike the previous example this script does not define any code that runs when the script is sourced during the setup phase of execution of the star Instead it simply defines a procedure with a name unique to the instance of the star This procedure reads two input values adds them and writes the result to the output Although this would be a very costly way to accomplish addition in Ptolemy this example nonethe less illustrates an important point If a Tcl script sourced by a Tc1Script star defines a procedure called goTc1 S starID then that procedure will be invoked every time the star fires The single argument passed to the procedure when it is called is the starID In this example the procedure uses grabInputs_ starID defined by the TclScript star to read the inputs The current input values are returned by this procedure as a list so the Tcl command 1 index is used to index into the list The final line adds the two inputs and sends the result to the output As shown in the previous example if the Tcl script defines the optional Tcl procedure goTcl_ starID then that procedure will be invoked every time the star fires It takes one argument the starID and r
292. provided otherwise use text itself as the key Code will be added to the stream only the first time that a particular key is used int addCompileOption const char text Add options to be used when compiling a C program The options are collected in the compileOptionsStream stream int addLinkOption const char text Add options to be used when linking a C program The options are collected in the 1inkOptionsStream stream The following streams which are used by the code generation methods just described are defined as members of the CGCTarget class in addition to the streams defined by the CGTarget class CodeStream include Include directives are added to this stream by the addInclude method of CGCStar CodeStream mainDecls Local declarations for variables are added to this stream by the addDeclaration method of CGCStar CodeStream globalDecls Global declarations for variables and functions are added to this stream by the addGlobal method of CGCStar CodeStream mainInit Initialization code is added to this stream when the addCode method is invoked from within the initCode method CodeStream mainClose Code generated when the addCode method is invoked from within the wrapup method of stars is placed in this stream CodeStream compileOptionsStream Options to be passed to the C compiler which have been added using the CGCStar addCompileOption method CodeStream linkOptionsStream Options to be passed to the linker whi
293. pt shared data structures Moni tors and condition variables are available to synchronize the execution of threads A monitor is 10 2 PN domain an object that can be locked and unlocked Only one thread may hold the lock on a monitor If a thread attempts to lock a monitor that is already locked by another thread it is suspended until the monitor is unlocked At that point it wakes up and tries again to lock the monitor Condition variables allow threads to send signals to each other Condition variables must be used in conjunction with a monitor a thread must lock the associated monitor before using a condition variable The scheduler in the PN domain creates a thread for each node in the program graph Each thread implements a dataflow process by repeatedly invoking the run method of a Star object The scheduler itself does very little work leaving the operating system to interleave the execution of threads The put and get methods of the class Geodesic have been re implemented using monitors and condition variables so that a thread attempting to read from an empty channel is automatically suspended and threads automatically wake up when data becomes available The classes Pt Thread PtGate and PtCondition define the interfaces for threads monitors and condition variables in Ptolemy Different implementations can be used as long as they conform to the interfaces defined in these base classes At different points in the devel opment of th
294. ptolemy 2 Verify that your LD_LIBRARY_PATH does not include libraries in another Ptolemy tree You could type unsetenv SLD_LIBRARY_PATH 3 gdb sources your cshrc so your SPTOLEMY and LD_LIBRARY_PATH could be different Inside gdb use show env PTOLEMY to see what it is set to This problem is especially common if you are running gdb inside emacs via ptgdb 4 Verify that you are running the right binary by looking at the creation times You may find it useful to use the rpc option pigi debug rpc SPTOLEMY obj SPTARCH pigiRpc pigiRpc mine ptdesign init pal 5 Recompile the problem files with optimization turned off and relink your pigiRpc You can do this with rm myfile o make OPTIMIZER install Then rebuild your pigiRpc 6 Look for weird coding styles that could confuse the line count in emacs and gdb such as declaring variables in the middle of a block and brackets that open a func tion body on the same line as the function declaration int foo int bar VS int foo int bar 7 Use stepi to step by instructions rather than step U C Berkeley Department of EECS Chapter 2 Writing Stars for Simulation Authors Joseph T Buck Soonhoi Ha Edward A Lee Other Contributors Most of the Ptolemy team 2 1 Introduction Ptolemy provides rich libraries of stars for the more mature domains Since the stars were designed to be as generic as possible many compl
295. r responding entry of the src matrix and converted as specified by the round argument Comparison operators int operator const XXXMatrix amp src Example if A B then Return TRUE if the two matrices have the same dimensions and every entry in A is equal to the corresponding entry in B Return FALSE other wise int operator const XXXMatrix amp src Example if A B then Return TRUE if the two matrices have different dimensions or if any entry of A differs from the corresponding entry in B Return FALSE oth erwise Conversion operators Each matrix class has a conversion operator so that the programmer can explicitly cast one type of matrix to another this casting is done by copying It would have been possible to make conversions occur automatically when needed but because these conversions can be quite expensive for large matrices and because unexpected results might occur if the user did not intend for a conversion to occur we chose to require that these conversions be used explic itly operator XXXMatrix const Example FloatMatrix C A FloatMatrix B Convert a matrix of one type into another These conversions allow the various arithmetic operators such as and to be used on matrices of different type For example if A in the example above is a 3 3 FloatMatrix and B is a 3 2 IntMatrix then Cisa FloatMatrix with dimensions 3 2 Destructive r
296. r This top level Galaxy will remain intact but all internal Galax U C Berkeley Department of EECS The Almagest 6 3 ies which pass the Cluster flattenGalaxy test will be flattened and deleted Thus any Scheduler and Target pointers to the top level Galaxy will not need to be updated because they do not change The necessary information from the user specified hierarchy is preserved automatically with the aid of the Scope class detailed in section 6 5 After the internals of the top level Galaxy have been flattened Clusters are con structed around each individual atomic Block In that way the scheduler writer can treat all the Blocks at each level except the innermost level as a Cluster This property is main tained through any sequence of merge absorb calls An example initializeForCluster ing invocation is shown in figure 6 1 frames and 2 A facility for restoring the internal Ptolemy representation back to the original user specified hierarchy is detailed in section 6 6 6 4 2 Absorb and Merge The basic clustering mechanisms are implemented with the virtual methods Clus ter merge and Cluster absorb Both of these methods can take up to two arguments The first argument is the Cluster to absorb merge and the second argument optional speci fies whether or not to remove the absorbed or merged Cluster from the original parent Gal axy The Cluster merge method takes the contents of the Cluster being merged and
297. r i 0 i lt N itt Sref output i sin i x A more complicated example follows codeblock cbLoop2 char portname int N double x for 1 0 i lt int length itt Sref portname i sin i x N In this example length is a data member of the star typically a state When called as cbLoop2 ina 3 0 2 it would generate assuming the value of length is 20 for 1 0 i lt 20 i stef ina i sin i 0 6666666 In order to trigger the C expression processing via escapes in codeblocks which would otherwise have no arguments add in a null argument list as in codeblock cbLoop3 for i1 0 i lt int length itt Sref output i sin i 0 1 In the example above the int length will be replaced with the value of the class member length The above example would be called with an empty argument list as go addCode cbLoop3 The complete parsing rules are ee gt double goes to single QATSIGN gt gt LBRACE gt LBRACE is literal string e gt RBRACE gt RBRACE is literal string a BACKSLASH gt BACKSLASH is literal string id gt C token id id is one or more alphanumerics expr SUG xpr expr expr is arbitrary with balanced U C Berkeley Department of EECS The Almagest 13
298. r to compute the order of execution of the Stars in the Galaxy Therefore creating a new Ptolemy simulation domain will typically involve writing new classes for Stars PortHoles WormHoles Targets and Schedulers Creating a new domain is a fairly involved process and not to be done lightly The first thing that many users want to do when they see Ptolemy is create a new domain However it is often the case that the functionality they need is already in either the SDF or DE domains or they can merely add a Target or Scheduler rather than an entire domain 17 2 A closer look at the various classes A simulation Domain can use the various classes mentioned above as they exist in the Ptolemy kernel or it can redefine them as needed For example in the SDF domain the classes SDFStar SDFPortHole SDFScheduler SDFDomain SDFTarget and SDFWormhole have all been defined Most of those classes inherit much of their functionality from the corre sponding kernel classes but the Domain creator is free to make major changes as well The kernel Geodesic Plasma and Particle classes are used without modification but other domains such as the CG domain have derived a subclass from Geodesic The Domain cre ator needs to decide whether or not existing Ptolemy classes can be used without change therefore it is a good idea to understand what functionality the kernel classes provide The following is a brief description of the various classes that either
299. ration hinclude Matrix h needs to be in the Star definition Otherwise the declaration ccinclude Matrix h is sufficient To declare an input porthole that accepts matrices the following syntax is used input name inputPortHole type FLOAT_MATRIX_ENV The syntax is the same for output portholes The type field can be COMPLEX_MATRIX_ENV FLOAT_MATRIX_ENV FIX_MATRIX_ENV or INT_MATRIX_ENV The icons created by Ptolemy will have terminals that are thicker and that have larger arrow points than the termi nals for scalar particle types The colors of the terminals follow the pattern of colors for scalar data types e g blue represents Float and FloatMatrix Input portholes The syntax to extract a matrix from the input porthole is Envelope inPkt inputPortHole 0 getMessage inPkt const FloatMatrix amp inputMatrix const FloatMatrix inPpkt myData The first line declares an Envelope which is used to access the matrix Details of the Enve lope class are given in Use of the Envelope class on page 4 17 The second line fills the envelope with the input matrix Note that because of the reference counting mechanism this line does not make a copy of the matrix The last two lines extract a reference to the matrix U C Berkeley Department of EECS The Almagest 4 31 from the envelope It is up to the programmer to
300. rations PtCondition notEmpty This data member points to a condition variable used for block ing read operations when the channel is empty PtCondition notFull This data member points to a condition variable used for block ing write operations when the channel is full int cap This data member represents the capacity of the communication channel and determines when it is full static int numFull This static data member records the number of full geodesics in the system The slowGet method shown in below implements the get operation for communica tion channels The entire method executes within a critical section to ensure consistency of the object s data members If the buffer is empty then the thread that invoked slowGet is sus pended until notification is received on notEmpty Data is retrieved from the buffer and if it is not full notification is sent on not Full to any other thread that may have been waiting Particle PNGeodesic slowGet Avoid entering the gate more than once CriticalSection region gate while sz lt 1 amp amp notEmpty notEmpty gt wait SIES Particle p pstack get if sz lt cap amp amp notFull notFull gt notifyA1ll return p U C Berkeley Department of EECS The Almagest 10 11 The slowPut method shown below implements the put operation for communication channels The entire method executes within a critical section to ensure consistency o
301. rder will be periodic The SDF domain in Ptolemy is one of the most mature with a large library of stars and demo programs It is a simulation domain but the model of computation is the same as that used in most of the code generation domains A number of different schedulers including parallelizing schedulers have been developed for this model of computation We assume in this very short chapter that the reader is familiar with the SDF model of computation Refer to the User s Manual Moreover we assume the reader is familiar with chapter 2 Writing Stars for Simulation Since most of the examples given in that chapter are from the SDF domain there is only a little more information to add here 7 2 Setting SDF porthole parameters All stars in the SDF domain must follow the basic SDF principle the number of parti cles consumed or produced on any porthole does not change while the simulation runs These numbers are given for each porthole as part of the star definition Most stars consume just one particle on each input and produce just one particle on each output In these cases no special action is required since the porthole SDF parameters will be set to unity by default However if the numbers differ from unity the star definition must reflect this For example the FFTCx star has a size parameter that specifies how many input samples to read The value of that parameter specifies the number of samples required at the input in ord
302. reams simulatorCmds Collects the commands to configure the Motorola DSP simula tor shellCmds Collects the commands that will be used in a shell script to start the run The resultant script simply invokes the simulator with the file generated from simulatorCmds 15 4 2 S56XTarget S56XTargetWH Code Streams aioCmds Collects the GUI specification which is interpreted by qdm or gslider shellCmds Collects the commands that will be used in a shell script to start the run The resultant script can start qdm or gslider In the case of the S56XTarget it might also download and run the gener ated code on the S 56X dsp card U C Berkeley Department of EECS The Almagest 16 1 Chapter 16 C50 Domain Authors Luis Gutierrez 16 1 Introduction The C50 domain generates assembly code for the Texas Instruments C5x series of pro cessors Chapter 13 describes the features common to all code generation domains The basic principles of writing code generation stars are explained in section 13 2 You will find expla nations for codeblocks macros and attributes there This chapter explains features specific to the C50 domain Refer to the C50 chapter in the Ptolemy User s Manual for an introduction to these domains 16 2 Data Types The supported CG50 data types are int intarray fix fixarray In addition the complex data type is supported for portholes but not states A com plex number is stored as a sequence of two 16 bit
303. rgets Methods defined here include virtual methods to gener ate display compile and run the code Derived targets are free to redefine these virtual meth ods if necessary Code streams A code generation target manages code streams which are used to store star and target generated code The CGTarget class has the two predefined code streams myCode and pro U C Berkeley Department of EECS The Almagest 13 17 cedures The myCode stream is referred to as CODE and the procedures Stream is called PROCEDURE these names should be used when referring to these streams as in Code Stream code getStream CODE Derived targets are free to add more code streams using the CGTarget method addStream stream name For example the default CGC target defines fourteen additional code streams Other methods such as addProcedure code uniquename can be defined to provide a more efficient or convenient interface to a specific code stream in this case proce dures With addProcedure it becomes clear why unique names are necessary Recall that addProcedure is used to declarations outside of the main body of the code For example say we wanted to write a function in C to multiply two numbers The codeblock to do this could read codeblock sillyMultiply A silly function double SsharedSymbol silly mult double a double b double m m a D return m Note that in this codeblock we used the sharedSymbo
304. rovides the quickest and easiest path to a customized user interface The icon can take any number of forms including the following Wy i y mat gt TclScript TelScript TelScript TelScript TelScript TY DS 1 Ty Tcl Tcl Tcl Tcl TelScript TelScript TelScript TelScript gt gt gt gt Tol TaL Tel 7 Ta All of these icons refer to the same star but each has been customized for a particular number of input and output ports You should select the one you need on the basis of the number of Y Ptolemy Last updated 10 10 97 5 2 Using Tcl Tk input and output ports required The left most icon has an unspecified number of inputs and outputs as indicated by the double arrows at its input and output ports The TclScript star has one parameter settable state tcl_file A string giving the full path name of a file containing a Tcl script The Tcl script file specifies initialization commands for example to open new windows on the screen and may optionally define a procedure to be invoked by the star every time it runs We begin with two examples that illustrate most of the key techniques needed to use this star Example 1 Consider the following simple schematic in the SDF domain Tel Er TclScript ShowValues The TkShowValues Star is in the standard SDF star library It displays whatever input values are supplied
305. rovides a convenient method for manipulating Ptolemy Last updated 4 17 97 10 8 PN domain PtGate objects preventing some common programming errors The class PNGeodesic uses all of these classes to implement a communication channel 10 3 1 PtGate A PtGate can be locked and unlocked but only one thread can hold the lock Thus if a thread attempts to lock a PtGate that is already locked by another thread it is suspended until the lock is released virtual void lock 0 This protected method locks the PtGate object for exclusive use by one thread virtual void unlock 0 This protected method releases the lock on the PtGate object 10 3 2 PosixMonitor The class PosixMonitor provides an implementation for the interface defined by PtGate It has a single protected data member pthread_mutex_t thread A handle for the POSIX monitor associated with the Posix Monitor object The implementations of the lock and unlock methods are shown below void PosixMonitor lock pthread_mutex_lock amp mutex void PosixMonitor unlock pthread_mutex_unlock amp mutex 10 3 3 CriticalSection The class CriticalSection provides a convenient mechanism for locking and unlocking PtGate objects Its constructor shown below locks the gate Its destructor also shown below unlocks the gate To protect a section of code simply create a new scope and declare an instance of CriticalSection
306. rred on the previous run Thus between invocations of the begin method either the wrapup method or the constructor for the star and all its members will be invoked The constructor for Sequent ialList also initializes the list so the list is always initialized before the first begin method is called The above approach is somewhat limited You may want more than one type of star to share a data structure In this case you should create a common base class for all the stars that will share the data structure The shared data structure should be a protected member rather than a private member so that it is accessible to derived stars Alternatively you might want arbitrary subsets of stars to share distinct data struc tures one for each subset This can be accomplished by defining a static list that is indexed by a string and using a parameter in the star to identify to which subset it belongs An efficient data structure to use for this is the HashTable So for example suppose we wanted to modify the above star to create lists of stars with common values of a parameter mySubset and to output the number of stars in their subset The above code becomes defstar Ptolemy Last updated 8 26 97 3 16 Infrastructure for Star Writers name BetterShar domain SDF desc A star with a shared data structure hinclude DataStruct h hinclude HashTable h output name howmany type int state
307. rs t if smallest NULL geo gt capacity lt smallest gt capacity smallest geo if smallest NULL smallest gt setCapacity smallest gt capacity 1 return fullBuffers 10 5 Programming Stars in the PN Domain Unlike portholes in the SDF domain the number of tokens consumed by an input or produced by an output can be dynamic in the PN domain This is indicated with the P_DYNAMIC porthhole attribute input name a type int attributes P_DYNAMIC For dynamic ports it is necessary to invoke the receiveData and sendData meth ods explicitly Note that the receiveData method must be used to initialize outputs For static ports the receiveData and sendData methods are invoked implicitly and should not be used in the go method Because a separate thread of execution is created for each star the go method of a PN star is not required to terminate As a programmer you are free to use infinite loops such as while TRUE within the go method of your PN stars This may be necessary if you access a porthole requiring a blocking read before entering the main loop of the process In the future such code could be placed in the star s begin method but currently as of release 0 6 the begin method is executed before the star s thread is created lt go Read both inputs the first time a receiveData b receiveData while TRUE output receiveData Ini
308. rt and the fractional part the binary point lies at a fixed Ptolemy Last updated 10 10 97 4 4 Data Types position in the bit pattern Its position represents a trade off between precision and range If the binary point lies to the right of all bits then there is no fractional part Constructing Fixed point variables Variables of type Fix are defined by specifying the word length and the position of the binary point At the user interface level precision is specified either by setting a fixed point parameter to a value precision pair or by setting a precision parameter The former gives the value and precision of some fixed point value while the latter is typically used to specify the internal precision of computations in a star In either case the syntax of the precision is either x y or m n where x is the num ber of integer bits including the sign bit y and m are the number of fractional bits and n is the total number of bits Thus the total number of bits in the fixed point number also called its length is x y or n For example a fixed point number with precision 3 5 has a total length of 8 bits with 3 bits to the left and 5 bits to the right of the binary point At the source code level methods working on Fix objects either have the precision passed as an x y or m n string or as two C integers that specify the total number of bits and the number of integer bits including the
309. rtHole the setBDF Params method described in BDF Domain on page 8 1 is not available for code generation stars Use the setRelation method of DynDFPortHole instead void setRelation DFRelation relation DynDFPortHole assoc Specify the relation of this port with the associated porthole assoc There are five possible values for relation DF_NONE no relationship DF_TRUE produces consumes data only when assoc has a TRUE particle DF_FALSE produces consumes data only when assoc has a FALSE particle DF_SAME signal is logically the same as assoc DF_COMPLEMENT signal is the logical complement of ASSOC For example the following statements describe the relationships among the portholes of the Switch block trueOutput setRelation DF TRUE control U C Berkeley Department of EECS The Almagest 14 7 falseOutput setRelation DF FALSE control 14 7 Tcl Tk Stars The CGCTclTkTarget class defines the tkSetup stream for Tcl Tk stars There is no special code generation function for this stream so its name must be used with addCode This is usually done from within the initCode method addCode codeblock tkSetup The following functions which are defined in the file tkMain c can be used within codeblocks of Tcl Tk stars in the CGC domain void errorReport char message This functions creates a pop up window containing message void makeEntry char window char nam
310. rue put completionTime pp else false put completionTime pp The Switch star has two input portholes input and control When an event arrives at the input porthole it routes the event to either the true or the false output porthole depending on the value of the last received cont rol input In the go method we have to check whether anew input event has arrived If not then the firing was triggered by a cont rol input event and there is nothing to do We simply return If the input is new then its particle is read using get method as summarized in table 12 1 In addition the most recent value from the control input is read This value is used to determine which output should receive the data input The statements in the constructor will be explained below in Sequencing directives on page 12 6 There are three ways to access a particle from an input or output port First we may use the operator followed by an integer which is equivalent to the same operator in the SDF InDEPort class method description Particle amp operator get a particle from the porthole without resetting dataNew void before simultaneous inputs here should be processed before those at p GenericPort p int dataNew flag indicating whether the porthole has new data Particle get get a particle from the porthole and reset dataNew void getSimulE fetch a simultaneous event from the global event queue int numSimulEvents re
311. ry pigiRpc ptrim This binary contains SDF DE BDF DDF and CGC domains only pigiRpc ptiny This binary contains SDF no image stars and DE domains only Each of the above versions can also be built as a debug version that contains debug ging information The file SPTOLEMY mk ptbin mk contains rules to build the above bina ries in combination with debugging and other features The file SPTOLEMY mk stars mk contains rules that indicate dependencies between domains and other features 1 3 Creating Custom Versions of pigiRpc Ptolemy is an extensible system Extensions can take the form of universes and galax ies which are viewed by Ptolemy as applications but they can also take the form of additional code linked to the Ptolemy kernel New stars can be dynamically linked see Writing Stars for Simulation on page 2 1 Other additional code has to be linked in statically If you add many of your own stars to the system you will want these stars to be statically linked as well so that you do not have to wait for the dynamic linking to complete every time you execute your applications The Ptolemy kernel and vem the schematic editor run in separate Unix processes The Ptolemy kernel process is called pigiRpc while the vem process is called vem You can create your own version of pigiRpc that contains your stars and other extensions perma nently linked in There are at least three ways to build your own pigiR
312. ry in A A and B must have the same dimensions operator xxx value Example A value Subtract the scalar value from each entry in the matrix operator const XXXMatrix src Example A B Perform the operation A entry i B entry i for each entry in A A and B must have the same dimensions Note this is an elementwise operation and is not equivalent to A A B operator xxx value Example A value Multiply each entry of the matrix by the scalar value operator const XXXMatrix amp src Example A B Perform the operation A entry i B entry i for each entry in A A and B must have the same dimensions operator xxx value Example A value Divide each entry of the matrix by the scalar value The scalar value must be non zero Department of EECS The Almagest 4 27 XXXMatrix amp operator identity Example A identity Change A to be an identity matrix so that each entry on the diagonal is 1 and all off diagonal entries are 0 Non destructive operators these return a new matrix XXXMatrix XXXMatrix XXXMatrix XXXMatrix XXXMatrix XXXMatrix operator Example B A Return a new matrix such that each element is the negative of the ele ment of the source operator Example B Return a new matrix that is the transpose of the source operator Example B A Return a new matrix which is the inver
313. s 13 2 2 Codeblocks with arguments Simple codeblocks as described above have a name and are implemented as static member strings Extended codeblocks have a name optional arguments and are implemented as non static functions They have an escape mechanism so that C expressions may be evaluated at run time and inserted into the generated code However in order to take advan tage of this escape mechanism a codeblock must be defined and called with arguments even if those arguments are empty An example codeblock cbLoop int N double x for i 0 i lt N itt Sref output i sin i x This defines a codeblock named cbLoop with two arguments N and x The variable i will appear in the generated code while the C expressions N and x are escaped by and will be evaluated at code generation time When this is called as chLoop 5 0 1 the following string will be returned for i 0 i lt 5 i Sref output i sin i 0 1 This might be used within a go method as go addCode cbLoop 5 0 1 The addCode method will process the ref macro as described elsewhere More com plicated expressions are allowable In general the clause may be delimited by parentheses and and must be operator lt lt printable The above codeblock could have been equiva lently declared as Ptolemy Last updated 10 17 97 13 6 Code Generation codeblock cbLoop int N double x fo
314. s Authors Joseph T Buck Michael J Chen Alireza Khazeni Other Contributors Brian Evans Paul Haskell Asawaree Kalavade Tom Lane Edward A Lee John Reekie 4 1 Introduction Stars communicate by sending objects of type Particle A basic set of types includ ing scalar and array types built on the Particle class is built into the Ptolemy kernel Since all of these particle types are derived from the same base class it is possible to write stars that operate on any of them by referring only to the base class It is also possible to define new types that contain arbitrary C objects There are currently eleven key data types defined in the Ptolemy kernel There are four numeric scalar types complex fixed point double precision floating point and integer described in Section 4 2 Ptolemy supports a limited form of user defined type the Message type described in Section 4 3 Each of the scalar numeric types has an equivalent matrix type which uses a more complex version of the user defined type mechanism they are described in Section 4 4 There are two experimental types included in the basic set containing strings and file references described in Section 4 5 Ptolemy allows stars to be written that will read and write particles of any type this mechanism is described in Section 4 6 Finally some experimental types that are not officially supported by Ptolemy are described in Section 4 7 4 2 Scalar Numeric Types Th
315. s 1 21 self scheduling STAT ee ee ee Re Ge ee RR 12 8 Send Staf RE ED EEN Ee see 13 23 Send Receive Star ee ee ee ee 13 23 send receive StATS ie ee Ge ee 13 23 sendData method ee ee ee 8 2 12 5 sequencing directives in DE ees se see ee ee ee 12 6 Seguentiall ist se sees se ee RR Ee ek Se Se ee ERA 3 15 SequentialList class ee ee ee ee ee ee RR 3 11 Server DE block ese ee ee ee ee ee ee ee 12 1 server stars in DE sees se ee ee se ee se ee ee ee 12 3 setAttibututes method ee ee 2 26 setAttributes method 00 0 ee ee ee 2 26 setBDFParams BDFPortHole method 14 6 setBDFParams method BDFPortHole clas ie ee ee ee 9 1 setInitValue method ee ee Ge ee ee 2 26 setOutputs starlD ees ee ee ee ee ee ee 5 4 5 5 setSDFParams method iese 2 12 2 19 7 1 setstate command ee ee ee ee ee 2 21 setup method ee ee ee ee ee ee oe ee ee ee ee ee 7 1 setup ptlang directive ees ee 2 6 2 13 shared data structures ie ee ee ee 3 14 sin Dit eth ei ee ER n 4 4 signal generators in DE esse se ee se ee ee ee 12 8 simple mode in DE eee sesse ee ee ee ee ee ee 12 11 SIMPLE de oe SE Ee ee ee GE se Ge Gee ee 12 11 simultaneous events DE domain ese ese 12 6 sol2 CfTONE ee ee ee ee ee ee ee 1 2 source code ee ee ee ee ee 1 1 source code control ee ee Ge ee ee 1 18 source stars in DE eee ee ee ee se ee ee ee 12 8 Spread CGC ive deputies eed dese Ee calcd eek Dek
316. s 3 when the above program is run the generated code will be Sref output Sref input 1 Sref input 2 Sref input 3 n Currently only the pre defined methods start go exect ime etc are processed this way not user defined methods Ptolemy Last updated 10 17 97 13 8 Code Generation 13 2 4 Macros In code generation stars the inputs and outputs no longer hold values but instead cor respond to target resources where values will be stored for example memory locations regis ters in assembler generation or global variables in C code generation A star writer can also define states which can specify the need for global resources A code generation star however does not have knowledge of the available global resources or the global variables tables which have already been defined in the generated code For star writers a set of macros to access the global resources is provided The macros are expanded in a language or target specific manner after the target has allocated the resources properly In this section we discuss the macros defined in the CGStar class Sref name Returns a reference to a state or a port If the argument name refers to a port it is functionally equivalent to the name 0 operator in the SDF simulation stars If a star has a multi porthole say input the first real porthole is input 1 To access the first porthole we use Sref input 1 or Sref input internal state where internal state Is t
317. s is usually only used by the Domains and not changed by the authors of new Domains Major methods put get 17 2 7 Particle Return an unused Particle to the Plasma Get an unused Particle or create one if needed The various Particle types supported by Ptolemy Currently the types are Float Ptolemy Last updated 10 10 97 17 6 Creating New Domains Int Complex Fix and Message The Message Particle is used to carry Messages inside Envelopes which can be almost anything For example the Matrix class is trans ferred using Message Particles These classes are also only used as is by the Domains and not redefined for new domains 17 2 8 Scheduler Sets up the execution by determining the order in which each Star of the Galaxy will fire Execution is performed using two main methods setup and run Schedulers can be timed or untimed depending on the Domain s model of execution This class will usu ally be different for each domain although some domains reuse the Scheduler of another domain if the Scheduler is appropriate for the new domain s model of computation Major methods setup Checks the Stars in the Galaxy initializes them and creates a schedule run Run the schedule computed in setup Major data members myGalaxy The pointer to the Galaxy that the Scheduler is working on myTarget The pointer to the Target which is controlling the execution 17 3 What happens wh
318. s might deallocate Pointer p memory int hasKey return l if the given key is in the table 0 otherwise const char key void insert insert an entry any previous entry with the same key is const char key replaced and the cleanup method is called so that in Pointer data derived classes its memory can be deallocated Pointer lookup lookup an entry in a derived class this could be over const char key loaded to return a pointer of a more specific type t remove remove the entry with the given key from the table note const char key that the object pointed to by the entry is not deallocated t size return the number of entries in the hash table TABLE 3 12 Asummary of the most useful methods of the HashTable class rized in table 3 13 Only the most useful and easily used methods are described You may want to refer to the source code for more information The HashTable class has a standard iterator called HashTablelter where the next method and operator return a pointer to class HashEnt ry This class has a const char key method that returns the key for the entry anda Pointer value method that returns a pointer to the entry Text Table has an iterator called Text TablelIter where the next method and operator return type const char Sophisticated users will often want to derive new classes from HashTable The rea son is that the methods that look up data in
319. s sees 2 6 2 13 determinism cht Ge Ee AG est eessen 12 12 discrete event DE domain eee 12 1 divide by zero bed eC aera ea eee nea eer 4 4 DL Scheculer iese ee ee Ge RR RR RR 13 22 domain AR EE ES 7 1 domain ptlang directive e ese see ee ee ee ee ee 2 5 2 6 DownCounter DDF star sesse sesse see ee ee 8 2 dummy Message ese ee ee ee ees 4 17 4 18 4 31 Ptolemy l 3 duplicate directory te ee ee ee ee ee ee ee ee 1 12 dynamic linking ese ee se ek ee ee ee ee 2 1 3 1 permanent sesse se seek ek see ee RR AE ee Se Se ee 2 3 dynamic porthol ee esse ee se ee ee ee Re RR ee n 8 1 DynDFStar ClaS esse ese se se ek ee SR Re RR RR 8 2 E edit params command see ee ee ee 2 21 2 26 Edwarda Se Es ee be es ee ee ee Ee 11 1 CMACS 34 0 AE Gh eh ER De 1 26 empty method Envelope cla ees ese ee ee ee ee es 4 17 Envelope class c ccccscscssesesessseeesceeessscecees 4 14 4 17 environment variables PT DEBUG prenen Es eer Se Ee ER Re OR Gee Dee 1 26 PIARGEEH SEER EES DEE SE GP Roast 1 2 PTOLEMY se gel E Ee es 1 2 id ER AE OR N OE 3 1 Evans Be SR ER GE DS Ge 4 1 10 1 ESTA ORE ke ER EEEN 12 1 event generator eene se ee ese oe Se eek Ge ee GR RR 12 9 exectime ptlang directive ee ee ee ee ee ee Re 2 6 execTime method ee ee ee 13 2 OX PAN AS Ee oer ee tues De ER EE Ee Ge Ge DE ge 1 12 expandPathName ee ese ee ee ee ee ee RR Re 3 3 expandPathName function ee ees
320. s to be executed and compared quickly and easily Implementation 14 4 1 C code generated to support command line arguments A sample of the additional code generated to support command line arguments is shown below struct double FOO double BAR arg_store 1 0 0 01 void set_arg_val char arg ant is for i 1 arg i i if stremp arg i help I stremp arg i HELP N stremp arg i h printf Settable states are n FOO tdefault 1 0 n BAR tdefault 0 01 n exit 0 if strcemp arg i FOO if arg i 1 arg_store FOO atof arg i 1 Ptolemy Last updated 8 26 97 14 4 CGC Domain continue if strcemp arg i BAR if arg i 1 arg_store BAR atof arg i 1 continue main function main int argc char argv double value 11 double value 12 End of Declaration set arg val argv Begin of Initialization value 12 arg store BAR value 11 arg store FOO Code The default values set by the edit parameters command are stored in the struct arg_store The function set arg val argv scans the list of command line arguments for FOO and BAR and sets the corresponding member in arg_store It also builds up the help message consist of the settable state names and their default values to be printed when the program receives a h help or HELP option The state values ar
321. s to be run universe gt run InterpUniverse run Runnable run target gt run sched run SDFScheduler run The domain specific Scheduler s run function Let s look at what a typical scheduler does when it runs a star SDFScheduler run Checks if there has been an error in the last iteration Calls 41 runOnce for each iteration runOnce Goes through each Star on the Lf schedule which is a list of Stars computed by setup and calls pid star gt run star gt run DataFlowStar run The SDF domain uses the general DataFlowStar run function A new Domain might want to redefine this Ports gt receiveData Calls receiveData for each of the PortHoles for this Star Bi Output PortHoles would do nothing in this case but input PortHoles would get Particles from the Geodesic Star run SimControl doPreActions Execute pre actions for a star go Call the Star specific go function that will process the input data and generate data to be put in the output PortHoles SimControl doPostActions Execute post actions for a star Ports gt sendData Calls sendData for each of the ortHoles for this Star P Input PortHoles would do nothing Lf in this case but output PortHoles would put their Particles into the Geodesic and refill their buffers with empty Particles fro
322. s to each output input name input type ANYTYPE outmulti name output types input Ptolemy Last updated 10 10 97 4 36 Data Types MPHIter nextp output PortHole p while p nextptt 0 p S0 input 0 Notice how in the definition of the output type the star simply says that its output type will be the same as the input type ptlang translates this definition into an ANYTYPE output porthole and a statement in the star constructor that reads output inheritTypeFrom input as you can see by examining the cc file generated for SDFFork During galaxy setup the Ptolemy kernel assigns actual types to ANYTYPE portholes making use of the types of connected portholes and inheritlypeFrom connections For exam ple if a Fork s input is connected to an output porthole of type INT the Fork s input becomes type INT and then so do its output s thanks to the inheritTypeFrom connection At runtime there is no such thing as an ANYTYPE porthole every porthole has been resolved to some spe cific data type which can be obtained from the porthole using the resolvedType method However this mechanism does not distinguish among the various subclasses of Message so if you are using Message particles you still need to check the actual type of each Message received Porthole type assignment is really a fairly complex and subtle algorithm which is dis cussed further in the Ptolem
323. sage ClaSS i sees ee ee ee ee 4 16 4 18 Closing Application error message ees 1 21 code ptlang directive ese ee ee 2 6 2 15 code stream AOC MS EE EE EER EE ER PG EES TA 15 2 ShellEdSs EE EE GE EG EE EE ED ig 15 2 simulatorCmds ee ee ee ee ee 15 2 code StrEaMS ee ee ie ee ee ee 13 16 Codeblock anne ea AA EA ee ee 13 3 codeblock ptlang directive ese ee ee ee ee 2 6 codeGenlnit method ie ee ee 13 18 CodeStream Class ii ee ee ee ee 13 16 Colet t GC tit ee ens 13 15 collect Staf ee Ge ee ee ee ee 13 24 Collect star EERS RE ED RS RE EE 13 15 COLDS is RE ee ee ee ee ER 5 12 COmmMPair ee rarna ee ee 13 27 U C Berkeley communication netWOTKS ee ee A 14 12 1 compileCode method ee ee ee 13 18 compile time scheduling c ccccesseseeeeeeeseseeees 2 13 Complex Clas ee ee 2 21 2 22 4 2 4 3 RO Ee ee sents Ps as 4 2 ET TEN 4 3 Operator uranian EnA EEEE 4 2 OpETatOT eeue ee ee ee ee ee ee ee ee ee ee ee 4 2 AN OPCTALOM etos see OER es eee vei ce Mocs ee 4 2 FS SE EE aa s 4 2 operators hk GEE RE GE Es areas 4 3 ET EE 4 2 2 OpelAatOr EE taken 4 2 OPCLAtOL ee ee ee ee ee ee ee ee ee ee ee ee 4 2 OPerator EE ESELS RR EE RE es 4 3 abs FUNCHON ee ee ee ee ee ee ee ee ee ee 4 3 arg funCHOR ees ee ee ee ee ee ee ee ee ee ee ee ee ee 4 3 basic Operators eeue ee ee ee ee ee ee ee ee ee 4 2 conj FUNCTION ee ee ee ee ee ee ee ee 4 3 COMSUEUCLOLS ese ee ee ee ee ee ee ee ee ee
324. se of the source N operator int exponent Example B AN2 Return a new matrix which is the source matrix to the given exponent power The exponent can be negative in which case the exponent is first treated as a positive number and the final result is then inverted So A 2 A A and A 3 A A A transpose Example B A transpose This is the same as the instead of as an operator operator but called by a function name inverse Example B A inverse This is the same as the operator but called by a function name instead of as an operator ComplexMatrix conjugate Example ComplexMatrix B A conjugate Return a new matrix such that each element is the complex conjugate of the source This function is defined for the ComplexMat rix class only ComplexMatrix hermitian Ptolemy Example ComplexMatrix B A hermitian Return a new matrix which is the Hermitian Transpose conjugate transpose of the source This function is defined for the ComplexMa trix class only Last updated 10 10 97 4 28 Data Types Non member binary operators XXXMatrix XXXMatrix XXXMatrix XXXMatrix XXXMatrix XXXMatrix XXXMatrix XXXMatrix U C Berkeley operator const XXXMatrix right Example A B C Return a new matrix which is the sum of the first two The left and right source matrices must have the same dimensions const XXXMatrix amp le
325. sen sitive actions and conditional code generation There are several additional code generation methods defined in the CGC domain The addinclude method is used to generate include file directives The addDeclaration method is used to declare local variables within the main function The addGlobal method is used to declare global variables outside the main function As with addCode these methods return TRUE if code was generated for the appropriate stream and FALSE otherwise These methods are member functions of the CGCStar class int addinclude const char file Generate the directive include file in the include stream The string file must include quotation marks file or angle brackets lt file gt around the name of the file to be included Only one include file directive will be generated for the file even if addInclude is invoked multiple times with the same argument Return TRUE if a new directive was generated int addDeclaration const char text const char name NULL Add text to the mainDecls stream Use name as the identify ing key for the code fragment if it is provided otherwise use Ptolemy Last updated 8 26 97 14 2 CGC Domain text itself as the key Code will be added to the stream only the first time that a particular key is used int addGlobal const char text const char name NULL Add text to the globalDecls stream Use name as the identi fying key for the code fragment if it is
326. setSDFParams 1 taps size 1 go double out 0 0 for int i 0 i lt taps size i out taps i double signaliIn i signalOut 0 lt lt out Notice the setup method this is necessary to allocate a buffer in the input PortHole large enough to hold the particles that are accessed in the go method Notice the us method of the FloatArrayState We now illustrate an ptc1 interpreter session using the above FIR star e of the size Assume there is a galaxy called singen that generates a sine wave you can use it with the FIR star as in star foop singen star fir FIR star printer Printer U C Berkeley Department of EECS The Almagest connect foop output fir signalin connect fir signalOut printer input print fir Star mainGalaxy fir States in the star fir mainGalaxy fir taps type FloatArray initial value O040609 001628 17853 001628 040609 current value 0 040609 001628 17853 37665 517853 0 0 0 1 2 3 add 665 4 5 6 7 001628 040609 2 25 39 1669 43 TOGS 11853 Then you can redefine taps by reading them from a file foo which contains the data 1 1 HA 2 33 4 4 The resulting interpreter commands are setstate fir taps lt foo 5 5 print fir Star mainGalaxy fir States in the star fir mainGalaxy fir taps type FloatArray initial value lt foo 5 5
327. sh to compile your change to the DDFRepeater pl file as above You will need to make an object tree Assume you are on a Sun Solaris 2 x platform You have created a parallel tree already in Ptolemy src Le Ptolemy src domains ddf stars exists Create the corresponding object tree ae cd Ptolemy exp obj sol2 exp domains exp ddf exp stars pwd users me Ptolemy obj sol2 domains ddf stars A A oe de oe The directory in which you are now located contains symbolic links to the o files and make files in the official Ptolemy tree If you run make here your replacement DDFRepeater pl star will be compiled in place of the official one If you run make install then a library will be created and installed in the directory Ptolemy 1lib so12 assuming this directory exists Running make as above uses the makefiles in the official Ptolemy tree because you have symbolic links to them Suppose you wish to modify the make template file in Ptolemy src domains ddf stars In this case you should run the mk1 alias to replace the makefile symbolic links If you have followed the above steps try this pwd users me Ptolemy obj sol2 domains ddf stars ls F DDFCase o DDFRepeater o libddfstars a DDFDownCounter o DDFSelf o make template DDFEndCase o DDFThresh o makefile DDFLastOfN o ddfstars o This assumes that the official Ptolemy has been rebuilt after being installed otherwise the o
328. sign bit that is n and x For example suppose you have a star with a precision parameter named precision Consider the following code Fix x Fix const char precision if x invalid Error abortRun this Invalid precision The precision parameter is cast to a string and passed as a constructor argument to the Fix class The error check verifies that the precision was valid There is a maximum value for the total length of a Fix object which is specified by the constant FIX MAX LENGTH in the file SPTOLEMY src kernel Fix h The current value is 64 bits Numbers in the Fix class are represented using two s complement notation with the sign bit stored in the bits to the left of the binary point There must always be at least one bit to the left of the binary point to store the sign In addition to its value each Fix object contains information about its precision and error codes indicating overflow divide by zero or bad format parameters The error codes are set when errors occur in constructors or arithmetic operators There are also fields to specify a whether rounding or truncation should take place when other Fix values are assigned to it truncation is the default b the response to an overflow or underflow on assignment the default is saturation see page 4 6 Warning The Fix type is still experimental Fixed point states State variables can be declared as Fix or FixArray The precisio
329. sp and other directories will also have to be recompiled Thus you will want to expand these directories and any subdirectories below them as well Remember to replace the make template and makefile links as in the sdf kerne1 directory ae exp dsp mk1 exp stars mk1 oA ol oe Because of the way symbolic links work it is important to remove the links for the o and a files in the directories you have just created You can do this by issuing a make realclean command in the obj SPTARCH domains sdf directory This will recursively clean out all the subdirectories You could also do this manually by issuing a rml o a command in each directory You will also need a private version of the src directory ole cd Ptolemy exp src oe oe exp domains exp sdf exp kernel oe ole At any point after this it is possible to switch back and forth between private and official versions of these directories with the sw alias In fact you just used it as part of the exp alias to switch to the private versions of the obj PTARCH lib PTARCH and src directories To compile your version of the sdf kernel directory oe cd Ptolemy obj SPTARCH domains sdf kernel make install oo To make a version pigiRpc or better yet ptinyRpc with your changes Ptolemy Last updated 10 10 97 1 18 Extending Ptolemy Introduction ole cd Ptolemy obj SPTARCH exp pigiRpc mkl make ptinyRpc A oe ole
330. ss derivation hierarchy for threads PtThread is an abstract base class with several possible implementations Each DataFlowProcess refers to a DataFlowStar DataFlowStar processes of Kahn process networks The abstract base class PtThread defines the interface for threads in Ptolemy The class PosixThread provides an implementation based on the POSIX thread standard Other implementations using AWESIME Gru91 or Solaris Pow91 are possible The class PNThread is a typedef that determines which implementation is used in the PN domain Changing the underlying implementation simply requires changing this typedef The class DataFlowProcess which is derived from PNThread implements a dataflow process The Star object associated with an instance of DataFlowProcess is activated repeatedly just as a dataflow actor is fired repeatedly to form a process 10 2 1 The PtThread Class PtThread is an abstract base class that defines the interface for all thread objects in Ptolemy Because it has pure virtual methods it is not possible to create an instance of PtThread All of the methods are virtual so that objects can be referred to as a generic PtThread but with the correct implementation specific functionality The class PtThread has three public methods virtual void initialize 0 This method initializes the thread and causes it to begin execu tion Ptolemy Last updated 4 17 97 10 4 PN domain virtual void runAll This met
331. ss is a type of Particle like IntParticle Float Particle etc it contains a Envelope Ports of type message transmit and receive objects of this type Class Particle contains two member functions for message support getMessage to receive a message and the lt lt operator with an Envelope as the right argument to load a message into a particle These functions return errors in the base class they are overridden in the MessageParticle class with functions that perform the expected operation 4 3 1 Defining a new Message class defined Every user defined message is derived from class Message Certain virtual functions in that class must be overridden others may optionally be overridden Here is an example of a user defined message type Ptolemy This is a simple vector message object It stores an array of integer values of arbitrary length The length is specified by the constructor include Message h class IntVecData public Message private int len init int length int srcData len length data new int len for int i 0 i lt len i data i srcDatatt public the pointer is public for simplicity int data int length const return len functions for type checking const char dataType const return IntVecData isA responds TRUE if given the name of the class or of any baseclass int isA const char typ const if strc
332. ssigned to individual portholes rather than to entire stars The cryptic statements in the constructor in the above example reveal these triggering relationships to the scheduler Consider for example the following problem In the Switch star above suppose that on a given firing an input with time stamp T is processed and the particle is sent to the true output Suppose that the very next time the star fires a control FIGURE 12 1 When DE stars are enabled by simultaneous events the choice of which to fire is determined by priorities based on a topological sort Thus if B and C both have events with identical time stamps B will take priority over C The delay on the path from C to A serves to break the topological sort U C Berkeley Department of EECS The Almagest 12 7 input with time stamp T arrives with value FALSE Probably the previous output should have gone to the false porthole Consider the constructor statement control before input This tells the scheduler that if a situation arises where two simultaneous events might appear at the control and input portholes then the one at the control porthole should appear first This is implemented by giving the stars upstream from the control porthole higher firing priorities than those upstream from the input porthole Thus if for some rea son the simultaneous events are processed in two separate firings always a possibility then the control event is sure to b
333. st line is similar to outputting a scalar value This is because we have overloaded the lt lt operator for MatrixEnvParticles to support PtMat rix class inputs The standard use of the MessageParticle class requires you to put your message into an envelope first and then use lt lt on the envelope see Use of the Envelope class on page 4 17 but we have spe cialized this so that the extra operation of creating an envelope first is not explicit Here is an example of a complete star definition that inputs and outputs matrices defstar name Mpy_M domain SDF desc Does a matrix multiplication of two input Float matrices A and B to produce matrix C Matrix A has dimensions numRows X Matrix B has dimensions X numCols Matrix C has dimensions numRows numCols The user need only specify numRows and numCols An error will be generated automatically if the number of columns in A does not match the number of columns in B U C Berkeley input name Ainput type FLOAT_MATRIX_ENV input name Binput type FLOAT_MATRIX_ENV output name output type FLOAT_MATRIX_ENV defstate name numRows type int default 2 desc The number of rows in Matrix A and Matrix C defstate name numCols type int default 2 desc The number of columns in Matrix B and Matrix C ccinclude Matrix h go get inpu
334. t Manipulate Any Particle Type 4 35 4 7 Unsupported Types iss sae cee eee eee 4 37 Sub matrices 4 37 Image particles 4 40 First class types 4 41 5 Usina TEVTk EE ES tei ee ee 5 1 5 1 Introduction ESE worn DE DE EES EE RE ESE 5 1 5 2 Writing Tcl Tk scripts for the TclScript star 5 1 5 3 Tcl utilities that are available to the programmer 5 6 5 4 Creating new stars derived from the TclScript star 5 11 5 5 Selecting colors es be es eee wee bos 5 12 5 6 Writing Tcl stars for the DE domain 5 12 6 Using the Cluster Class for Scheduling csssssseseeeereeeees 6 1 6 1 INTFOGUCTION Ss SEE oek RESERWE acide ee ce ele he eta ee 6 1 6 2 Basic Classes AE ek eres Lake heb ie 6 1 6 3 Galaxies and their relationship to Adjacency Lists 6 1 6 4 CIUSICNNG tices renser pie OE EE tee eee BO meas 6 2 Initialization Flattening the User Specified Graph 6 2 Absorb and Merge 6 3 Cluster Iterator Classes 6 5 6 5 Block state and name scoping hierarchy 6 6 6 6 Resetting an InterpUniverse back to actionList 6 6 6 7 Ref rentes is ccc ects Pek eee ewe been ER ER 6 7 7 SDF DOMAIN N EE 7 1 7 1 INTORUCUON 2 6 bc sis SE Ee ER eee La ee dea ie bees 7 1 7 2 Setting SDF porthole parameters 5 7 1 8 DDF Dom es ee ee EA de Ee 8 1 8 1 Programming Stars in the DDF Domain 8 1 9 BDF DOMAIN ER EE EE N 9 1 9 1 Writing BDFStar
335. tar A Star is an object derived from class Block that implements an atomic function Major methods run What to do to run the star For example the DataFlowStar class a parent class to many of the dataflow domain stars such as SDFStar and DDFStar defines this function to make each input PortHole obtain Particles from the Geodesic execute the go method of each Star and then have each output PortHole put its Particles into the Geodesic 17 2 4 PortHole PortHoles are data members of Stars and are where streams of Particles enter or leave the Stars Each PortHole always handles Particles of one type so two connected PortHoles need to decide which data type they will use if they are not the same There is a Ptolemy Last updated 10 10 97 17 4 Creating New Domains base class called GenericPort which provides some basic methods that derived classes should redefine as well as some data members commonly needed by all PortHole types Major methods isItInput isItOutput isItMulti connect initialize receiveData sendData putParticle getParticle numX fer numTokens numInitDelays geo setDelay Major data members my Type myGeodesic myPlasma myBuffer farSidePort bufferSize numberTokens Return TRUE if the PortHole class is an input type Return TRUE if the PortHole class is an output type Return TRUE if the P
336. tars in a CGC star The S56XTarget fromCGc method illustrates the typical code needed for these methods CommPair S56XTarget fromCGC PortHole amp CommPair pair new CGCXSend new CG56XCReceive configureCommPair pair return pair The configureCommPair function is defined in the S56XTarget cc file and con figures the S56X Target communication stars Ptolemy Last updated 10 17 97 13 28 Code Generation U C Berkeley Department of EECS The Almagest 14 1 Chapter 14 CGC Domain Authors Joseph T Buck Soonhoi Ha Edward A Lee Yu Kee Lim Thomas M Parks Jos Luis Pino Other Contributors Sunil Bhave Kennard White 14 1 Introduction The CGC domain generates code for the c programming language Code Generation on page 13 1 describes the features common to all code generation domains The basic princi ples of writing code generation stars are explained in Writing Code Generation Stars on page 13 2 You will find explanations for codeblocks macros and attributes there This chap ter explains features specific to the CGC domain Refer to the CGC domain chapter in the user s manual for an introduction to this domain 14 2 Code Generation Methods The addCode method is context sensitive so that it will do the right thing when invoked from within the initCode go and wrapup methods of cGcStar Refer to Writing Code Generation Stars on page 13 2 for documentation on addCode including context
337. tcl Edit the file and add a run Xxx line and a wrapup line at the end If the demo should run for 100 iterations then add run 100 wrapup to the end of the file Build a ptcl debug that has just exactly the functionality you need by using an override mk file Alternatively you could use either ptcl ptrim debug or ptcl ptiny debug If your demo is SDF then try building and using ptcl ptiny debug If you use emacs then you can start up gdb on your binary with M x gdb Then type in the name of the binary You may have to use the full pathname Inside emacs you can then set breakpoints in the gdb window either by typing a break command or by viewing the file and typing Cont rol X space at the loca tion you would like a break point Type r to start the process and then source your demo with source tmp tst tcl If you want to recompile your demo outside of gdb and then reload it into your gdb session use the file command inside gdb Last updated 10 10 97 1 28 Extending Ptolemy Introduction file users cxh pt obj sol2 ptcl ptcl ptiny debug Your breakpoints will be saved which is a big time saver Miscellaneous debugging hints for gdb If you are having problems debugging with gdb here s what to check 1 Verify that your SPTOLEMY is set to what you intended If you are building bina ries in your private tree be sure that SPTOLEMY is set to your private tree and not ptdesign or users
338. ter invokes a proce dure named setOutputs_S starID with a single argument 1 0 passed as a string This procedure has been defined by the TclScript star It sets the value s of the out puts of the star In this case there is only one output so there is only one argument The next statement defines the action when the button is released bind s lt ButtonRelease 1 gt setOutputs_SstarID 0 0 The next statement initializes the output of the star to value 0 0 setOutputs_SstarID 0 0 The last command unsets the variable s since it is no longer needed Ptolemy Last updated 10 10 97 5 4 Using Tcl Tk unset s As illustrated in the previous example a number of procedures and global variables will have been defined for use by the Tcl script by the time it is sourced These enable the script to mod ify the control panel define unique window names and set initial output values for the star Much of the complexity in the above example is due to the need to use unique names for each star instance that sources this script In the above example the Tcl procedure for setting the output values has a name unique to this star Moreover the name of the button in the control panel has to be unique to handle the case when more than one TclScript star sources the same Tcl script These unique names are constructed using a unique string defined by the star prior to sourcing the script That string is made available to the Tcl s
339. terface constructed by the framework is made up of communication pairs each pair encir cled by an ellipse The first sine and last xgraph stars are to be run on the host workstation CGC The second block analysis filter bank a galaxy made up of two polyphase FIR actors is to be run on a DSP card CG56 The third block synthesis filter bank a galaxy made up of two polyphase FIR actors is to be run using a VHDL simulator In case there are delays or past tokens are used on the connection between two blocks that should be connected through spread or collect stars we need to copy data explicitly Thus we will need extra memory for these stars In this case the user will see the existence of spread collect stars in the generated code Spread Collect stars have only been implemented in the CGC domain so far 13 5 Interface Issues In Ptolemy 0 6 and later we have developed a framework for interfacing code genera tion targets with other targets simulation or code generation In this section we will detail how to support this new framework for a code generation target To learn how to develop applications within Ptolemy that use multiple targets that support this new framework refer to the Interface Issues section in the User s Manual CG Domain chapter As with Wormholes we have developed a way to interface N targets without requir ing N specialized interfaces We do this by generating a customized interface
340. th their PortLists can be viewed as eguivalent to the adjacency list data structure A PortHole in most domains is either an input or an output It contains a far SidePort pointer to the PortHole it is connected to NULL if it is not connected To traverse the adjacency list a scheduler writer must make use of two iterators in Ptolemy See Tterators on page 3 10 GalStarIter and SuccessorIter By using aGalStarItera scheduler writer can iterate over the nodes in the user specified graph Then on each of these nodes we can find the adjacent nodes using the SuccessorIter Although it is not necessary for adjacency list equivalence the PredecessorIter is provided to iterate over the nodes that are predecessors to a given node There is slight overhead in accessing the graph using both GalStarIter and Suc cessorlter over a straight forward implementation of an adjacency list class This over head has a constant cost which is not dependent on the size of the graph Thus we feel that the robustness achieved by not having two parallel representations of the same graph far outweigh this small overhead 6 4 Clustering Clustering is often used in implementing scheduling heuristics We have provided a generic Cluster class in the Ptolemy kernel which scheduler writers can use directly or if need be derive specialized clustering classes The older schedulers such as the BDF scheduler and the SDF loop schedulers have not been u
341. than they appear in the source file You may find it easier to debug a file by recompiling it with the optimization turned off by removing the corresponding o file and doing make OPTIMIZER install Debugging StringLists in gdb Ptolemy uses StringList object to manipulate strings However using gdb to view U C Berkeley Department of EECS The Almagest 1 27 a StringList object can be non intuitive To print the contents of a Stringlist myStringList as one item per line from within gdb use p displayStringListItems myStringList To print out the St ringList as a contiguous string use p displayStringList myStringList How to use ptcl to speed up the compile test cycle If you are spending a lot of time debugging a problem you may want to use ptcl instead of pigiRpc as ptcl is smaller and starts up faster Also you can keep your break points between invocations of ptcl as debugging ptc1 does not start up a separate emacs each time However ptc1 cannot handle demos that use Tk Here s how to use ptc1 to debug 1 Ptolemy Run pigiRpc on the universe and use compile facet to generate a pigiLog pt file Note the number of iterations for the universe and then exit pigiRpc Copy pigiLog pt to somewhere A short file name like tmp tst tcl will save time in typing since you may be typing it often Don t use something inside your home directory as you can t easily use inside p
342. the Parti cle object supplied by the input but rather its value interpreted as a double precision float ing point number Try changing this code to go output 0 lt lt sin double input 0 1 0 To recompile and reload the star place your mouse cursor on any instance of the icon for the star and type L or invoke the Extend load star command through the menus Sometimes you will wish to dynamically link stars that are derived from other stars that you have dynamically linked To do this the base class stars must be permanently linked This can be done with the Extend load star perm command K To do this place the mouse over an icon representing the parent star and type K Once the parent star is perma nently linked it cannot be replaced or redefined you must restart pigi The go and all other entries in the p1 file defining the star are explained in the fol lowing sections 2 3 The Ptolemy preprocessor language ptlang The Ptolemy preprocessor pt lang was created to make it easier to write and docu ment star class definitions to run under Ptolemy Instead of writing all the class definitions and initialization code required for a Ptolemy star the user can concentrate on writing the action code for a star and let the preprocessor generate the standard initialization code for portholes states etc The preprocessor generates standard C code divided into two files a header file Ptolem
343. the User s Manual rather than in this Programmer s Manual e Customized simulation builders and controllers can be created using the ptcl inter preted command language This language is also covered in the User s Manual e New functional blocks stars can be added to any of the Ptolemy domains These blocks can be dynamically linked with either ptcl or pigi e New code generation blocks can be added to existing synthesis domains e Stars with customized user interfaces and displays can be created using Tcl Tk e New simulation and design flow managers called targets can be created e New domains with new models of computation can be created This volume explains how to accomplish most of the above The Kernel Manual volume 3 of The Almagest supplements this volume with a detailed listing of all of the classes in the Ptolemy kernel and in the code generation kernel The sophisticated user however who is extending the system in nontrivial ways will wish to refer to the source code as the ultimate most complete documentation In this volume we assume familiarity with the terminology and use of Ptolemy Refer to the User s Manual and particularly to the glossary contained therein for assistance We also assume you are familiar with the overall organization of the Ptolemy software as described in User s Manual 1 2 File Organization Ptolemy is distributed with source code The complete distribution even includes the compil
344. the star writer must know is how to specify that a porthole is conditional on other portholes This is accomplished with a method of the class BDFPort Hole called setBDFParams The setBDFParams method takes four arguments The first argument is the number of particles transferred by the port when the port is enabled Note that unconditional ports are always enabled The second argument is either a pointer or a reference to another BDFPort Hole which is called the associated port the function has two overloaded forms which is why the argument may be specified either as a pointer or as a reference The third argument is a code specifying the relation between the porthole this method is called on and the associated port BDF_NONE This code indicates no relation at all BDF_TRUE This code indicates that data are transferred by the port only when the conditional port has a TRUE particle BDF_FALSE This code indicates that data are transferred by the port only when the conditional port has a FALSE particle BDF_SAME This code indicates that the stream transferred by the associated port is the same as the stream transferred by this port This relationship is specified for the BDF Fork actor and aids the operation of the cluster ing algorithm BDF_COMPLEMENT This code indicates that the stream transferred by the associated port is the logical complement of the stream transferred by this port This rela
345. the table can be defined to return pointers of the appropriate type Moreover the deallocation of memory when an entry is deleted or the table itself is deleted can be automated Text Table is a good example of such a derived class This is not possible with the generic HashTable class because the Pointer type does not give enough information to know what destructor to invoke Thus when using the generic Hash Table class the user should explicitly delete the objects pointed to by the Pointer if they were dynamically created and are no longer needed A detailed example that directly uses the HashTable class without defining a derived class is given in the next section In that exam Ptolemy Last updated 8 26 97 3 14 Infrastructure for Star Writers ple the Pointer entries point to stars in a universe so they should not be deleted when the entries in the table are deleted Their memory will be deallocated when the universe is deleted TextTable class void clear include HashTable h description empty the table void cleanup Pointer p deallocate the string pointed to by p int hasKey const char key void insert const t char key const t char string return I if the given key is in the table 0 otherwise create an entry containing a copy of string any previous entry with the same key is replaced and the cleanup method is called to deallocate its memory const ch
346. ther they are parallelizable or not The advantage of doing this is the simplicity in code generation since we do not need to splice in Spread Collect stars which will be discussed later Also it provides us another possi ble scheduling option adjust Schedule this is described below The main disadvantage of setting oneStarOneProc to YES is the performance loss of not exploiting parallelism It is most severe if Sih s declustering algorithm is used Therefore Sih s declustering algorithm is not recommended with this option In this paragraph we describe a future scheduling option which this release does not support yet Once automatic scheduling with oneStarOneProc option set is performed the processor assignment of each star is determined After examining the assignment the user may want to override the scheduling decision manually It can be done by setting the adjustSchedule parameter If that parameter is set after the automatic scheduling is per formed the procid state of each star is automatically updated with the assigned processor The programmer can override the scheduling decision by setting that state The adjustSchedule cannot be YES before any scheduling decision is made previously Again this option is not supported in this release Different scheduling options result in different assignments of APEG nodes Regard less of which scheduling options are chosen the final stage of the scheduling is to decide the
347. this example the Ptolemy distribution is at users ptolemy setenv PTOLEMY users ptolemy 3 Set PTARCH to the appropriate value setenv PTARCH SPTOLEMY bin ptarch 4 Set the path properly set path SPTOLEMY bin SPTOLEMY bin SPTARCH path 5 Execute the mkPtolemyTree command so that the override mk file is used to create a custom tree in the mypt directory mkPtolemyTree override mk mypt In general you will want to define the variables TK and HOF Setting TK indicates that you want to include Tcl Tk extensions to the domains Setting HOF means that you want to include the higher order functions domain The higher order functions domain is used in many demonstrations to configure stars with multiple portholes and to specify scalable sys tems So adding these make variables in the same override mk file would make it look like the following HOF 1 TK 1 VHDL 1 DEFAULT_DOMAIN VHDL VERSION_DESC VHDL only 1 4 2 How mkPtolemyTree works src stars mk contains a makefile variable named CUSTOM DI To accumulate a list of the directories necessary to build a custom tree PTOLI EMY RS In stars mk each fea ture such as VHDL adds directories to CUSTOM_DIRS Also a feature can require sub features and the sub features can add directories to CUSTOM_DIRS For example VHDL require and CG adds more directories to CUSTOM DIRS U C Berkeley When you run SPTOLEMY bin mkPtolemyTree the foll
348. those libraries are cur rently only available in Fortran and there are some incompatibilities with Fortran s column major ordering and C s row major ordering Those problems would still exist even if the For tran code was converted to C There are a few groups which are currently working on C ports of the numerical analysis libraries One notable group is the Lapack project which is 1 LAPACK A Design Overview of Object Oriented Extensions for High Performance Linear Algebra by Jack J Dongarra Roldan Pozo and David W Walker available on netlib Ptolemy Last updated 10 10 97 4 34 Data Types developing a flexible matrix class of their own besides porting the Fortran algorithms of Lapack into C This might possibly be incorporated in a future release 4 5 The File and String Types There are two experimental types in Ptolemy that support non numeric computation These types represent the beginnings of an effort to extend Ptolemy s dataflow model to non dataflow problems such as scheduling and design flow Their interfaces are still being devel oped so should be expected to change in future releases We would welcome suggestions on how to improve the interface and functionality of these two types 4 5 1 The File type The file type is implemented by the classes FileMessage and FileParticle which are derived from Message and Particle It uses the reference counting mechanism of the Message and Envelope class
349. tialize the output if int a 0 lt int b 0 Ptolemy Last updated 4 17 97 10 16 PN domain output s0 a 0 output sendData a receiveData else if int a 0 gt int b 0 f output 0 D 0 output sendData b receiveData else Remove duplicates output 0 a 0 output sendData a receiveData b receiveData Instead of using an infinite loop most PN stars rely on the run method of Dat aF low Process to repeatedly invoke the star s go method U C Berkeley Department of EECS Chapter 11 SR domain Authors Stephen Edwards Other Contributors Christopher Hylands 11 1 Introduction Synchronous Reactive SR is a statically scheduled simulation domain in Ptolemy designed for concurrent control dominated systems Simple stars for the SR domain are easy to write but more complex ones that take full advantage of the domain are more subtle Stars can be written in either C or Itcl 11 2 Communication in SR Time in SR is divided into discrete instants In each instant the communication chan nels in SR contain a valued event have no event or are undefined corresponding to when the system could not decide whether there was an event or not These channels are not buff ered unlike Ptolemy s dataflow domains and do not hold their values between instants Stars in the SR domain have input and output ports much like they do in other
350. tionship is specified for the BDF Not actor and aids the operation of the clustering algorithm The fourth argument for setBDFParams is the maximum delay that is the largest value that the star may specify as an argument to the operator on that porthole The default value is zero This argument serves the same purpose as the second argument to set SDF Params The setSDFParams function may be used on BDF portholes it does not alter the associated port or the relation type but does alter the other two parameters of set BDF Params By default BDF portholes transfer one token unconditionally 9 2 BDF Domain Calls to set BDFParams may be placed in the setup method of a star or alternatively in the constructor if the call does not depend on any parameters of the star Consider as an example a Switch star This star s functionality is as follows on each execution it reads a particle from its control input port If the value is TRUE it reads a particle from its t rueIn put port otherwise it reads a particle from its falseInput port In any case the particle is copied to the output port Using the pt lang preprocessor the setup method could be written setup trueInput setBDFParams 1 control BDF_TRUE 0 falselnput setBDFParams 1 control BDF_FALSE 0 and the go method could be written go if int control 0 output 0 trueInput 0 else output s0
351. to NO the input particles are cast to an internal precision which is usually specified by another parameter Here is the abbreviated source of the SDFGainFix star which demonstrates this point defstar name GainFix domain SDF derivedFrom SDFFix desc This is an amplifier the fixed point output is the fixed point input multiplied by the gain default 1 0 The precision of gain the input and the output can be specified in bits input name input type fix output name output type fix defstate name gain type fix default 1 0 desc Gain of the star Ptolemy Last updated 10 10 97 4 8 Data Types defstate name ArrivingPrecision type int default YES desc Flag indicating whether or no to use the arriving particles as they are YES keeps the same precision and NO casts them to the precision specified by the parameter InputPrecision defstate name InputPrecision type precision default 2 14 desc Precision of the input in bits The input particles are only cast to this precision if the parameter ArrivingPrecision is set to NO defstate name OutputPrecision type precision default 2 14 desc Precision of the output in bits This is the precision that will hold the result of the arithmetic operation on the inputs When the value of the product extends outside of the precis
352. tomizing the star A second issue is that of communicating the new parameter values to the Tcl script For example the Tcl script will need to know the value of the abel parameter in order to cre ate the label for the display The TclScript star automatically makes all the parameters of any derived star available as array entries in the global array whose name is given by the glo bal variable starID To read the value of the label parameter in the Tcl script use the expression set starID label The confusing syntax is required to ensure that Tcl uses the value of starID as the name of the array The string label is just the index into the array The set command in Tcl when given only one argument returns the value of the vari able whose name is given by the argument Some programmers may prefer an alternative way to refer to parameters that is slightly more readable The Tcl statement upvar 0 SstarID params allows subsequent statement to refer to parameters simply as Sparam param_name The upvar command with argument 0 declares the local variable params equivalent to the glo bal variable whose name is given by the value of starID Many more examples can be found in PTOLEMY src domains sdf tcltk stars Ptolemy Last updated 10 10 97 5 12 Using Tcl Tk 5 5 Selecting colors Since X window installations do not necessarily use consistent color names a particu lar color database has been installed
353. tructions about this c Use mkPtolemyTree to rebuild a subset of the Ptolemy tree See Using mkP tolemyTree to create a custom Ptolemy trees on page 1 9 for more information d Use the csh aliases to rebuild a subset of the Ptolemy tree See Using csh aliases to create a Parallel Software Development Tree on page 1 12 for more informa tion The next step is to build the pigiRpc debug binary cd SPTOLEMY obj SPTARCH pigiRpc make pigiRpc debug Then set the PIGIRPC environment variable to point to the binary setenv PIGIRPC PTOLEMY obj S PTARCH pigiRpc pigiRpc debug Then run pigi as follows pigi debug An extra window running gdb appears If this fails then gdb is probably not installed at your 1 Note that the pigi script will attempt to find pigiRpc debug binary if the PIGIRPC environment vari able is not set An alternative is that one can avoid setting PIGIRPC and use the pigi rpc option to specify a binary The command would be pigi debug rpc PTOLEMY obj PTARCH pigiRpc pigiRpc debug Ptolemy Last updated 10 10 97 1 24 Extending Ptolemy Introduction site or is not in your path Type cont to continue past the initial breakpoint Now if you can replicate the situation that created the crash you will be able to get more information about what happened Here is a sample of interaction with the debugger through the gdb window GDB is free software and you are welcome to
354. ts Envelope Apkt Ainput 0 getMessage Apkt const FloatMatrix amp Amatrix Department of EECS The Almagest 4 33 const FloatMatrix Apkt myData Envelope Bpkt Binput 0 getMessage Bpkt const FloatMatrix amp Bmatrix const FloatMatrix Bpkt myData check for null matrix inputs which could be caused by delays on the input line if Apkt empty Bpkt empty if either input is empty return a zero matrix with the state dimensions FloatMatrix amp result new FloatMatrix int numRows int numCols result 0 0 output 0 lt lt result else Amatrix and Bmatrix are both valid if Amatrix numRows int numRows Bmatrix numCols int numCols Error abortRun this Dimension size of FloatMatrix inputs do not match the given state parameters return do matrix multiplication FloatMatrix amp result new FloatMatrix int numRows int numCols we could write result Amatrix Bmatrix but the following is faster multiply Amatrix Bmatrix result output 0 lt lt result 4 4 5 Future extensions After reviewing the libraries of numerical analysis software that is freely available on the Internet it is clear that it would be beneficial to extend the PtMatrix class by adding those well tested libraries as callable functions Unfortunately many of
355. ts the delayType member summarized in table 12 1 This information is used by the scheduler and is particularly important when determining which of several simulta neous events to process first 12 2 2 Functional Stars In the DE model of computation a star is runnable ready for execution if any input porthole has a new event and that event has the smallest time stamp of any pending event in the system When the star fires it may need to know which input or inputs contain the events that triggered the firing An input porthole containing a new particle has the dat aNew flag set by the scheduler The star can check the dataNew flag for each input A functional star will typically read the value of the new input particles compute the value of new output particles and produce new output particles with time stamps identical to those of the new inputs To see how this is done consider the Switch star defstar name Switch domain DE desc Switches input events to one of two outputs depending 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 constructor control triggers control before input if input dataNew completionTime arrivalTime U C Berkeley Department of EECS The Almagest 12 5 Particle amp pp input get int c int control 0 if c t
356. turn the number of pending simultaneous events at this input void triggers indicate that the input does not trigger any immediate output events void triggers indicate that the input triggers an immediate output on port p GenericPort p OutDEPort class description le amp oa get the most recent particle from the porthole ticle amp pu get a new writable particle with the given time stamp double ti void sendDat flush output porthole data to the global event queue called by put TABLE 12 1 A summary of the members and methods of the InDEPort and OutDEPort classes that are used by star writers Ptolemy Last updated 10 17 97 12 6 DE Domain domain For example contro1 0 returns the most recent particle from the control port hole The second method get is specific to InDEPort It resets the dat aNew member of the port as well as returning the most recent particle from an input port In the above example we are not using the dataNew flag for the control input so there is no need to reset it How ever we are using it for the input porthole so it must be reset If you need to reset the dataNew member of a input port after reading the newly arrived event the more common case you should use the get method instead of 0 operator Alternatively you can reset the dataNew flag explicitly using a statement like input dataNew FALSE The put method is also s
357. type FLOAT_MATRIX output name output type FLOAT_MATRIX defstate name numRows type int default 2 desc The number of rows in the input output matrices defstate name numCols type int default 2 desc The number of columns in the input output matrices ccinclude SubMatrix h setup Ainput setMDSDFParams int numRows int numCols Binput setMDSDFParams int numRows int numCols output setMDSDFParams int numRows int numCols go get a SubMatrix from the buffer FloatSubMatrix amp inputl Last updated 10 10 97 4 40 Data Types FloatSubMatrix Ainput getInput FloatSubMatrix amp input2 FloatSubMatrix Binput getInput FloatSubMatrix amp result FloatSubMatrix output getOutput compute product putting result into output result inputl input2 delete amp inputl delete amp input2 delete amp result The sub matrix particles The pt lang type of submatrices is FLOAT_MATRIX INT_MATRIX and so on This is not documented in the User s Manual and is likely to change in a future release Each of these ptlang types is implemented by a sub class of Particle IntMatrixParticle Float MatrixParticle FixMatrixParticle and ComplexMatrixParticle These particle classes exist only for setting up the portholes and performing type checking they are never created or passed aro
358. ult 1 0 desc Height of the rectangular pulse state name width type int default 8 desc Width of the rectangular pulse state name count type int default 0 desc Internal counting state attributes A_NONSETTABLE A_NONCONSTANT U C Berkeley Department of EECS The Almagest 2 5 output the output port name output type float desc The output pulse go the run time function double t 0 0 if count lt width t count int count output S0 lt lt t height 1 Running the preprocessor on the above file produces the three files SDFRect h SDFRect cc and SDFRect htm1 the names are determined not by the input filename but by concatenating the domain and name fields These files define a class named SDFRect At the time of this writing only one type of declaration may appear at the top level of a Ptolemy language file a defstar used to define a star Sometime in the future a defgal axy section may also be supported The defstar section is itself composed of subitems that define various attributes of the star All subitems are of the form keyword body where the body may itself be composed of sub subitems or may be C code in which case the Ptolemy language preprocessor checks it only for balanced curly braces Note that the keywords are not reserved words they may also be used as identifiers in the body
359. un in the setup or begin method prior to allocating new memory and in the destructor public protected private These three keywords allow the user to declare extra members for the class with the desired protection The syntax is protkey body where protkey is public protected or private Example from the xMgraph star protected XGraph graph double index This defines an instance of the class XGraph defined in the Ptolemy kernel and a U C Berkeley Department of EECS The Almagest 2 15 double precision number If any of the added members reguire arguments for their constructors use the conscalls item to specify them ccinclude hinclude code These directives cause the cc file or the n file to include extra files A certain number of files are automatically included when the preprocessor can determine that they are needed so they do not need to be explicitly specified The syntax is ccinclude inclist hinclude inclist where inclist is acomma separated list of include files Each filename must be sur rounded either by quotation marks or by lt and gt for system include files like lt math h gt This keyword allows the user to specify a section of arbitrary C code This code is inserted into the cc file after the include files but before everything else it can be used to define static non class functions declare external variables or anything else The outermost p
360. und during a simulation Instead sub matrices are created and destroyed by the MDSDF kernel and stars as described above 4 7 2 Image particles A set of experimental image data types designed to make it convenient to manipulate images and video sequences in Ptolemy were defined by Paul Haskell They are based on Ptolemy s built in Message type described above A library of stars that uses these image data types can be found in the image library of the DE domain This set of classes is being replaced by the PtMatrix classes and the SDF image classes now all use PtMatrix We give here a brief introduction to the image data types used in the DE domain although new work should consider using PtMat rix classes instead Class definitions can be found in SPTOLEMY src domains de kernel The base class of all the image classes is called BaseImage It has some generic methods and members for manipulating images Most of the methods are redefined in the derived classes The fragment method partitions an image into many smaller images which together represent the same picture as the original The assemble method combines many small images which make up a single picture into a single image that contains the picture The fragment method works recursively so an image that has been produced by a previous fragment call can be further fragmented Assembly always produces a full sized image from fragments however small Use of t
361. utput name output type input defstate name delay type float default 1 0 desc Amount of time delay constructor delayType TRUE go completionTime arrivalTime double delay Particle amp pp input get output put completionTime pp Inside the go method description the complet ionTime is calculated by adding the delay to U C Berkeley Department of EECS The Almagest 12 3 the arrival time of the current event The last two lines will be explained in more detail below Another type of delay star is a server In a server star the input event waits until a sim ulated resource becomes free to attend to it An example is the Server star defstar name Server domain DE desc This star emulates a server If an input event arrives when it is not busy it delays it by the service time a constant parameter If it arrives when it is busy it delays it by more than the service time It must become free and then serve the input input name input type anytype output name output type input defstate name serviceTime type float default 1 0 desc Service time constructor delayType TRUE go No overlapped execution set the time if arrivalTime gt completionTime completionTime arrivalTime double serviceTime else completionTime double serviceTime Particle amp pp
362. ven value The number is rounded to the closest representable number Ptolemy Last updated 10 10 97 Fix const Fix const Fix const Data Types given the precision If the precision parameters are not valid then an error bit is internally set so that the invalid method will return TRUE char precisionString double value Same as the previous constructor except that the precision is specified by the given precisionString instead of as two integer arguments If the precision parameters are not valid then an error bit is internally set so that the invalid method will return true when called on the object char precisionString uintl6 bits Create a Fix with the specified precision and set the bits precisely to the ones in the given bits The first word pointed to by bits contains the most significant 16 bits of the representation Only as many words as are necessary to fetch the bits will be referenced from the bits argu ment For example Fix 2 14 bits will only reference bits 0 This constructor gets very close to the representation and is meant mainly for debugging It may be removed in the future Fix amp arg Copy constructor Produces an exact duplicate of arg Fix int length int intbits const Fix amp arg Read the value from the Fix argument and set to a new precision If the precision parameters are not valid then an error bit is internally set so that the invalid method will return true when cal
363. verride mk file CUSTOM_DIRS CROOT lib tcl To expand Tycho consult the Tycho documentation and use the tylndir script There is no documentation of the variables to pull in each domain yet In general it is the standard abbreviation for the domain in capital letter For example the Synchronous Data flow SDF domain is SDF the Discrete Event DE domain is DE and so forth Some of the domains are split up the entire domain can be brought in by defining FOOFULL e g SDF FULL or CGCFULL When defined they include all of the SDF and CGC functionality respectively whereas SDF and CGC include only the basic functionality The basic version of the SDF domain does not include the image matrix Matlab DSP and Tcl Tk stars If you are attempting to build a pigi that includes the Process Network PN domain then you should add the following to your override mk file INCLUDE_PN_DOMAIN yes For a listing of the possible make variables refer to the PTOLEMY mk ptbin mk and SPTOLEMY mk stars mk files 1 4 3 Combining mkPtolemyTree and pigiExample It is possible to use the override mk file used by mkPtolemyTree in the pigiEx ample directory to create a custom pigiRpc with user added stars One reason for doing this would be to that on some platforms stars that have been incrementally linked are not visible from the debugger Creating a custom pigiRpc with the star as a built in star can aid debug ging
364. workaround is to do SPTOLEMY obj S PTARCH pigiRpc make PIGI pigiRpc See Creating a pigiRpc that includes your own stars on page 1 7 for details on how to use your new pigiRpc binary To verify that your new domain has been installed start pigi with the console option SPTOLEMY pigi rpc SPTOLEMY obj SPTARCH pigiRpc pigiRpe console U C Berkeley Department of EECS The Almagest 17 13 and then type domains into the console window prompt Below is the sample output for the yyy example domain pigi gt domains YYY pigi gt knownlist Nop pigi gt Ptolemy Last updated 10 10 97 17 14 Creating New Domains U C Berkeley Department of EECS The Almagest INDEX Symbols SR a er AD EE IE 2 23 SPT ARCH ei EG NETA 1 2 SPTOLEMY 3 sis Ve gese Re Fee ese se EG ee EE iran 1 3 Yo OPETALOT eeuse see se eek se Se ee ee ERA ee Re De 2 19 12 5 EE dl N OE N AT 1 2 1 12 SOC TIMES DE ELE OE ENE 2 4 EER filenn Rene one eer Ae er ne ree 1 2 iy THES me ER OE iE EN ae 2 4 Bid des SERE AD BEREA Es 2 4 Dl file SEE ER De Ee ee EE 2 1 7 1 EE Ee EE EN 2 19 AplOleMly sarene EE ED Gee BE RS EE EE se 1 3 A EE EA ER ES 2 10 A CONSTANT attribute ee ees se ee se ee 2 10 A_NONCONSTANT attribute 2 10 2 21 A_NONSETTABLE attribute iese eee 2 10 A_SETTABLE attribute ses esse sesse 2 10 2 21 AB CIRC attribute cece se ee Ge Ge 13 13 AB CONSEC attribute iese ee se se ee 13 13 access
365. xample Complex A complexSourceNumber Basic operators The following list of arithmetic operators modify the value of the complex number All func tions return a reference to the modified complex number this Complex amp operator const Complex amp arg Complex amp operator const Complex amp arg Complex amp operator const Complex amp arg Complex amp operator const Complex amp arg Complex amp operator const Complex amp arg Complex amp operator double arg Complex amp operator double arg There are two operators to return the real and imaginary parts of the complex number double real const double imag const Non member functions and operators The following one and two argument operators return a new complex number Complex operator const Complex amp x const Complex y Complex operator const Complex amp x const Complex y Complex operator const Complex amp x const Complex y U C Berkeley Department of EECS The Almagest Co Co CO Co CoO Co Co Co Co Co mp 1 mp 1 mp 1 mp 1 mp 1 mp 1 mp 1 mp 1 mp 1 mp 1 Co Co Co mp 1 mp 1 mp 1 ex ex ex ex ex ex ex ex ex ex ex ex ex operator double x const Complex y operator const Complex amp x double y operator const Complex
366. y Kernel Manual The important properties for a star writer to know are these e Ifan input port has a specific declared type it is guaranteed to receive particles of that type For reasons mentioned in Reading inputs and writing outputs on page 2 17 it is safest to explicitly cast input particles to the desired type as in go double value double in 0 but this is not strictly necessary in the current system e In simulation domains an output port is NOT guaranteed to transmit particles of its declared type the actual resolved type of the porthole will be determined by the con nected input porthole Therefore you should always allow for type conversion of the value computed by the star into the actual type of the output particle This happens implicitly when you write something like out 0 lt lt t because this expands into a call of the particle s virtual method for loading a value of the given type But assuming that you know the exact type of particle in the porthole say by writing something like FloatParticle amp out 0 is very unsafe e In code generation domains it is usually critical that the output porthole s actual type be what the star writer expected Most codegen domains therefore splice type conver U C Berkeley Department of EECS The Almagest 4 37 sion stars into the schematic when input and output ports of different declared types are connected In this way both connected stars wi
367. y Last updated 8 26 97 2 4 Writing Stars for Simulation with a h extension and an implementation file with a cc extension It also generates stan dardized documentation in a file with a html extension to be included in the manual In releases before Ptolemy 0 7 Ptolemy used t files which conained troff source 2 3 1 Invoking the preprocessor The definition of a star named yyy in domain XXX should appear in file with the name XXXYYY pl The class that implements this star will be named xxxyyy Then running the command ptlang XXXYYY pl will produce the files XXXYYY cc XXXYYY h and XXXYYY html Implementation of the preprocessor The preprocessor is written in yacc and C It does not attempt to parse the parts of the language that consist of C code for example go methods for these it simply counts curly braces to find the ends of the items in question It outputs 1ine directives so the C com piler will print error messages if any with respect to the original source file 2 3 2 An example To make things clearer let us start with an example a rectangular pulse star in the file SDFRect pl defstar name Rect domain SDF desc Generates a rectangular pulse of height height default 1 0 with width width default 8 version W G author J T Buck copyright 1993 The Regents of the University of California location SDF main library state name height type float defa
368. y particles An example is if inPkt empty FloatMatrix amp result new FloatMatrix int numRows int numCols result 0 0 output 0 lt lt result There are many ways that an empty input can be interpreted by a star that operates on matri ces For example a star multiplying two matrices can simply output a zero matrix if either input is empty A star adding two matrices can output whichever input is not empty Note above that we create an output matrix that has the dimensions as set by the state parameters of the star so that any star that uses this output will have valid data A possible alternative to outputting a zero matrix is to simply pass that empty Mes sageParticle along This approach however can lead to counterintuitive results Suppose that empty message reaches a display star like TkText which will attempt to call the print method of the object An empty message has a print method that results in a message like lt type gt no print method This is likely to prove extremely confusing to users so we strongly recommend that each matrix star handle the empty input in a reasonable way and produce a non empty output Matrix outputs To put a matrix into an output porthole the syntax is FloatMatrix amp outMatrix new FloatMatrix someRow someCol Ptolemy Last updated 10 10 97 4 32 Data Types do some operations on the outMatrix outputPortHole 0O lt lt outMatrix The la
369. ynamic memory allocated for the matrix will be automatically deleted by the Message class Then the matrix is reset to be an identity matrix Finally the matrix is sent to the output port with the same time stamp as that of the input data Note that the syntax to output data in the discrete event domain differs from the syntax of the synchronous dataflow domain due to the time stamp In the SDF domain the output code would be output 0 lt lt result 12 4 2 Matrix Transpose In the next example we will compute the matrix transpose defstar name Transpose_M domain DE desc Transpose a floating point matrix author Brian L Evans input name input type FLOAT_MATRIX_ENV output name output type FLOAT_MATRIX_ENV ccinclude Matrix h go Functional Star pass timestamp without change completionTime arrivalTime Extract the matrix on the input port Envelope Xpkt input get getMessage Xpkt const FloatMatrix amp Xmatrix const FloatMatrix Xpkt myData Create a copy of the input matrix FloatMatrix amp xtrans new FloatMatrix Xmatrix Transpose the matrix xtrans transpose Send the matrix result to the output port output put completionTime lt lt xtrans The key difference between creating an identity matrix and taking a matrix transpose in the DE domain is the conversion of the input data to a matrix The input

Download Pdf Manuals

image

Related Search

Related Contents

Manual de instalação do kit de disjuntores  1 REGLEMENT INTERIEUR DU COLLEGE EPISCOPAL DE  

Copyright © All rights reserved.
Failed to retrieve file