S2sinstrument

From STRIDE Wiki
Jump to navigation Jump to search

The STRIDE Instrumentation Utility

The s2sinstrument executable generates instrumentation code, also known as IM, or Intercept Module code. It is a command line utility that accepts the following input:

  • database (.sidb) file (output from s2sbind)
  • intercept module name
  • C/C++ code files, output location and C header files output location
  • a set of configuration options

The resulting output files will be generated:

  • a prototype header file <im_name>IM.h
  • implementation files <im_name>IM.c(pp) and <im_name>IMEmtry.h
  • a read-me file <im_name>IMReadMe.txt.

Syntax

   s2sinstrument [options] database_file

Options

Option Description
--version Print version information.
--im_name=<string> The intercept module name. The default is the base name of the database file.
--im_suffix=<string> The intercept module file name suffix. The default is "IM".
--code_output=<path> The location of the generated C or C++ files. The default is the current directory.
--header_output=<path> The location of the generated header files and text (read me) file. The default is the current directory.
--strip_path When present, the path information from include directives will be striped.
--disable_access_class When present, all interface SUIDs will be explicitly registered instead of using access class registration. When generating multiple simultaneously running intercept modules, all (with the exception of one) must have that option specified.
--suppress_exception_handling When present, C++ exceptions would not be handled as errors.
--prototype=<tag> Generate only prototype header files. <tag> is a unique tag that would be appended to the prototype header file name.
--implement Generate only implementation files.
--default_mode=<mode> Optional. When present, sets the default generation mode. If not present the <mode> is assumed to be "I" for intercept-able functions (see scl_function for details) and "S" for all others.

The format of the <mode> is "SPI[T]", where:
"S" – stub
"P" – proxy
"I" – interceptor (requires scl_function interception attributes)
"T" – tracer (valid only with "I")
To set the default mode to NOP (do nothing) set its value to #.

Allowed combinations are:

MeaningSPIT
Remote invocation (aka Stub) x    
Remote call forwarding (aka Proxy)  x   
Local interception (aka Interceptor)    x 
Local and remote (formal Dynamic Delegate) interception  x x 
Local and trace (formal Trace Delegate) interception    xx
All types of interception  x xx
Remote invocation in combination with any type of interception (the above 4) xx xx

NOTE: The use of the previously defined mode format, "SPD[oued]"[#<group_id>], has been depricated in favor of the new "SPI[T]" in combination with the new scl_function interception attributes.

--mode=<mode>(<interface>[,<interface>…]) Interface specific generation mode. The <mode> is the same as above. The <interface> is an interface name.

This option could be repeated as many times as needed. It overrides any --default_mode option otherwise in effect.
To set the mode for a set of functions to NOP (do nothing) set <mode> to empty.

Example: Generate proxy for functions f1 and f2

 --mode=P(f1,f2)
--options_file=<file> A file that contains command line options. The format is the same as the command line with the only addition that it could be split on multiple lines. A line starting with "#" symbol is ignored.

This option is necessary if the length of the command line string exceeds system limits. Otherwise it is provided only as a convenience.

Examples

Refer to the Intercept Module Generation section of the Build Tools Examples.