Studio:Interfacing Sample

Note: for content related to versions of STRIDE 3.0.0101a and earlier, please refer to Autoscript Sample v3.0.0101a

Introduction

The following content relates to the sample files and workspaces installed in %STRIDE_DIR%\Samples\TestScripts\Interfacing. This sample consists of a Visual Studio workspace for building an off-target simulator, sample source code and test scripts, and a STRIDE workspace for sample code execution.

Getting Started

Prerequisites

Before starting, some prerequisites must be satisfied. For details and instructions, see Host Installation.

Specifically:

• STRIDE must be installed on the Windows PC to be used in the training, and any required licenses must be present.
• Active State Perl must be installed, and additional perl packages must be downloaded and installed.
• Microsoft Visual Studio 2005 or a later version must be installed. If you do not currently have any version of Visual Studio, we recommend that you install the current free version of Visual Studio Express.

Basic Execution

To begin, open the Visual Studio Solution file in the sample directory. This solution (and corresponding project) were created for Visual Studio 2005. If you have a later version of Visual Studio installed, you should be able to open this solution and it will be automatically upgraded if necessary.

Once you have successfully opened the solution, rebuild it. The build process has custom STRIDE build rules integrated and will produce a STRIDE database, intercept module source files, and an off-target simulator application that incorporates the sample source code.

Once the build is complete, perform the following steps to run the sample scripts in the workspace:

1. launch the off-target simulator, Interfacing.exe. This will run in a standard console window.
2. open a command prompt window and change to this sample's directory.
3. at the command prompt, run the command WorkspaceRun.pl -x setup -x teardown. This will execute all of the sample test scripts in the workspace and displays the results. You may open a browser and display the report written to the Ascript_Samples.html file in the sample's directory .
4. quit the Ascript_Samples.exe application by typing 'q' in its console window.

Sample Description

Now that you have built the off-target simulator and executed the scripting samples, you can take time to peruse the sample scripts. This section provides a brief description for each category of example scripts. You can execute any of the scripts manually as long as you have the off-target simulator (Interfacing.exe) running.

The main focus of this sample is the use of your SCL qualified interfaces in script code. The STRIDE object that enables this is AutoScript - declared as ascript when injected into Studio's script execution environment. We provide functionally equivalent examples in two languages: jscript and perl. We recommend that you try to follow the provided examples in whichever language you are most comfortable reading.

Calling Functions

Shows how to call functions that have been captured and qualified using STRIDE. These scripts make calls to functions that have been implemented in the off-target simulator. The examples shows how to set-up and invoke the functions with a variety of input data types.

Scalars

Shows how to make calls and receive and return values consisting of simple scalar values (int, float, char, etc.) that are passed by value.

Structs

Shows how to make calls to functions that accept and/or return structures by value.

Arrays

Shows how to make calls to functions that have fixed size arrays in their input arguments. The techniques used here to set individual array members are very similar to those used when working with Sized Pointers.

ArrayDataXfer

Shows how to make use of the AutoScript Bulk Transfer interfaces for setting array data. These bulk transfer interfaces can provide better performance for setting large array payloads since all of the data is transferred to ascript using a single COM interface property assignment. For large array payloads, there can be undesirable COM call overhead performance penalty when using the ascript object model directly to set each array member value one-by-one (since each member will be set with a COM interface property invocation). These methods provide a means to mitigate that overhead.

The bulk data transfer interfaces require that you provide strings that represent an entire array's worth of data - partial data is not allowed. For multidimensional arrays, the data must be stored in the string in row-major order. This example uses the same interfaces and the Array example (above) but the data is assigned using the HexString, B64String, or SafeArray properties.

The first example (f_cf_array_1) requires a 3 element, 1 dimensional array of integers. Our target's integers are 4 bytes, thus 24 hex digits are required to represent the array's data. Each 4 bytes (8 hex characters) in our example represents the integer value 10 in little endian byte order which is appropriate for our windows off-target app.

