Top Up Prev Next Bottom Contents Index Search

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 interact.

17.4.2 Creating the files

The mkdom script at $PTOLEMY/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 internally. 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 $PTOLEMY/src/domains/yyy
2. cd to that directory and then run mkdom:
cd $PTOLEMY/src/domains/yyy
$PTOLEMY/bin/mkdom yyy

17.4.3 Required classes and methods for a new domain

mkdom will create copies of key files in $PTOLEMY/src/domains/yyy/kernel and a Nop star in $PTOLEMY/src/domains/yyy/stars. The template files have various comments 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. 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 Geodesic that allows multiple connections, such as AutoForkNode. You can define your own YYYGeodesic or simply use the kernel's AutoForkNode if that is suitable (this is what SDF does).
Various methods to interface your new domain with others must be defined if you wish to use your domain with other 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 others are not (like SDF), you must be able to convert from one to another.
Currently we set the Geodesic to be the kernel's AutoForkNode. 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.
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 methods have been defined but you'll want to add much more. Refer to Star, DataFlowStar, and 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 $PTOLEMY/obj.$PTARCH directories. Currently, there are two ways to build the $PTOLEMY/obj.$PTARCH directory tree: MAKEARCH and mkPtolemyTree. To build object files for your new domain in $PTOLEMY/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 other users run mkPtolemyTree to setup parallel development trees on the new domain.


$PTOLEMY/MAKEARCH is a /bin/csh script that creates or updates the object tree in an already existing Ptolemy tree. To add a domain to MAKEARCH, 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 hof ipus yyy)
This will cause a stars and kernel directory to be created in $PTOLEMY/obj.$PTARCH/domains/yyy when MAKEARCH is run.
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.$PTARCH tree, as MAKEARCH has probably traversed down a parallel tree created by mkPtolemyTree and come up in a directory that you do not own.


$PTOLEMY/bin/mkPtolemyTree is a tclsh script that creates a new parallel Ptolemy tree. Note that mkPtolemyTree cannot be run in an already existing Ptolemy development tree. The file $PTOLEMY/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, so adding support for mkPtolemyTree is fairly trivial.


Follow the style for domain addition that you see in this file for the other domains. A few things to keep in mind:

5. Edit $PTOLEMY/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


In $PTOLEMY/mk/, add your domain to the FULL definition. This causes your domain to be built in whenever a full pigiRpc binary is created.

Building a pigiRpc

6. To build a pigiRpc with your domain, first build and install your domain's kernel and star libraries:
cd $PTOLEMY/obj.$PTARCH/domains/yyy
make depend
make install
If your domain depends on other domains, you will have to build in those directories as well. You may find it easier to do cd $PTOLEMY; 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 $PTOLEMY/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 in $PTOLEMY/obj.$PTARCH/pigiRpc which will pull in only the domains you want.
$PTOLEMY/obj.$PTARCH/pigiRpc/ could contain:
To build your binary, do:
cd $PTOLEMY/obj.$PTARCH/pigiRpc; make
If you don't have all the libraries built, you may get an error message:
make: *** No rule to make target \Q../../lib.sol2/', needed by \QpigiRpc'. Stop.
The workaround is to do:
cd $PTOLEMY/obj.$PTARCH/pigiRpc; make PIGI=pigiRpc
9. See "Creating a pigiRpc that includes your own stars" on page 1-7 for details on how to use your new pigiRpc binary.
10. To verify that your new domain has been installed, start pigi with the -console option:
cd $PTOLEMY; pigi -rpc $PTOLEMY/obj.$PTARCH/pigiRpc/pigiRpc -console
and then type:
into the console window prompt. Below is the sample output for the yyy example domain:
pigi> domains
pigi> knownlist

Top Up Prev Next Bottom Contents Index Search

Copyright © 1990-1997, University of California. All rights reserved.