Studio:Intercept Module Sample

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

Introduction

The following content relates to the sample files and workspaces installed in %STRIDE_DIR%\Samples\InterceptModule. This sample consists of a Visual Studio workspace for building a Windows Off-Target App, sample Intercept Module (IM) source code, and a STRIDE workspace for doing more advanced test 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.

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 a Windows Off-Target App that incorporates the sample source code.

Once the build is complete you can open the STRIDE workspace file and run all scripts using the button. The focus of this example is on the source code instrumentation and intercept module settings, both of which are most easily viewed in the Visual Studio workspace. The STRIDE workspace provides a means to execute some function call sequences to demonstrate that the call routing via the STRIDE runtime indeed works.

Sample Tests

Now that you have built the Windows Off-Target App and executed the tests it contains, you can take time to peruse the Visual Studio project source and settings. This section provides a brief description for the topics covered by this sample workspace. This project is organized in the following foldders:

Main

contains the application entry point and the generated Intercept Module source file.

Settings

contains a text file with the Intercept options that are used by the project. This file is passed to the s2sinstrument tool as part of the STRIDE build rules.

Source

contains the application code that we have instrumented so as to illustrate the IM concepts outlined below.

Stub

Illustrates creation of a Stub Intercept Module (IM), which is required to be included in the target build to call a function on the target platform from the host.

Proxy

Demonstrates creation of a Proxy Intercept Module (IM), which is required to be included in the target build to call a function on the host platform from a function on the target.

Delegate User Implicit

Illustrates creation of a Delegate User Implicit Intercept Module (IM), which is required to be included in the target build to trace on a user (calling) function with implicit name mangling that resides wholly on the target.

Delegate User Explicit

Illustrates creation of a Delegate User Explicit Intercept Module (IM), which is required to be included in the target build to trace on a user (calling) function with explicit name mangling that resides wholly on the target.

Delegate Owner Implicit

Illustrates creation of a Delegate Owner Implicit Intercept Module (IM), which is required to be included in the target build to trace on a owner (called) function with implicit name mangling that resides wholly on the target.

Delegate Owner Explicit

Illustrates creation of a Delegate Owner Explicit Intercept Module (IM), which is required to be included in the target build to trace on a owner (called) function with name mangling that resides wholly on the target.

Delegate Dynamic

Illustrates creation of a Delegate Dynamic Intercept Module (IM), which is required to be included in the target build to transparently route calls to either a target-based or host-based implementation of a function.

Test Execution

This sample demonstrates two different techniques for executing tests.

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 InterceptModule.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:\STRIDE\Samples\InterceptModule/InterceptModule.ssw..
 excluding folder setup in workspace C:\STRIDE\Samples\InterceptModule/InterceptModule.ssw
 running folder test in workspace C:\STRIDE\Samples\InterceptModule/InterceptModule.ssw
 excluding folder teardown in workspace C:\STRIDE\Samples\InterceptModule/InterceptModule.ssw
 Test results written to C:\STRIDE\Samples\InterceptModule\InterceptModule.html
 ***************************************************************************
 Results Summary
 ***************************************************************************
   Passed:              13
   Failed:               0
   In Progress:          0
   Not Applicable:       0
   ...in 9 suites.
 ***************************************************************************

Workspace-Based Execution

When opened with STRIDE Studio the sample STRIDE workspace (.ssw) a user could manage test order and hierarchy. The setup and teardown folders provide basic infrastructure scripts that start and stop the simulator application, InterceptModule.exe. The scripts that drive the testing are in the workspace test folder. What follows is a brief description for each.

Stub

This folder contains a script that demonstrates how to make a host call to an IM generated function stub.

Proxy

This folder contains scripts that demonstrate how to make the IM generated function proxy to call the host.

DelegateUserImplicit

This folder contains a script that demonstrates how to make a host call to an IM generated function delegate user with implicitly mangled name.

DelegateUserExplicit

This folder contains a script that demonstrates how to make a host call to an IM generated function delegate user with explicitly mangled name.

DelegateOwnerImplicit

This folder contains a script that demonstrates how to make a host call to an IM generated function delegate owner with implicitly mangled name.

DelegateOwnerExplicit

This folder contains a script that demonstrates how to make a host call to an IM generated function delegate owner with explicitly mangled name.

DelegateDynamic

This folder contains a script that demonstrates how to make a host call to an IM generated dynamic function delegate.