Update some obsoletes. -czhang
[dyninst.git] / paradyn / src / met / README
1
2 A simple configuration language.
3
4 q0) What is the configuration language?
5 q1) What files are used?
6 q2) Where are these files located?
7 q3) How are the files used?
8 q4) What can be defined?
9 q5) What keywords exist in the simple configuration language?
10 q6) What if I don't want to commit to a specific host?
11 q7) Where can I get more information?
12
13 q0) What is the configuration language?
14      A parser has been built into paradyn that searches for 
15      configuration files, parses these files, and takes actions
16      based on the parsing.
17
18 q1) What files are used?
19      The metric parser uses a system configuration file, user
20      configuration file, and an applicaton configuration file. 
21      Paradyn can run without the existence of these files.
22      The following information is compiled into paradyn (for the
23      time being).
24
25      daemon pvmd { command "paradyndPVM"; }
26      daemon cm5d { command "paradynd"; }
27      visi HISTOGRAM_REALTIME { command "rthist"; }
28      visi TABLE { command "tclVisi"; }
29
30 q2) Where are these files located?
31      The system configuration file is searched for in 
32      $(PARADYN_ROOT)/paradyn.rc, and then in $(CWD)/paradyn.rc if it
33      is not found in the first location.
34
35      The user configuration file is searched for in $HOME/.paradynrc
36
37      The application configuration file is specified on the command
38      line when paradyn is started.  The command line has one option,
39      -f <app file>.  So, 'paradyn -f App' would cause paradyn to attempt
40      to open the file 'App' in the current working directory and parse
41      that file.
42
43 q3) How are the files used?
44     The system configuration file is read first, followed by the
45     user file, and then the application file.   Name equality
46     is used to determine when two requests are equal, in which case
47     the latest request read will be used.  Each element in the 
48     configuration language has a name (which is noted in the language
49     element descriptions that follow) that will be used for this
50     purpose.  Information on the elements of the language is discussed
51     later.  The files are read before the paradyn threads are created, and 
52     data from the files may be available to the thread at thread
53     initialization time, if it is needed.  Otherwise, after all of the
54     threads are created, igen thread calls are made from function 'main'
55     to the datamanager thread to define daemons and start processes.
56     Calls are also made to the visiualization manager to define 
57     visualizations.
58
59 q4) What can be defined?
60     Comments
61     Lists
62     tunableConstant settings
63     paradyn daemons definitions
64     processes to start
65     visualization definitions
66
67     A comment on comments
68         Consecutive slashes, "//" are used to include comments in the
69         configuration file.  The comment is from the "//" to the end
70         of the line.
71
72     IDENTIFIER = string, not quote delimited
73     LITERAL = quote delimited string
74     INT = integer
75     FLOAT = floating point number
76     BOOLEAN = {TRUE, FALSE}  (case does not matter}
77
78     Lists:
79         list <name> { [<list item>,]* }
80
81         <name>: IDENTIFIER 
82         <list item>: LITERAL
83
84         list Practice { "item1", "item2" } 
85
86         Effects:
87             lists currently are of limited use in the configuration language
88
89         Note: the <name> field is used to detect duplicate definitions
90
91     tunableConstant settings:
92
93         tunable_constant <name> <tunable value>;
94         tunable_constant { [<name> <tunable value>;]* }
95             
96         <name>: LITERAL
97         <tunable value>: FLOAT
98         <tunable value>: INT
99         <tunable value>: BOOLEAN
100
101         tunable_constant "maxEval" 3;
102         tunable_constant {
103             "maxEval" 3;
104             "minObservationTime" 5.1;
105             "pcPrintEval" TruE;
106         }
107
108         Note: the name field is used to detect duplicate definitions.
109               the name field is also the name by which the paradyn
110               knows the tunable constant.
111
112
113     paradyn daemons: 
114
115         daemon <name> {
116             command <cmd string>;
117             [flavor <flavor type>;]
118             [user <user name>;]
119         [dir <directory name>;]
120             [host <host name>;]
121         }
122
123     REQUIRED:
124     <name>: IDENTIFIER, the name of the daemon, this allows daemon
125                 definitions to be looked up and replaced.
126         <cmd string>: LITERAL, the command to use to start this paradyn
127                       daemon (for exec's)
128
129     OPTIONAL:
130         <host name>: IDENTIFIER, same as <host name> in the process
131                 definition below.
132     <user name>: IDENTIFIER, same as <user name> in the process
133                 definition below.
134     <directory name>: IDENTIFIER, same as <directory name> in the
135                 process definition below.
136         <flavor type> a keyword that represents the environment type
137            the possible choices are enumerated in the next section.
138
139         Effects:
140            This enters this data structure into a daemon dictionary
141            that the dataManager maintains to match daemon names to
142            dictionary entry.  
143
144         Note:
145            the fields in the daemon structure can be declared in any
146            order.  They can also be redeclared within the same structure.
147            The effect of the following is legal but undefined in terms
148            of which host name will be used.
149
150            daemon { 
151                command "paradyndPVM";
152                host "poona";
153                host "cham";
154            }
155
156     Processes
157         process <name> {
158             command <command string>;
159             daemon <daemon string>;
160             [host <host string>;]
161             [user <user name>;]
162         [dir <directory name>;]
163         }
164
165         REQUIRED:
166         <name>: IDENTIFIER, the name of the process
167         <command string>: LITERAL, the command to use to start this paradyn
168                           daemon (for exec's)
169         <daemon string>: IDENTIFIER, the name of the daemon used to get 
170                          the data needed to start the daemon from the
171                          daemon dictionary
172
173         OPTIONAL:
174         <user name>: IDENTIFIER, specifies the user name (login) under which
175                      the process will run. If no user field is present, it
176                      will default to the same user name under which Paradyn 
177                      was started.
178         <directory name>: IDENTIFIER, specifies the working directory for the
179                      process. If no dir field is present, it will default to
180                      user's home directory on the remote machine.
181         <host string>: IDENTIFIER, the name of the host on which the process
182                        should be started.  If this field is not specified, the
183                        process is started on the local machine.
184
185         process default {
186             command "potato";
187             daemon "paradyndPVM";
188         }
189
190
191         Effects:
192             a process is started using <command string> on the local host
193                 under the control of daemon <daemon string>.  <daemon string>
194                 is used to get an entry from the daemon dictionary. 
195
196         Note:
197            the fields in the process structure can be declared in any
198            order.  They can also be redeclared within the same structure.
199            See the discussion on daemons for an elaboration of this.
200  
201
202     Visualizations
203         visi <name> {
204             command <command string>;
205             [user <user string>;]
206             [host <host string>;]
207             [dir <directory>;]
208             [force <int >;]
209                 [limit <int>; ]
210         }
211
212         REQUIRED:
213         <name>: IDENTIFIER, used to replace visi definitions.  This
214                 string is displayed by the user interface.
215         <command string>: IDENTIFIER
216
217         OPTIONAL:
218         <user string>: IDENTIFIER, not used now
219         <host string>: IDENTIFIER, determines where the visi is started
220                        no entry implies the local host
221         <directory>:   IDENTIFIER, not used now
222         <force>:  int, if 1 then the visi will be started without menuing
223                   first, otherwise met/focus menuing will occur first
224
225         Effects:
226             a visualization named <name> is made available to
227             paradyn.  The visualization is started with the command
228             <command string>, which may include arguments.
229
230 q5) What keywords exist?
231
232     // - a comment 
233     visi
234     list
235     daemon
236     process
237     name 
238     host
239     flavor
240     command
241     dir
242     user
243     tunable_constant
244     flavor - one of {pvm, unix}
245     pvm -  a flavor
246     unix - a flavor
247
248 q6) Any 'host' field that is not specified implies that the local
249     host should be used.
250
251 q7) More info?  See metParser.y for the grammar.