Difference between revisions of "Scl function"

From STRIDE Wiki
Jump to: navigation, search
(→‎The scl_function pragma)
(→‎Syntax)
 
(17 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
= The scl_function pragma =
+
__NOTOC__
 +
The ''SCL function'' pragma allows capturing a global function for doubling or remoting. During the build process the [[Build Tools | Stride Build Tools]] generates [[Intercept Module]] that provides the correct logic for the test. 
  
−
The scl_function pragma allows the user to capture the function. All interfaces that STRIDE works with must be captured.
+
<source lang=c>
 +
int foo(int x);
  
−
When captured for the purpose of interception (in which case the term '''intercept-able''' is used throught the documentation) optional arguments allow specification of how would it be done. The [[s2sinstrument|Instrument Build Tool]] will use those options to generate appropriate function interception code.
+
void boo(void);
  
−
== Syntax ==
+
#pragma scl_function(foo)
 +
#pragma scl_function(boo, "DEFINITION", "IMPLICIT", "TEST_GROUP")
 +
</source>
 +
 
 +
=== Syntax ===
 +
The ''scl_function'' pragma allows the user to capture a function. When captured for the purpose of interception ('''intercept-able''') the optional arguments are used to specify how the intercept should be executed. The [[s2sinstrument|Instrument Build Tool]] will use those options to generate appropriate function interception code.
  
 
  #pragma scl_function(function-name [,context, name-mangling, group-id])
 
  #pragma scl_function(function-name [,context, name-mangling, group-id])
Line 16: Line 23:
 
|-
 
|-
 
| ''function-name''
 
| ''function-name''
−
| String
+
| Identifier
−
| Name of the function to define (no quotes)
+
| Name of the function to capture.
 
|-
 
|-
 
| ''context''
 
| ''context''
 
| String
 
| String
−
| Optional. Context in which the function is going to be intercepted. Possible values are ''"REFERENCE"'' - intercept at the function call or ''"DEFINITION"'' - intercept at the function definition. These attribute is equivalent to the formal [[Intercept_Module#Owner.2FUser|User/Owner option]] that is in place for generating [[Intercept_Module#Delegate|delegates]].
+
| Optional. Context in which the function is going to be intercepted. Possible values are ''"REFERENCE"'' - intercept at the function call (i.e. where the function is called) or ''"DEFINITION"'' - intercept at the function definition (i.e. where the function is implemented).
 
|-
 
|-
 
| ''name-mangling''
 
| ''name-mangling''
 
| String
 
| String
−
| Optional. Type of [[Name_Mangling|name mangling]] to be used when intercepted. Possible values are ''"EXPLICIT"'' or ''"IMPLICIT"''. These attribute is equivalent to the formal [[Intercept_Module#Implicit.2FExplicit|Implicit/Explicit
+
| Optional. Type of [[Name_Mangling|name mangling]] to be used when intercepted. Possible values are ''"EXPLICIT"'' or ''"IMPLICIT"''. If the ''context'' argument is defined the default will be '''IMPLICIT'''. Note that if '''EXPLICIT''' is set the '''srTEST_INTERCEPT('''<function_name>''')''' macro is required.  
−
option]] that is in place for generating delegates.
 
 
|-
 
|-
 
| ''group-id''
 
| ''group-id''
 
| String
 
| String
−
| Optional. User defined identifier representing the group to which this function belongs when solving name mangling conflicts. These attribute is equivalent to the formal [[Intercept_Module#Group_ID|Group ID
+
| Optional. User defined identifier representing the group to which this function belongs when enabling interception. The default ''group-id'' is set to '''STRIDE_TEST_GROUP'''.  
−
option]] that is in place for generating delegates.
 
 
|}
 
|}
  
−
== Notes ==
+
=== Notes ===
−
* Identifier must be declared as a function designator with external linkage.  
+
* The function must be declared as a designator with external linkage.  
−
* A compilation error is reported if an attempt is made to capture a function more than once (with either scl_func or scl_function).
+
* A compilation error is reported if an attempt is made to capture a function more than once.
  
−
== Example ==
+
=== Examples ===
 +
Using the default "IMPLICIT" ''name-mangling'' and "STRIDE_TEST_GROUP" ''group-id''
 
<source lang=c>
 
<source lang=c>
−
int f(int x);  
+
void boo(void);
  
−
void g(void);
+
#pragma scl_function(boo, "DEFINITION")
 +
</source>
  
−
#pragma scl_function(f)
+
 
−
#pragma scl_function(g, "DEFINITION", "IMPLICIT", "TEST_GROUP")
+
Setting a specific ''name-mangling'' and ''group-id''
 +
<source lang=c>
 +
void boo(void);
 +
 
 +
#pragma scl_function(boo, "DEFINITION", "IMPLICIT", "MY_TEST_GROUP")
 
</source>
 
</source>
−
 
−
[[Category: Functions]]
 
−
[[Category: SCL]]
 

Latest revision as of 16:20, 29 September 2015

The SCL function pragma allows capturing a global function for doubling or remoting. During the build process the Stride Build Tools generates Intercept Module that provides the correct logic for the test. 

int foo(int x); 

void boo(void);

#pragma scl_function(foo)
#pragma scl_function(boo, "DEFINITION", "IMPLICIT", "TEST_GROUP")

Syntax

The scl_function pragma allows the user to capture a function. When captured for the purpose of interception (intercept-able) the optional arguments are used to specify how the intercept should be executed. The Instrument Build Tool will use those options to generate appropriate function interception code. 

#pragma scl_function(function-name [,context, name-mangling, group-id])


Parameters Type Description
function-name Identifier Name of the function to capture.
context String Optional. Context in which the function is going to be intercepted. Possible values are "REFERENCE" - intercept at the function call (i.e. where the function is called) or "DEFINITION" - intercept at the function definition (i.e. where the function is implemented).
name-mangling String Optional. Type of name mangling to be used when intercepted. Possible values are "EXPLICIT" or "IMPLICIT". If the context argument is defined the default will be IMPLICIT. Note that if EXPLICIT is set the srTEST_INTERCEPT(<function_name>) macro is required.
group-id String Optional. User defined identifier representing the group to which this function belongs when enabling interception. The default group-id is set to STRIDE_TEST_GROUP.

Notes

  • The function must be declared as a designator with external linkage.
  • A compilation error is reported if an attempt is made to capture a function more than once.

Examples

Using the default "IMPLICIT" name-mangling and "STRIDE_TEST_GROUP" group-id 

void boo(void);

#pragma scl_function(boo, "DEFINITION")


Setting a specific name-mangling and group-id 

void boo(void);

#pragma scl_function(boo, "DEFINITION", "IMPLICIT", "MY_TEST_GROUP")
Retrieved from "https://www.stridewiki.com/index.php?title=Scl_function&oldid=14662"