Studio:SCL Samples

Introduction

The following content relates to the sample files and workspaces installed in %STRIDE_DIR%\Samples\SCL. This sample consists of a Visual Studio workspace for building an off-target simulator, sample STRIDE Communication Language (SCL) source code, test scripts for host-side function calls and verification, and a STRIDE workspace for sample code execution.

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. Note: when the sample workspace is executed, a script runs that verifies that the required Perl packages have been installed correctly.
• 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.

Getting Started

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. If you do not currently have any version of Visual Studio, we recommend that you install the current free version of Visual Studio Express.

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, SCL_Samples.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 SCL_Samples.html file in the sample's directory .
4. quit the SCL_Samples.exe application by typing 'q' in its console window.

Sample Tests

Now that you have built the off-target simulator and executed the SCL sample code it contains, you can take time to peruse the sample source and the corresponding results that each produces. The Source Files workspace folder (in the Files tab) contains the header files that provide examples of SCL usage. This section provides a brief description for each.

Capture

This folder contains header files that demonstrate how to use SCL to identify and define interfaces on the target.

Functions

This folder contains a header file that demonstrates the usage of the scl_func and scl_function SCL pragmas.

Messages

This folder contains a header file that demonstrates the usage of the scl_msg SCL pragma to define several different types of interfaces: one way command, one way response, two way, and broadcast messages.

Qualification

This folder contains header files that demonstrate how to use SCL to annotate or markup interface payloads for communication with the target.

Casting

This folder contains a header file that demonstrates the usage of the scl_cast pragma. One example shows how to use SCL to cast an integer field to an enumerated type, effectively constraining the values that may be allowed for that field. Another example shows how to use the scl_cast pragma to cast an integer pointer to a pointer to enumerated type, constraining the values that that field may point to.

FunctionCallbacks

This folder contains a header file that demonstrates how to use the scl_ptr_flist pragma to identify functions that may be associated with a function pointer field in a payload. This illustrates a concept where callback functions may be communicated between user and owner. Examples include using a form of the pragma to declare an anonymous function interface (the "default function"), and using the pragma to associate previously captured functions with the function pointer field.

Pointers

This folder contains three header files that demonstrate the use of the scl_ptr, scl_ptr_opaque, and scl_ptr_sized pragmas.
In the scl_ptr examples, it is shown how to apply the pragma to pointer fields within structure types. The effect is that these pragmas are implicitly applied to the interface payloads that use these structure types. Then it is shown how to override the pragma settings by explicitly setting pointer attributes to individual interface payload fields. The sample code shows how to apply the OUT directional attributes to payload fields, in order for the user to receive data back from the owner when the interface call is made. The test script and intercept module will demonstrate how this is achieved.
The scl_ptr_opaque header file shows how to apply the pragma to a pointer type field, as well as an individual payload field.
The scl_ptr_sized header file shows how to use the pragma to associate a size field with a pointer field to indicate the number of elements allocated to the pointer. Both examples show values being returned by the function calls, meaning that memory is allocated and assigned by the function owners, running on the target application. The first pragma sample shows a pointer in the command payload qualified as a sized pointer, and the second sample shows the function return value qualified as a sized pointer.

Strings

This folder contains a header file that demonstrates the use of the scl_string pragma. The sample shows how to specify a pointer to short (Unicode) as a string, and an array of char as a string.

Unions

This folder contains a header file that demonstrates the use of the scl_union, and scl_union_activate pragmas. The sample shows a form of the pragma that designates a fixed active member, one that designates a discriminant with default mapping, and one that designates a discriminant with explicit mapping, using the scl_union_activate pragmas as additive specifications to the union.

Values

This folder contains a header file that demonstrates the use of the scl_values pragma to constrain the allowable values for a payload field. The sample shows a form of the pragma that specifies a list of values, and a form that specifies an enumerated type.

Test Execution

This sample demonstrates two different techniques for executing the sample test scripts.

Command Line Execution

Command line execution for sample STRIDE test workspace is done using the WorkspaceRun utility. Here is an example of specific syntax to execute a test workspace. All of these commands can be invoked from a standard command shell (or other shell of your choosing) and the arguments shown assume that the commands are executed with the sample's directory as the starting directory. You must have your SCL_Samples.exe application running in order for the runner to be able to initiate a connection to the target simulator.

 WorkspaceRun.pl -x setup -x teardown

When you run this command, you should see console output like:

 Opening workspace C:\S2\Seaside\Samples\SCL/SCL_Samples.ssw..
 excluding folder setup in workspace C:\S2\Seaside\Samples\SCL/SCL_Samples.ssw
 running folder test in workspace C:\S2\Seaside\Samples\SCL/SCL_Samples.ssw
 excluding folder teardown in workspace C:\S2\Seaside\Samples\SCL/SCL_Samples.ssw
 Test results written to C:\S2\Seaside\Samples\SCL\SCL_Samples.html
 ***************************************************************************
 Results Summary
 ***************************************************************************
   Passed:              19
   Failed:               0
   In Progress:          0
   Not Applicable:       0
   ...in 11 suites.
 ***************************************************************************

Workspace-Based Execution

We provide a sample STRIDE workspace (.ssw file) that demonstrates the use of script execution with STRIDE Studio to manage the test order and hierarchy. The setup and teardown folders provide basic infrastructure scripts that start and stop the simulator application (SCL_Samples.exe). The scripts that drive the testing are in the workspace test folder. The subfolders under test follow the same structure as the header files under Source Files. They each contain scripts that exercise the interfaces built with the corresponding SCL pragmas.
The scripts implement the User side, initiating the function calls, and providing traceview processing to verify the results and generate reports. The Owner side of these functions are implemented in the target application, in the ".c" files that correspond to the header files containing the SCL pragmas in the sample workspace. Note: these ".c" files are part of the Visual Studio project, you may view these files in Visual Studio, or you may locate them on disk in the same directory as the sample header files, under the Tests directory under the installed sample directory.

A particular point of interest is in the implementation of the sample functions for the scl_ptr and scl_ptr_sized pragmas. The f2_ptr_override and f2_ptr_sized_return functions show how RETURN/PRIVATE block memory is allocated. The f1_ptr_sized_double shows how RETURN/POOL memory should be allocated by using the palMemAlloc API of the STRIDE Runtime.