Test Point Testing in C/C++

2009-10-06T21:02:39Z

Stevel: /* srTestPointExpect */

Test Point Testing in C/C++

2009-10-06T21:02:21Z

Stevel: /* Instrumenting Test Code */

2009-03-20T22:17:13Z

Stevel: /* Test Spaces */

STRIDE 3.0.02xx

2009-03-20T22:15:08Z

Stevel: /* Test Spaces */

STRIDE 3.0.02xx

2009-03-20T22:14:34Z

Stevel: /* Usability Improvements */

2009-02-12T19:00:19Z

Stevel: /* Creating Double Intercepts in the IM */

==Introduction==
The ''Function Double'' feature provides a means for intercepting C language functions on the target, and directing the call to a substitute function with identical parameters and return value. The use case is a unit test where the function under test uses a ("C") function during its execution, and this dependency is simulated by a substitute or double function during testing. The unit test is able to control the substitution of the dependency during run time, and thereby verify the behavior of the function under test.
The following sample illustrates the relationship of the function under test and a dependency:

<source lang="c">
// depend.h
int depend(int x);
</source>

<source lang="c">
// depend.c
#include "depend.h"

int depend(int x)
{
return x + x;
}
</source>

<source lang="c">
// test.h
int test(int x, int y);
</source>

<source lang="c">
// test.c
#include "test.h"
#include "depend.h"

int test(int x, int y)
{
return depend(x) * y;
}
</source>

In the above sample, test() is the function under test and depend() is a dependency candidate for doubling.

The steps required to achieve doubling of a dependency function are as follows:
#[[#Configuring_the_Double_Using_SCL|Configure the double parameters using SCL pragmas]]
#[[#Creating_Double_Intercepts_in_the_IM|Create the double intercepts in the IM]]
#[[#Switching_the_Double_Function_During_Runtime|Switch to/from the double function during runtime]]

==Configuring the Double Using SCL==

The syntax of the [[Scl_func|scl_func]] and [[Scl_function|scl_function]] pragmas have been expanded to include new '''''optional''''' attributes that allow the specification of function interception parameters. If these options are omitted, then the function is not a candidate for doubling.

#pragma scl_function(function-name [,<intercept>])
#pragma scl_func(SUID, function-name [,<intercept>])

<intercept> = <context>, <name_mangling>, <group_id>
<context> = “REFERENCE” | “DEFINITION” (case insensitive)
<name_mangling> = “EXPLICIT” | “IMPLICIT” (case insensitive)
<group_id> = [user defined identifier] (i.e. “^[A-Za-z_]\w*$”)

