update for tcl7.5
[dyninst.git] / visiClients / tclVisi / README
1 #
2 # $Log: README,v $
3 # Revision 1.2  1994/07/20 21:48:29  rbi
4 # Documented Dg commands
5 #
6 # Revision 1.1  1994/06/01  17:25:34  rbi
7 # Initial documentation
8 #
9 #
10
11 This directory contains the source code for tclVisi, a tcl interface
12 to the visi library.  The visi library is a C++ interface to paradyn
13 data (see ../../visi).  
14
15 To use tclVisi, a programmer writes a tcl application and makes calls
16 to DataGrid (or Dg) commands.  The Dg commands allow a tcl application
17 to get information about metrics, resources, and data values.
18 tclVisi, in turn, makes Dg callback commands to the tcl application to
19 tell it when configurations have changed and when data is available.
20
21 Subdirectories:
22   src -- source code for tclVisi
23   tcl -- code for tcl applications
24   ${PLATFORM} -- platform specific binaries and makefiles
25
26 Dg service commands
27 -------------------
28
29   tclVisi provides a tcl command called "Dg" that a visi may call to
30 get performance information.  "Dg" has several sub-commands, each of
31 which returns different information to the visi.  This section
32 describes the commands in detail.  Arguments in angle brackets <>
33 denote input parameters.
34
35   Dg nummetrics -- this command returns the number of currently defined
36                    metrics.  Metric identifiers (mids) are integers between
37                    0 and [expr [Dg nummetrics]-1]
38
39   Dg metricname <mid> -- returns the name of metric <mid>
40                      An example metric name might be "procedure_calls"
41                    
42   Dg metricunits <mid> -- returns the units of metric <mid>.  
43                       An example metric unit might be "calls/sec"
44
45   Dg numresources -- this command returns the number of currently defined
46                   resources.  Resource identifiers (rids) are integers 
47                   between 0 and [expr [Dg numresources]-1]
48
49   Dg resourcename <rid> -- returns the name of resource <rid>
50        Resource names are given in the full paradyn naming style.  The
51        resource name is defined as exactly one representative from each
52        resource hierarchy.  For example, if the resource hierarchies are
53        defined to be Machine, Process, and Procedure, then the root (or
54        top-level) resource is named <Machine,Process,Procedure>.  The
55        resource indicating procedure "main" on machine "beaufort" would be
56        named <Machine/beaufort,Process,Procedure/main>
57
58   Dg valid <mid> <rid> -- test if a time histogram is valid
59        returns 1 if a time histogram exists for metric <mid> and 
60        resource <rid>.  returns 0 otherwise
61
62   Dg value <mid> <rid> <bucket> -- returns a value from a time histogram
63        This command returns the value in bucket <buck> of the time histogram
64        of metric <mid> measured for resource <rid>.  Every valid
65        <mid>,<rid> corresponds to a different time histogram, and every
66        time histogram consists of an array of buckets numbered 0 to [Dg
67        numbuckets <mid> <rid>].  Each bucket in a time histogram corresponds
68        to a period in time of [Dg binwidth] seconds.  The value in the 
69        bucket is the measured value of the performance metric during the time 
70        period to which the bucket corresponds.  Therefore, if [Dg binwidth] 
71        returns .5 then [Dg value 0 1 20] will return the measured value of 
72        metric 0 for resource 1 for the time period between 10 seconds and 
73        10.5 seconds after the start of execution.
74        
75   Dg sum <mid> <rid> -- returns sum of a time histogram
76        This command returns the sum of all buckets of the time
77        histogram of metric <mid> measured for resource <rid>.
78
79   Dg aggregate <mid> <rid> -- average value of a time histogram
80        This command averages all bucket values in the time histogram
81        of metric <mid> measured for resource <fid>.
82
83   Dg numbins -- number of buckets in time histograms
84        returns the total number of buckets in time histograms.  Every
85        time histogram has the same number of buckets.
86   
87   Dg lastbucket -- last bucket filled in time histograms
88        returns the index of the last bucket filled in the time histograms.
89        Every time histogram is filled at the same rate, so the return 
90        value from this command gives the last bucket filled for all 
91        of the time histograms.
92
93   Dg start <metricname> <resourcename> -- start a new histogram.  
94      this command asks paradyn starts a new histogram of data 
95      corresponding to metric <metricname> and resource <resourcename>.  
96      Currently, <metricname> and <resourcename> are ignored, so make 
97      the call like this:
98
99             Dg start "*" "*"
100
101      Paradyn will ask the user to chooe a metric and a focus, and then 
102      will notify the visi with a call to DgConfigCallback after the user 
103      chooses.
104
105   Dg stop <mid> <rid> -- stop a histogram.
106      this command asks paradyn to stop sending data for the histogram 
107      corresponding to <mid> and <rid>.  After paradyn stops the data, 
108      it will notify the visi with a call to DgConfigCallback.
109
110 Dg callback commands
111 --------------------
112
113   The Dg callbacks are commands that must be implemented by a visi if
114 the visi wants to be notified of important events.  Here, we explain
115 when the commands will be called and what information is passed.  The
116 behavior of the callback command is left completely to the visi
117 writer.
118
119 DgConfigCallback -- configurations have changed
120   "Configuration" include the number of resources, the number of
121   metrics, the names of metrics, and the names of resources.  This
122   callback is called if and only if any of these values change.  The visi
123   must call the Dg service routines if it wants to find out exactly
124   what changed.
125
126 DgDataCallback <first> <last> -- new data is available
127   This command is executed whenever new data is available.  <first> 
128   indicates the first bucket containing new data and <last> indicates 
129   the last bucket that contains new data.  These new data values are 
130   available in all valid time histograms.  The visi must call Dg service
131   routines if it wants to find the values of the new data.
132
133 DgValidCallback <mid> <rid> -- new time histogram is now valid
134   This command is executed when the time histogram for metric <mid> 
135   measured for the resource <rid> is valid.  
136
137 DgFoldCallback -- time base has changed
138   When the last buckets of the time histograms have been filled, the time
139   histograms are folded so that the bucket widths are doubled and 
140   only the first half of the histogram is used and the second half can be 
141   filled again.  When this happens, the DgFoldCallback command is called 
142   to notify the visi.  When this command is executed the visi must 
143   assume that all bucket values in all time histograms havee changed,
144   the global bucket width has changed, and the global lastbucket value 
145   has changed.
146
147   
148