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 executable, 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 a function that completely resides 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

Target instrumentation is handled via stubs, proxies, and delegates, each of which provide distinct functionality.

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.

Owner/User

To insert a delegate between a user (calling) function and owner (called) function, you must choose how function name mangling will be handled. Name mangling describes the automatic source transformation required for a delegate to insert itself between caller and callee. There are two options for handling name mangling, one of which must be chosen when using delegates:

1. A call to a function f() is transformed to "__imf()” to allow the delegate to intercept the call. This is referred to as user mangling.
2. The implemention of f() can be transformed to "__imf()”. This is referred to as owner mangling.
   

See the Understanding Name Mangling page for a detailed explanation of name mangling and how it is used.

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(<function_name>)". For detailed information about implicit and explicit mangling, including examples, click here.

Group ID

A Group ID assigns a special symbolic constant, declared in the Intercept Module delegate mangling header file (xxxIM.h), that can be used by the preprocessor to mangle a subset of routines; successful use of Group ID(s) assumes that each source file (e.g., FuncA.c and FuncB.c) has its own header file (e.g., FuncA.h and FuncB.h). A Group ID can be defined within the source file or defined as a compiler input parameter. The default Group ID(s) used by the s2sinstrument executable or the Intercept Module Wizard in Studio can be overridden with your own Group ID(s). Name mangling conflicts can be resolved using the Group ID(s).

See also

• Understanding Name Mangling
• Integrating the Intercept Module (IM) for directions on how to generate an IM and add it to your target build
• Using s2sinstrument to generate an Intercept Module