- Introduction
Paravision is a flexible modular system. The Paravision controller
parses a trace file, in PICL 2.0 format, and provides control flow
through the trace file. The PICL 2.0 format is further discussed in the events section of this document. For know it
will suffice to say that each event includes a time stamp and tags.
When the current execution time is equal to an events time stamp that
event is executed. Execution involves parsing the event to determine
the event type. The event is then propagated through sockets to the
applications requesting that event type.
At startup the Paravision controller reads in the list of applications to execute and the events they require. Currently a file is read in at startup and changes can not be made during run time. The specification on starting Paravision and the mechanism will be discussed in future sections.
- Installation
To install Paravision and the supplied binaries your system needs to
be a Sun4. If you wish to recompile the Paravision controller for a
different architecture, you need to have ET++ and Escallante installed
on your system. Get the
ParaVision.tar.gz file from the ftp cite and place it in its own
directory. gunzip the file and then use tar to extract
the files from the tar-ed file. The result is the creation of a file
and three
directories: traces containing some sample traces and the programs
to generate them,PICL contains the PICL 2.0 parser code and the
socket code for communication with the Paravision
controller,and ParaVision which contains the code and binaries
for Paravision.
The binary for the ParaVision controller has been supplied since re-compilation requires the prior installation of ET++ and Escallante. If installing ET++ and Escallante make certain ET++ is the modified version associated with Escallante.
The file ETRC that was extracted from the tar-ed file must be copied to the home directory of anyone using Paravision. The file can be modified to change the view of the user interface and turn some debugging features on. As a simple test, change the ShowPICL flag to YES which will result in printing the events to stdout. Okay, your ready to install and create applications.
- Getting Started
If you have not followed all the installation instructions please do
so know.
The Paravision system is ready to go. You don't need to have any applications to test the system, but to implement some of the instructions that follow get a simple application installed. dumpit is the most basic application and results in printing the events to stdout. The dumpit application will be used as the example in the Table of Contents
- The Interface
- The Events
- ParaVision System Events
- cCommandMark = -2; // Events that occur at a fixed point in time.
- cCommandBegin = -3; //The start of an event that occurs over a period of time.
- cCommandEnd = -4; //The termination of an event matched to the begin.
- cCommandLabel = -5; //Used to pass information for a lookup table mapping numbers to names.
- cAllEvents = 9996; //This event is never generated by the Paravision controller but is used in the ParaVisionRegister file to requesting all events be registered with the application.
- cFinishTime = 9997; //The event is sent at startup specifying the termination time of the trace file.
- cReverseTimeFlow = 9998; //This event is sent to all applications, it need not be registered, specifying the change of flow direction within the trace file. This event is generated by the user interacting with the graphical controller.
- cSockDone = 9999; //Instructs the application to terminate and is sent to all application upon termination of the Paravision system by the user.
- Registering Events
The Paravision controller has a graphical user interface for run time
functionality. While command line arguments and configuration files
are used at startup. If desired Paravisions look and feel can be
modified, before startup, using the ETRC file as described in the installation.
Before starting a session make sure the desired applications are registered with Paravision. The file ParaVisionRegister, which is in a PICL 2.0 like format, contains the list of applications to be executed and the events registered to each application. The program eventregister.C can be used to create the ParaVisionRegister file and avoid some of the hassles entailed in manually encoding PICL 2.0. This process is described in the Event Registration section.
Your know ready to start Paravision. It is recommended that you run Paravision from the directory containing the trace file. In this way the ParaVisionRegister file that you have specially designed for the current trace will be used. If the ParaVisionRegister file can not be found in your current directory, the default file will be retrieved from the ParaVision directory. Executing from the location where the trace file was created will also make it possible for applications to find files with the path specified in the trace file. For example, to user the TRAP example trace from its directory, on the command line type ../../ParaVision/ParaVision new_trace and your now ready to use the graphical controller.
The controller as seen above has 4 click-able button, and
a slider bar. The Quit button terminates the Paravision system, but
first verifies that you really want to quit. The controller
sends the quit command to all the applications and then terminates.
The Step button causes the controller to proceed through the
trace file by one time increment. The increment is specified in the
ETRC file by the ParaVision.TimePerTick(Num) command.
The Forward or Backward button, depending on your
current flow direction, toggles the time flow and sends the
reverse time event to all applications.
The current time and termination time of the trace file are displayed on the controller. The Run button causes the controller to execute the trace file. The rate at which the trace file is executed can be specified in the ETRC file, as mentioned above, and at run time via the slider bar.
The trace files Paravision uses follow the PICL 2.0 self defining
format. Below is a small sample to demonstrate the look of a PICL 2.0
trace file.
-5 -1 0.000000 262147 -1 1 "%s" ./timing40003 -5 -11 0.000001 -1 -3 1 "%s" mytid -3 -11 0.000002 262147 -1 5 "%8c%6c%d%d%d" ./timing lampur 262147 45 1 -5 783 0.962522 262147 -1 3 "%15c%d%d" ../src/timing.c 52 1 -5 -598 0.962522 -1 -3 1 "%s" spawn -3 -598 0.962523 262147 -1 4 "%12c%2c%d%d" timing_slave "" 52 1 -5 -598 0.980987 -1 -4 1 "%s" spawn_done -4 -598 0.980988 262147 -1 5 "%12c%2c%d%d%d" timing_slave "" 262148 52 1 -5 -479 0.987196 -1 -2 1 "%s" initsend -2 -479 0.987197 262147 -1 4 2 1 7 68 1 -5 -480 0.988815 -1 -2 1 "%s" pkint -2 -480 0.988816 262147 -1 4 2 0 1 69 1 -5 -27 0.989399 -1 -3 1 "%s" send -3 -27 0.989400 262147 -1 8 2 4 1 262148 -1 1 0 75 1 -5 -27 0.990338 -1 -4 1 "%s" send_done -4 -27 0.990339 262147 -1 8 2 4 1 262148 -1 1 0 75 1 -5 -51 0.990745 -1 -3 1 "%s" recv -3 -51 0.990746 262147 -1 4 2 -1 -1 80 1 -5 -1 1.801020 262148 -1 1 "%s" m3/bin/HPPA/timing_slave40004 -3 -11 1.801021 262148 -1 5 "%24c%6c%d%d%d" m3/bin/HPPA/timing_slave lampur 262148 27 1 -5 783 1.887759 262148 -1 3 "%21c%d%d" ../src/timing_slave.c 31 1 -2 -479 1.887759 262148 -1 4 2 1 5 31 1 -2 -480 1.889238 262148 -1 4 2 0 1 32 1 -3 -51 1.889706 262148 -1 4 2 -1 -1 37 1 -5 -51 1.890197 -1 -4 1 "%s" recv_done -4 -51 1.890198 262148 -1 8 2 4 1 262147 -1 1 7 37 1 -5 -14 1.890606 -1 -2 1 "%s" bufinfo -2 -14 1.890607 262148 -1 6 2 262147 0 0 0 38 1 -3 -27 1.891083 262148 -1 8 2 4 2 262147 -1 1 0 39 1 -4 -27 1.891809 262148 -1 8 2 4 2 262147 -1 1 0 39 1 -3 -51 1.892271 262148 -1 4 2 -1 -1 37 1 -4 -51 1.900891 262147 -1 8 2 4 2 262148 -1 1 5 80 1Parsing events in the PICL 2.0 format, as seen above, will be discussed in detail in the section on Creating an Application. For now it will suffice to say that the 1st position is the record type, 2nd is the event type, the 3rd is the relative time of the event, 4th is the process id, 5th is the processor, and then comes the self defining part of PICL. The 6th number says how many items follow and the format of the items is described by integers or a C format type string. For more details see the PICL 2.0 description.
An example trace file can be found in the traces/TRAP directory. Some work needs to be done to create a trace file after executing a program. The program in the trapezoid example creates a separate file for each process. The files must be merged and sorted by time stamp before using it with Paravision. The files trap.trace0, trap.trace1, trap.trace2, ... need to be merged into one file. The following commands will do this for you. Type cat trap.trace*|sort +2n > trapezoid.trace and now you have one trace file named trapezoid.trace.
PICL 2.0 has a bunch of predefined record types and event types.
Paravision makes use of the record types which include:
To create your own ParaVisionRegister file, modify the eventregister.C program and then compile and run it. The Makefile has a command to compile and run the eventregister.C program. To do so, type make eventreg, and the above process will be executed.
To modify the eventregister.C program to register your events, place calls to the add_program function as seen in the default eventregister.C file supplied with Paravision. The parameters to add_program consist of the application name, the machine for execution of the application, the number of events, and lastly the list of events. Make sure that the application includes a full path name so that Paravision can execute the application. Currently the machine specification is ignored, so if you want to execute on machine foobar remember to use rsh <host> exec <application> as the application name. Some events and their effects are described earlier in this section.
- Creating an Application
The dumpit.C program is a minimal
example, demonstrating the creation of a new application and it was
compiled using g++ 2.5.8. Make sure to
view the example for any specific information that may be left off in
this section. Applications require the inclusion of socket++.h
for use in connecting to the Paravision controller, datapt.h to
decode the PICL 2.0 format, and CommandList.h which contains
the list of possible events.
When starting the application read the information supplied by the server, the Paravision controller, via your applications command line.
- argv[1] - contains the host name (ie. bigtime.cs.colorado.edu)
- argv[2] - contains the socket number (ie. 2567)
- argv[3] - the name of the datafmt file (~/griff/ParaVision_datafmts)
- argv[4] - the trace file being parsed (traces/Trap/Trapezoid.trace)
It is now time for your application, the client, to connect to the server. Your code should have a global instance of the class sockinet instantiated using the parameter CLIENT. The connect_to_server method is then sent to sockinet with the parameters of the host name and socket number, in that order. The client and server are now connected via a socket. The socket can now be read using the sockinet method readln which returns one event per execution stored in a buffer passed in as a parameter along with the size of the buffer.
The buffer can be parsed by an instance of sdata by calling the method parse_event and passing in the buffer. The information is now present in the sdata instance. The record type and event type can be accessed in sdata via the get_rec_type and get_type methods respectively. For further details on creating applications see some of the existing applications.