S P E X Software Performance Experiment Driver Version 1 By Alex Hubbard August 1997 Real-time and Distributed Systems Group Department of Systems and Computer Engineering, Carleton University, Ottawa, Canada. Introduction Input File Format Spex uses a number of syntax rules for parsing its input. The file is read line by line and the syntax rules are applied to each line in the order of the rule highest priority to the lowest priority rule. Comments and Continuations The highest priority rule is the rule that checks for continued lines. If an input line ends with a backslash (\) followed by optional whitespace and ultimately by a newline with no intervening text, the line is said to be continued and spex appends the next line to it. Any number of consecutive lines may be continued in this way. Once a complete line has been read, the remaining syntax rules are applied (but not before). The next highest priority rule is the comment rule. Any characters following a hash mark (#) through to the end of the line are considered to be a comment and are generally ignored. However, should a line begin with optional whitespace followed by '#pragma', then the remainder of the line will be reported to the solver as a pragma (more on pragmas below). All comments (and pragmas) of this type are removed from the input file before any other syntax rules are applied. Note that because the comment rule has a lower priority than the line continuation rule, comments may be continued with the backslash (\). Model Title and Description The remaining syntax rules depend on the state of the input parser. In its initial state, the parser collects zero or more lines of text which will form a description of the model. This description serves as the 'model comment' printed as part of the header in the solver's low level input file. The first line of the description is used as the title of the model and is printed in the results file header. Extra blank lines at the beginning and end of the description are removed. Double quotes (") are handled properly. The description ends and the next state is reached when a line matching any of the following constructs is detected: Type of Construct Matching Text Next State --------------------------------------------------------------- Parameter Assignment $name = initwait Pragma Definition pragma initwait Global Information G global Processor Information P processor where is the rest of the line and is small non-negative integer (often zero -- more on this below). The third column gives the name of the next state. These states are each described below. Setting Pragmas, Controls, and Parameters Once spex has moved beyond its initial state -- that is, the model description has been fully read -- some new rules are activated and remain active throughout the remainder of the input file processing. These rules are subordinate to the previously stated rules governing continued lines and comments. Note that the spex syntax forbids the use of a semicolons (;) to terminate a line. The next highest priority rule (coming just after the comment rule) is the blank line rule. All blank lines are ignored. Pragmas The next rule is the second pragma rule. Any line beginning with optional whitespace followed by the word 'pragma' (no leading '#') will be reported to the solver as a pragma. This rule is more convenient since there is no need for the hash mark (#). The first pragma rule (the one with the hash mark) is still needed in order that spex be able to properly handle all existing model files without modification. Variable names may appear in pragma statements (more on variables below). Controls The next rule handles lines matching control statements of the form $variable = where is some numeric or textual value (expressions and lists are not allowed here). The following table is a complete list of all the possible controls and the types of values to which they can be set. Control Variable Type of Value Default Value ----------------------------------------------------------- $convergence_limit 0.00001 $iteration_limit 100 $print_interval 1 $coefficient_of_variation 0.9 $solver lqns Other values for the $solver variable are 'parasrvn' and 'petrisrvn'. Any command line options or arguments may be included in the text value (see the examples below). The same control may be set multiple times in an input file but only the last setting has any effect. If the optional general information section (described below) is included in the input file, then the $convergence_limit, $iteration_limit, $print_interval, and $coefficient_of_variation variables have no effect. Array Parameters If the line matched $name = but was not a control setting, then the next rule handles the line as a parameter setting. There are two classes of parameter: array parameters and scalar parameters. An array parameter is specified in one of two ways: $name = :, This sets $name to the array of numeric values beginning at value and stepping by an increment of until is reached or the last value before if does not evenly divide the interval [,]. Any amount of whitespace may be added around the (=), (:), and (,) characters. $name = , , ... This sets $name to the array of textual or numeric values specified by the comma-separated (or space-separated) list , , , etc. When textual values are given in a list they are usually given as plain text. However, if a textual item is to be used in an expression, perl requires that the item be enclosed in single or double quotes (single quote are preferred). Scalar Parameters and Expressions If the parameter was not an array parameter than the line is interpreted as a scalar parameter setting of the form: $name = where is any legal perl expression yielding a scalar value. Remember that text items need to be quoted. The expression may contain any parameter variables defined previously or subsequently in the input file; order does not matter. However, undefined variables or observation variables (more on these below) are not permitted. By convention, pragma definitions and array or scalar parameter definitions usually appear after the model description text and before the general info or processor info sections. However, due to the high priority of the rules governing these constructs, they may appear anywhere after the model description including nested in and between the various sections defined below. The Remaining States The state immediately following the initial state depends on the type construct next to be read as described above. If the global information is next the state goes to 'global'. If the processor information is next, then the state goes to 'processor'. If however, pragmas (without the '#'), parameter settings or controls follow, then the state goes to 'initwait' until the start of the global info or processor info (at which point it goes to 'global' or 'processor'. This 'initwait' state allows the pragmas, parameters, or control settings to end the model description but also appear anywhere else in the model file. The Global Information The global information section of the file is optional. Actually, it is included only for backward compatibility reasons. Most models files will use the model description and controls mentioned above. The global information section has the following format: G "" -1 The arguments have the same meaning and types of values as described the the section on controls discussed above. Remember that if a model file contains a global information section of this type and control settings as described above, the control settings are ignored and the global information section only is used. The global information can be split over multiple lines without requiring the use of the line continuation character (\). The Processor, Task, Entry, and Activity Information After the global information section comes the processor information section which is followed by the task information section which is then followed by the entry information section. None of these three sections is optional. The activity information which comes after is optional. For more information on the syntax for these four sections, please refer to the 'SRVN Input File Format' reference manual. The remainder of this guide assumes that the reader is familiar with the basic syntax of these four sections. Note that the various declarations in these sections must not be split over multiple lines unless the continuation character (\) is used. Variable Substitution A variable as described above may be used in place of *any* token in any of these four sections. For example, a variable may be used to represent a processor name in a task declaration or a service time in an entry service demand declaration or a scheduling policy indicator in a processor declaration. Observation Indicators There is a set of special symbols that are used to indicate to spex which result values from the solution of the model are of interest. This result indication has the following form: % $var where is a one or two letter key indicating the type of data to be observed and is an option integer indicating the phase of the data to be observed. The data, once obtained from the results of the model, is placed into the variable $var where it may be used in the Result Information section described below. The location of a result indication determines the entity to be observed. First a list of all the keys and their meanings is given. Key Description --------------------------------------------------- %u Utilization %f Throughput %pu Processor Utilization by Task, etc %s Service Time %v Service Time Variance %fb Throughput Bounds %pw Processor Waiting Time by Task, etc %w Waiting Time The following table is description of where the keys may be used. Key Phase Location ------------------------------------------------------------- %u no processor declaration (p info) yes task declaration (t info) yes entry service declaration (s info) %f no task declaration (t info) no entry service declaration (s info) %pu no task declaration (t info) no entry service declaration (s info) %s yes entry service declaration (s info) %v yes entry service declaration (s info) %fb no entry service declaration (s info) %pw yes entry service declaration (s info) %w yes entry call declaration (y info) no entry open arrival declaration (a info) For any key/location combination that takes a phase argument, if none is supplied then the sum of the values for all phases is reported. This also happens if a phase of zero is given. Report Information The final section of the spex input file is the report section. The purpose of this section is to specify which variable values (including result indications) are to be printed in the spex result file. The format of this section is as follows: R -1 There may be any number of report declarations, however, the integer must either be the number of report declarations present or zero (actually, the number is ignored; it is present in the syntax so that the report section matches the other sections). A report declaration has the following form. Note that the result information may not be split over multiple lines unless the continuation character (\) is used. $var = The may be any valid perl expression as discussed above. Note that in this section, the report indication variables and the parameter variables may both be used together. There is a special variable called $0 which represents the independent variable in the results tables. That is, it is the left most column of the result output. The variable $0 may be set to any expression allowing for flexibility in producing result tables. The remaining variables listed on the left hand side of the equals sign in the report section appear as the remaining columns in the report tables. Also, the order of the report declarations determines the order of the columns in the tables. print "Usage: spex [-n] [-r] [-q] [-F format] [-C cmt] file [file ...]\n"; } Command Line Options The following are the command line options available with spex: -n This option disables the solver so that only model input files are produced. No output files or result files are generated. -r This option forces spex to reuse the output files it already has for a particular model. This option should not be used if the parameters of the model have changed since the output files were originally created. -q This makes spex run more quietly. -F This option takes an argument which determines which output format to use for the results file. The current formats that are supported are the following: gnu Gnuplot mat Matlab (Note that only the first letter of the argument is looked at by spex). If the -F option is not given, then the default format is used. The default format is plain ASCII. -C This option allows the 'comment character' to be set. This is the character that is used to lead a comment in the result files. For example, the character is '#' for the gnu and default formats and '%' for the the matlab format. Any single character may be used.