The next example (f_cf_array_2) requires a 3x3 array of integers. Here we use a base64(see RFC 2045) encoded string which requires 48 B64 characters to represent the 36 bytes of the array. Each element in the array again holds the value 10.

The third example (f_cf_array_3) uses a safearray (also known as a COM array or a VBArray) to set the array elements. JScript does not natively support safearrays for writing/assignment, but the Scripting.Dictionary object provides a means for creating a safe-array from a hash table.

Strings

Shows how to use strings in function calls.

Pointers

Shows examples of basic pointer usage, as documented by scl_ptr. The first three examples show how to assign and read pointed-to values. The last example shows how to set a pointer to NULL. For more information on working with pointers in ascript, refer to this article.

OpaquePointers

Shows how to call functions that have been qualified with scl_ptr_opaque. When working with opaque pointers, the ascript dynamic objects for that parameter refer to the pointer value and not the pointed-to value (as described in the aformentioned article).

SizedPointers

Shows how to set-up parameters that have been qualified with scl_ptr_sized. The first example (f_cf_sized_pointer_1) declares a size field in the pragma and the script must therefore correctly set the size field. The second example (f_cf_sized_pointer_2) does not declare a size field, therefore the data is assumed to be fixed size. The next example (f_cf_sized_pointer_3) shows how INOUT sized pointers are returned and how the resulting outpointers are accessed. The fourth example (f_cf_sized_pointer_4) shows how to access OUT sized pointers. In this example, we have also declared the the return value of the function as the size field for the OUT sized pointer. The last example (f_cf_sized_pointer_5) shows how to use RETURN sized pointers.

Unions

Shows how to call functions with union input parameters that have been qualified with scl_union. The first two examples show basic examples of calling discriminated unions. The third example demonstrates the use of an enum discriminant value where scl_union_activate has been used to map enum values to active indexes. The last example shows a simple fixed-active member union.

Values

Shows how to make calls to interfaces with parameters that have been qualified with scl_values. The two examples show how to call interfaces with parameters that have been constrained by an enum or user-defined list of values.

Owning Functions

Shows how a functions implementation (aka owner) can be scripted. The basic steps to implementing an owner in sciipt are:

1. Register for ownership of the function. More specifically the auto script method Register() (or OverrideRegister()) must be called. 2. Call the autoscript api WaitForEvent(). This will pause execution of the script until a caller invokes the method and the method call will be delivered to this script as an event. The event object will actually be FunctionOwner (subtype of Event). This can be validated in script as the event Type field will have the value "FunctionOwner" 3. Handle the call by checking the values of the parameters or setting return values. 4. Return to the caller with the autoscript Return() method.

Running Test Units

Run

This demonstrates the use of the TestUnits collection and items to invoke test units. The examples shows script examples of executing a single test units, all test units, and a single test unit with constructor arguments.

The first example simply executes a single test units item from the collection by invoking the Run method. The next example shows how to run all the declared test units by iterating over the ascript collection. Any test units with constructor arguments will be called with default arguments. The collection is sorted in ascending alpha order before iterating to insure a predictable execution order. We store these results in a subsuite of our current default suite by creating a subsuite and assigning it to the ascript.TestSuite property.

The last example shows how to call a test unit with constructor arguments.

Using Constants

The AutoScript object model exposes preprocessor macros present in the compilation units given to the STRIDE compiler. There are a number of rules that determine exactly how the macros are interpreted by the compiler (refer to SCL Language Reference for details). The AutoScript Constants Object exposes the preprocessor macros as a collection of items with name an value properties.

Macros

This shows how to use the Value field to refer to the interpreted value of the declared macro. In many cases, this is just the string representation of the macro as declared in the source code. In some cases, when the expression can be readily interpreted as an arithmetic or logical expression, the result of the expression is returned in the Value field instead. Refer to the corresponding Constants.h source file when reviewing this example.