Difference between revisions of "Studio:Integrating the Intercept Module (IM)"

From STRIDE Wiki
Jump to: navigation, search
(→‎IM Files and how they are used)
(→‎IM Resource Requirements)
 
(46 intermediate revisions by 7 users not shown)
Line 1: Line 1:
−
== IM Files and how they are used ==
+
== About Intercept Modules ==
−
The Intercept Module is generated by STRIDE Studio for the specific set of function interfaces you select. Three files are created, differing only by their ending:
+
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. The [[Intercept Module|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 Intercept Module source file (IM.c / IM.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 (IM.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 <tt>#include</tt>'d in the source.  Also, it is only required if the C file uses Delegates.  Stubs and Proxy functions do not need this file.
 
−
* The IM Entry point header file (IMEntry.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.
 
  
−
These filenames are all prepended by the name you give the IM when it is generated.  For example, if you call the IM "MyProject", then the resulting filenames will be "MyProjectIM.c", "MyProjectIM.h", and "MyProjectIMEntry.h".
 
  
−
== Adding the IM files to the build ==
 
−
== IM Resource Requirements ==
 
−
* Stack size
 
−
* Threads
 
  
−
== Configuring and generating an Intercept Module ==
+
== Activating the Intercept Module ==
−
You can either generate the IM via STRIDE Studio’s Intercept Module Wizard, or you can utilize scripts to automatically configure and generate the IM files. These files will contain Studio-based configuration definitions. In addition, the script used for configuration will denote in which context the IM runtime functions are to be executed.
+
=== Compiling the IM ===
 +
To compile the IM, you must define the '''STRIDE_ENABLED''' (or '''srIMON''' in 3.0.01xx or older releases) preprocessor directive when you compile the IM.c file or any file that includes one of the headers. This "turns on" the intercept feature. For example:
 +
  cc -c -IC:\STRIDE\inc -DSTRIDE_ENABLED=1 MyProjectIM.c
  
−
The script can execute automatically so that the Intercept Module is built as part of the test automation framework, as shown in the following example. The IM generation script should open a Studio workspace, optionally compile the workspace and save the database (if needed), then configure and create the IM as shown in the following Perl example:
+
Notice that the IM.c and IMEntry.h files reference header files in the STRIDE installation directory. The build must include this directory when compiling either of these files. The public interface (IM.h) header file does not have any dependencies on this directory.
−
 
 
−
  # Compile and save the workspace database
 
−
  $main::studio->Workspace->CompileAll();
 
−
  $main::studio->Workspace->Save();
 
−
 
 
−
  # Intercept Module (IM) name and path constants
 
−
  my $IM_FILE_NAME = "stride";
 
−
  my $IM_LOCATION_PATH = $main::studio->Workspace->Path;
 
−
 
 
−
  # Create a reference to the workspace IM object
 
−
  my $IM = $main::studio->Workspace->Intercept;
 
−
 
 
−
  # Local variables
 
−
  my ($i, $fx);
 
−
 
 
−
  # Reset all of the IM configuration settings to off and
 
−
  # reset the delegate group Id's to their default name.
 
−
  $IM->Reset();
 
−
 
 
−
  # Setup the IM name and path
 
−
  $IM->{Name} = $IM_FILE_NAME;
 
−
  $IM->{Path} = $IM_LOCATION_PATH;
 
−
 
 
−
  # For each interface in the IM collection
 
−
  for ($i=0; $i < $IM->Count(); $i++)
 
−
  {
 
−
      # reference the ith interface;
 
−
      $fx = $IM->Item($i);
 
−
 
 
−
      $fx->{Stub} = 1;              # configure as stub
 
−
                                    # and delegate
 
−
      $fx->Delegate->{Owner} = 1;    # mangle from owner's perspective
 
−
      $fx->Delegate->{Explicit} = 1; # implicit name mangling
 
−
      $fx->Delegate->{Dynamic} = 1;  # enable dynamic interception
 
−
  }                               
 
−
 
 
−
  # Create IM files.
 
−
  $IM->Create();
 
−
 
−
The resulting Intercept Module file is then compiled and built with the rest of your target code.
 
  
−
== Starting the IMStubRead thread ==
+
=== IM Resource Requirements ===
 +
The Intercept Module is usually run as a separate task, and therefore has some
 +
resource requirements that are in addition to those of the [[Runtime Integration|STRIDE Runtime]]. One of these is the task resource itself.  Another is space for the task stack.
  
−
[[Category:Deploying STRIDE]]
+
The required task stack size if difficult to predict since it is dependent on the underlying system and on the data that is passed through function arguments.  A stack size between 2-4K would be a good starting point.
 +
 
 +
=== Starting the IMStubRead threads ===
 +
The IM must be started ''after'' the Runtime and Transport have been initialized, but before any intercepted calls can be made.  Failure to do this before making an intercepted call can crash or hang the target.
 +
 
 +
Look at any of the prepackaged [[:Category:SDKs|SDKs]] for examples of integrating your application.
 +
 
 +
[[Category:Studio:Installation]]

Latest revision as of 17:00, 19 May 2010

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. 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.


Activating the Intercept Module

Compiling the IM

To compile the IM, you must define the STRIDE_ENABLED (or srIMON in 3.0.01xx or older releases) preprocessor directive when you compile the IM.c file or any file that includes one of the headers. This "turns on" the intercept feature. For example: 

 cc -c -IC:\STRIDE\inc -DSTRIDE_ENABLED=1 MyProjectIM.c

Notice that the IM.c and IMEntry.h files reference header files in the STRIDE installation directory. The build must include this directory when compiling either of these files. The public interface (IM.h) header file does not have any dependencies on this directory.

IM Resource Requirements

The Intercept Module is usually run as a separate task, and therefore has some resource requirements that are in addition to those of the STRIDE Runtime. One of these is the task resource itself. Another is space for the task stack.

The required task stack size if difficult to predict since it is dependent on the underlying system and on the data that is passed through function arguments. A stack size between 2-4K would be a good starting point.

Starting the IMStubRead threads

The IM must be started after the Runtime and Transport have been initialized, but before any intercepted calls can be made. Failure to do this before making an intercepted call can crash or hang the target.

Look at any of the prepackaged SDKs for examples of integrating your application.

Retrieved from "https://www.stridewiki.com/index.php?title=Studio:Integrating_the_Intercept_Module_(IM)&oldid=12474"