===Context Option===
The <context> option in the syntax guide above allows either the '''"REFERENCE"''' or '''"DEFINITION"''' strings. A "REFERENCE" context means the intercept is made at the function call, i.e., the intercept function is called instead of the dependency. A "DEFINITION" context means that the intercept is made at the function definition, i.e., the intercept function name is equivalent to the dependency name, and and is called in place of the dependency. These options are equivalent to the [[Intercept_Module#Owner.2FUser|user and owner delegate options]] that are in place for generating [[Intercept_Module#Delegate|delegates]].

===Mangling Option===
The <name_mangling> option above allows either the '''"EXPLICIT"''' or '''"IMPLICIT"''' strings. These settings are used to solve [[Name_Mangling#Name_Mangling_Conflicts|name mangling conflicts]] within your target source. "EXPLICIT" mangling requires the use of the "'''imINTERCEPT('''<function_name>''')'''" macro, which explicitly mangles the name of "f()" to "__im_f()". This macro is defined in the generated Intercept Module delegate mangling header file (xxxIM.h). Explicit mangling requires [[Intercept Module#Group ID|Group ID(s)]] to be defined (#define MyGroupID) in the source file of the caller/callee of the routine to protect against the inclusion of unnecessary defined types. "IMPLICIT" mangling performs no mangling, and requires none of these steps.

===Group ID Option===
As described in the above mangling option section, a [[Intercept Module#Group ID|Group ID]] is required for EXPLICIT mangling. The <group_id> string is specified in the pragma as shown. The Group ID(s) must be defined your source before including the Intercept Module delegate mangling header file (xxxIM.h). Please refer to an example of when and how this is done [[Name_Mangling#Mangling_Conflict_Example_2:_Two_users_of_a_routine.2C_f.28.29.2C_exist_in_the_same_source_file.2C_but_only_one_is_a_user_delegate|here]].

===Dependency Interception===
In the above sample, depend() needs to be SCL captured and enabled for interception in a matter to be doubled.

<source lang="c">
// depend_scl.h
#include "depend.h"

#pragma scl_function(depend, "DEFINITION", "IMPLICIT", "TEST_GROUP")
</source>

==Creating Double Intercepts in the IM==
If a function has been configured as a double candidate using SCL as outlined in the above step, then the next step is to compile and bind using [[Build_Tools|STRIDE build tools]] and create the IM that contains the intercept for the double function. The options to [[S2sinstrument|s2sinstrument]] have been updated to support the function double feature as follows:

{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Option'''
| '''Change'''
| '''Notes'''
|-
| '''--default_mode'''=<mode>[#<group_id>]
| Deprecated
| Use the new format below.
|-
| '''--default_mode'''=<mode>
| New
| Optional. When present, sets the default generation mode. If not present the <mode> is assumed to be “I” for intercept-able functions and “S” for all others. 
The format of the <mode> is "SPI[T]", where: 
“S” – stub 
“P” – proxy 
“I” – intercept 
“T” – trace
|-
| '''--mode'''=<mode>[#<group_id>] (<interface>[,<interface>…])
| Deprecated
| Use the new format below.
|-
| '''--mode'''=<mode>(<interface>[,<interface>…])
| New
| 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.
|}

Where the allowed mode combinations are:
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''S'''
| '''P'''
| '''I'''
| '''T'''
| '''Notes'''
|-
| X
|
|
|
| Generate Stub
|-
|
| X
|
|
| Generate Proxy
|-
|
|
| X
|
| Generate Intercept for a Function Double (see '''''Note''''' below)
|-
|
| X
| X
|
| Generate Intercept for Dynamic Delegate
|-
|
|
| X
| X
| Generate Intercept for Trace Delegate
|-
|
| X
| X
| X
| Generate Intercept for a Dynamic Delegate with Tracing
|}

'''''Note:''''' Currently the only option that supports Function Doubles is the "I" option ''by itself''. Any other option combinations will not allow the double substitution at run-time as outlined in the next step. Also note that the absence of any options will default to the "I" option alone per interface.

Once the IM is successfully created alter the source file containing the depend() implementation by incluting the generated strideIM.h:

<source lang="c">
// depend.c
#include "depend.h"
/* include this */
#define TEST_GROUP
#include "strideIM.h"

int depend(int x)
{
return x + x;
}
</source>

==Switching the Double Function During Runtime==
The test unit will have access to the following STRIDE runtime macros for substituting a stub function for a double candidate.

<source lang="c">
srDOUBLE_GET(fn, pfnDbl)
srDOUBLE_SET(fn, fnDbl)
</source>

Where:
*'''fn''' is the function qualified by scl_function or scl_func as a dependency candidate, as above.
*'''pfnFbl''' is a pointer to a object of type srFnDbl_t, declared to hold the current value of the active double function.
*'''fnDbl''' is a function that is to be the current active double. ''The function passed in should '''always''' match the signature of the dependency candidate specified by '''fn'''.''
'''''Note:''''' the initial value of the current active double is always the dependency candidate function.

These macros are defined in the STRIDE runtime header file '''sr.h'''. The following example shows how they are used in a [[Test_Units#C.2B.2B_Test_Classes|C++ test unit]]:

<source lang="cpp">
#include <srtest.h>

extern "C" int depend_dbl(int a) { return a * a; }

class Test: public stride::srTest
{
public:

Test()
{
srDOUBLE_GET(depend, &m_depend_dbl);
srDOUBLE_SET(depend, depend_dbl);
}

~Test()
{
srDOUBLE_SET(depend, m_depend_dbl);
}

int test1(void) { return test(1, 2); }
int test2(void) { return test(5, 6); }

private:
srFnDbl_t m_depend_dbl;
};

#ifdef _SCL
#pragma scl_test_class(Test)
#endif
</source>

[[Category: Reference]]