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

The following prerequisites must be satisfied (see Host Installation for more info) before starting:

• 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. When run, a simple test report will be produced with a single Passed test and no failures. Although this example produces a report, the focus of it 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 folders, as described in the following sections. The section names match the project folder being described.

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. we have chosen to name this file stride.s2sinstrument to make clear that it applies the the s2sinstrument tool, but the name is not required by the tools (any basename and suffix are allowed).

Source

Contains the application code that we have instrumented so as to illustrate the IM concepts outlined below. The following sub-folders present several IM related concepts. For each of these samples, refer to the stride.s2sinstrument settings file to see the corresponding tool settings that are required to properly generate the IM code.

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.

Workspace Execution

The sample STRIDE workspace contains a few basic scripts that drive the execution of the interfaces in the sample application. The workspace is of little interest other than verifying that the interfaces can be called and invoke the proper proxies and delegates.