Intercept Module

About Intercept Modules

Intercept Modules allow remote function calls across hardware (e.g., processor or machine) or software (operating system) platform boundaries. Intercept Modules are target-based components that are created as a step in the STRIDE build process (see the Build Tools page). The Intercept Module, or IM, is created based on selected interfaces or test units that have been "captured", or identified through a subset of SCL pragmas that tag interfaces as candidates for remote function calls. Once created, the generated code is then compiled, linked and run along with the target application.

The s2sinstrument.exe program, or alternatively, the Intercept Module Wizard in Studio generate the code for an intercept module for selected functions or test units. Generation can be tailored to include different instrumentation details for each function.

Three files are created, each prepended with the name of the Intercept Module that you gave it when it was created:

• The Intercept Module source file (imnameIM.c or imnameIM.cpp)
  This file contains the code that allows the remoting of functions so that they can be accessed by the Target and Host.
• The Delegate Mangling header file (imnameIM.h)
  This file must be included in all of your C files that are using Delegates (Dynamic or Tracing). It contains macros that will mangle the appropriate function names so that they can be intercepted and routed through the IM. When used, it must be the last file #include'd in the source. Also, it is only required if the C file uses Delegates. Stubs and Proxy functions do not require this file
• The IM Entry point header file (imnameIMEntry.h)
  This file contains the prototypes for the external entry points into the IM. It is needed only by the function that starts the IM Stub Read Thread.

The following examples describe integration and testing situations that would require generation of one or more intercept modules:

• To call a function on the target platform from the host, you must generate an intercept module containing a stub and include it in the target build.
• To call a function on the host platform from a function on the target, you must generate an intercept module containing a proxy and include it in the target build.
• To trace on that function resides wholly on the target (e.g., both the called and the calling functions are co-located on the target platform), you must generate an intercept module containing a tracing delegate and include it in the target build.
• To be able to dynamically "move" a function back and forth between host and target platforms during integration and testing without rebuilding the target application, you must generate an intercept module containing a dynamic delegate and include it in the target build.
  

Stubs, Proxies, and Delegates

Stub

A stub is required in order to call a function, f(), on the target from the host.

The stub performs two main tasks:

• Provides a handler for incoming host invocations and transparently converts them into local calls to f().
• Captures the return and output values of the local call and transmits them back to the host.

When a proxy and a stub exist for a given function, the stub is never on the same platform as the proxy.

Proxy

A proxy is required in order to transparently intercept a target call to a function, f(), and remote the call to a host implementation of f().

The proxy performs two main tasks:

• Intercepts local calls to f() and transfers the call, along with parameter data, to the host implementation.
• Captures the host response containing return values and output data, and transparently returns the information to the local caller.
  

When a proxy and a stub exist for a given function, the stub is never on the same platform as a proxy. When more than one proxy exists for a given function, each proxy must be located on a different platform.

Note: A stub and a proxy cannot simultaneously coexist for the same function. Only one can be used for any given test configuration.

Delegate

A delegate is a specialized type of proxy. A delegate can perform the following tasks:

• Transparently trace all calls to a method, f(), whose implementation resides on the target. All calls and parameter data can be captured and recorded. This type of delegate is called a Tracing Delegate.
• Transparently route calls to either a target- or host-based implementation of f(). This routing is dynamic and controlled by the host. This type of delegate is called a Dynamic Delegate.

A Tracing Delegate intercepts calls to f() and records tracing information such as time, input parameters, etc. before passing control to the local implementation of f(). Upon the return from f(), the delegate again records tracing information before passing control back to the caller. The delegate inserts itself between the caller and the callee in order to capture tracing information.

A Dynamic Delegate inserts itself between the caller and the callee in the same way as a Tracing Delegate, but its logic is different. In addition to recording tracing information, it contains logic to check certain state information to determine whether to route the call to a host implementation (and override the owner) of f(), or to allow the call to proceed to the local implementation (owner) of f().

Note: A Dynamic Delegate is always a Tracing Delegate, but depending upon instructions you give the Intercept Module Wizard, a Tracing Delegate may or may not be a Dynamic Delegate.

Implicit/Explicit

A delegate may have either implicit or explicit mangling incorporated into it. By default, implicit mangling is used; this means that selected routines will be mangled using a Group ID. If explicit mangling is used, you must explicitly mangle selected routines using the explicit macro (imDELEGATE(fn)).