Studio:Intercept Module Sample: Difference between revisions

From STRIDE Wiki
Jump to navigation Jump to search
(New page: '''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 ...)
 
No edit summary
Line 23: Line 23:
==Sample Tests==
==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:
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.


; Main : contains the application entry point and the generated Intercept Module source file.
===Main===
; 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 [[Windows_Off-Target_SDK#Instructions_for_Microsoft_Visual_Studio|STRIDE build rules]].
; Source : contains the application code that we have instrumented so as to illustrate the IM concepts outlined below.


===Stub===
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 [[Windows_Off-Target_SDK#Instructions_for_Microsoft_Visual_Studio|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 [[Intercept Module#Stub|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.
Illustrates creation of a [[Intercept Module#Stub|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===
====Proxy====


Demonstrates creation of a [[Intercept Module#Proxy|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.  
Demonstrates creation of a [[Intercept Module#Proxy|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===
====Delegate User Implicit====


Illustrates creation of a [[Intercept Module#Delegate|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|name mangling]] that resides wholly on the target.
Illustrates creation of a [[Intercept Module#Delegate|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|name mangling]] that resides wholly on the target.


===Delegate User Explicit===
====Delegate User Explicit====


Illustrates creation of a [[Intercept Module#Delegate|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|name mangling]] that resides wholly on the target.
Illustrates creation of a [[Intercept Module#Delegate|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|name mangling]] that resides wholly on the target.


===Delegate Owner Implicit===
====Delegate Owner Implicit====


Illustrates creation of a [[Intercept Module#Delegate|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|name mangling]] that resides wholly on the target.
Illustrates creation of a [[Intercept Module#Delegate|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|name mangling]] that resides wholly on the target.


===Delegate Owner Explicit===
====Delegate Owner Explicit====


Illustrates creation of a [[Intercept Module#Delegate|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|name mangling]] that resides wholly on the target.
Illustrates creation of a [[Intercept Module#Delegate|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|name mangling]] that resides wholly on the target.


===Delegate Dynamic===
====Delegate Dynamic====


Illustrates creation of a [[Intercept Module#Delegate|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.  
Illustrates creation of a [[Intercept Module#Delegate|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==
==Workspace 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.pl|WorkspaceRun utility]]. Here is an example of specific syntax to execute a test workspace. All of these commands can be invoked from a standard [http://en.wikipedia.org/wiki/Command_Prompt_(Windows) 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.
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.


====DelegateDynamic====


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




[[Category: Samples]]
[[Category: Samples]]

Revision as of 19:03, 3 October 2008

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 Run all.gif 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 folders, as described in the following sections.

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.