A script runs as part of the simulation test cycle and, thus, is resumed every cycle by the scheduler. It relinquishes execution after doing the work corresponding to the cycle. If it doesn’t, the test cycle will overrun its alloted time, possibly causing the scheduler to terminate the test.
There can only be one script program running as part of a test. It runs after the input stage of the test cycle (after values are read from I/O devices and written to the real-time database (RTDB)), allowing it to overwrite values provide by the input cycle in order to affect the behavior of the simulation models that run after it.
The test scripting framework provides a transparent mechanism to be started when a test is run, to hook up into the scheduler, and to map the RTDB into its own address space.
Scripts can be written in the C programming language. In order to ease the programmer’s task, two additional pseudo-languages are layered on top of the C language.
SWs
Full C programming environment with additional macros. The macros ease access to the RTDB and wait or test for logical conditions on RTDB variables. An SWs file is processed by the sws_pp preprocessor (on the real-time host) to generate a C program that is then compiled and linked by the default gcc compiler.
SWm
Reduced-features pseudo-language. This language provides a very easy way to write programs that access the RTDB and test for logical conditions. An SWm file is processed by the swm_pp preprocessor (on the real-time host) to generate an SWs program.
Both SWs and SWm files always end up as C source files that are compiled and linked to produce a native executable that is run in the test cycle.
Additionally, both SWm and SWs scripts automatically create a test log file for every test run. Execution status of wait logical and test logical conditions are logged to the file with a pass/fail result (see waitcond, testcond). Options can be enabled in a script to halt the test run on error conditions, ignore errors, report errors and continue, etc. At the end of the test run, an html report is generated which gives a line by line account of the test execution.
Local variables must be valid C identifiers (they can be used directly in embedded C code) and may hold either a numeric value (implemented as a double in C) or a string value (implemented as a char[1024] in C). Local variables may not be named the same as an SWm keyword. The type of local variables is determined by the type of assignment operator used to assign a value to it.
RTDB variables may be accessed in one of two ways. First, the R.“variable” syntax may be used to access them directly. Second, a shortcut may be defined using the rtdb_ref statement and the shortcut used via the r.shortcut syntax.
The alternate and operator flags for an RTDB variable can be set or reset via the following assignment syntax:
r.shortcut.alt=true;
R.“variable”.alt=true;
r.shortcut.op=true;
R.“variable”.op=true;
Numerical expressions generally follow regular C syntax, with some enhancements.
The following operators are provided, in order of increasing operator precedence:
• + (add), - (subtract)
• * (multiply), / (divide)
• ^ (raise to a power)
• % (modulo)
• - (unary negate)
Parentheses can be used to override default operator precedence.
Logical expressions generally follow regular C syntax.
The following logical operators compare two numerical values and have the usual C meaning: >=, <=, >, <, ==, and !=. The following logical operators compare two string expressions for equality and inequality, respectively: eq and ne.
The following logical operators operate on logical expressions and have the usual C meaning: &&, ||, and !.
Two logical constants are defined: true and false.
Parentheses can be used to override default operator precedence.
The string concatenation operator is the period: ..
A statement occupies one, and only one, line. Multiline statements are not supported.
Assigns an expression to a variable.
variable = numeric_expression;
variable := string_expression;
Numeric values (including logical values) are assigned to a variable via the = operator; string values via the := operator. Assignment statements must be terminated with a semicolon. If the destination is a local variable, the operator chosen determines the type of the variable, which is not otherwise declared.
Starts a section with embedded C code.
code;
C statements...
endcode;
The source statements are placed “as is” in the generated C source file.
Configures the script program to ignore any Failed conditions generated by the script execution.
ei;
See if.
See code/
See section.
Writes a C language printf style formated string to the pseudo standard out and logs the string to the test log.
errormsg pass_or_fail,error_code,format_string,expression_list;
The pass_or_fail parameter is a numeric expression that must evaluate to -1 to log Fail, 1 to log Pass, or 0 for a user condition. The error_code parameter from simerrors.h. A negative value always indicates an error conditions. For user error codes, a value less than -10000 or greater than 10000 should be used.
Configures the script program to abort execution of the script and terminate the test run with an error whenever a Fail condition is generated.
es;
Configures the script program to generate a warning when a Fail condition is generated instead of terminating the script.
ew;
Writes a C language printf style formatted string to the pseudo standard out and logs a Fail entry to the test log.
failmsg error_code,format_string,expression_list;
The error_code parameter from simerrors.h. A negative value always indicates an error conditions. For user error codes, a value less than -10000 or greater than 10000 should be used.
Transfers execution of the program to the specified label.
goto label;
statements...
label:
statements...
Conditionally executes statements.
if logical_expression
statements...
else
statements...
end
Includes the contents of another file at the line the statement appears at.
include “filename”
See goto.
Configures whether the script program will log Pass conditions to the test log file.
logsuccess logical_expression;
When the logical_expression is false, successful waitcond and testcond statements are not recorded to the test log file. Only Fail conditions are logged. If true, both Pass and Fail conditions are recorded for waitcond and testcond statements.
Writes a C language printf style formatted string to the pseudo standard output and to the test log.
msg format_string,expression_list;
Writes a C language printf style formatted string to the pseudo standard out and logs a Pass entry to the test log.
failmsg error_code,format_string,expression_list;
The error_code parameter from simerrors.h. A negative value always indicates an error conditions. For user error codes, a value less than -10000 or greater than 10000 should be used.
Writes a C language printf style formatted string to the pseudo standard output.
print format_string,expression_list;
Reads from the psuedo standard input and sets the values of the variables specified to the values parsed in the input buffer.
read timeout_seconds,variable_list;
The user must delimit values with a comma or semicolon. If the time out expires without the user providing input, a Failed message is logged to the test log. Specify a negative value for the time out to disable timing out. If the user does not provide enough values, the leftover variables will be undefined.
See ninputs.
Defines a shortcut for an RTDB variable.
rtdb_ref “variable”,shortcut;
Writes a C language printf style formatted string to the pseudo standard output and makes an entry in the test log that marks additional entries as part of this section.
section format_string,expression_list;
statements...
endsec
Sections may be nested. This organizes the test log and its report file into different sections and subsections.
Stops the script program and terminates the test run.
stop;
Defines a subroutine.
sub subroutine_name;
statements...
end
Subroutines do not take parameters, but have access to all local variables.
Logs the line number of this statement and the result of the logical expression to the test log file as Pass for true and Fail for false.
testcond logical_expression;
Logging of Passed may be disabled by the logsuccess statement.
Suspends execution of the script, allowing test cycles to continue executing, until the logical expression evaluates to true or the time out expires.
waitcond logical_expression,timeout_seconds;
The condition is tested once every test cycle. This statement is logged to the test log file as Pass when the logical expression evaluates to true and as Fail when the time out expires. Logging of Pass may be disabled by the logsuccess statement.
Suspends execution of the script, allowing the test cycle to continue executing, until the next test cycle frame comes around to the script step.
waitframe;
Suspends execution of the script, allowing test cycles to continue executing, for a number of seconds.
waitseconds seconds;
The time is rounded to an integer multiple of the frame rate.
Executes a block of statements while an expression is true.
while logical_expression
statements...
end
Extracts the left most portion of the string expression.
string_expression.left(number_of_characters)
If the number_of_characters specified is longer than the length of the string_expression, the whole string_expression is returned.
Extracts the right most portion of the string expression.
string_expression.right(number_of_characters)
If the number_of_characters specified is longer than the length of the string_expression, the whole string_expression is returned.
Extracts a substring from the string expression.
string_expression.mid(start_index,number_of_characters)
The start_index is the offset from the beginning of the string_expression where the substring will be extracted.
If the number_of_characters specified is longer than the length of the string_expression-start_index, the whole string_expression to the right of start_index is returned.
Formats an numeric expression as a string.
“”.number(expression,format_character,format_precision)
The numeric expression is formatted the same way as a C style printf with the specified format_precision and format_character. The the value of the string expression the function is attached to is not used.
Calculates the absolute value of the expression.
abs(expression)
Searches the string expression haystack for the string expression needle.
find(haystack,needle)
Returns the index from the beginning of haystack where needle is located, or -1 of needle is not found.
Truncates the fractional portion of the expression, returning an integer number.
int(expression)
Calculates the length of the string_expression.
length(string_expression)
Returns the number of fields read by the previous read statement.
ninputs()
See read.
Returns the current script status.
status()
The status is set by all statements that generate a Pass or Fail condition. Negative values, defined in simerros.h, indicate a Fail; non-negative values, a Pass.
Converts a string_expression into a numerical value.
value(string_expression)
If the string_expression contains illegal characters, a value of 0 is returned.