Difference between revisions of "Pragmas"

From STRIDE Wiki
Jump to: navigation, search
Line 126: Line 126:
 
#pragma scl_function(func)
 
#pragma scl_function(func)
 
</source>
 
</source>
 +
 +
 +
= scl_conform =
 +
The scl_conform pragma allows the user to define a conformant array within a payload. The payload can be a C structure or a parameter declaration list. The conformant array must be the last item in the payload (e.g., the last field in the structure, or the last parameter in the declaration list). Because of this, only the payload name and the name of the size field in that payload are required. The SCL compiler automatically assumes the conformant array field within the specified payload.
 +
 +
NOTE: ''For an alternative use case of sized structure please look at [[scl_struct_sized]] pragma.''
 +
 +
=== Syntax ===
 +
#pragma scl_conform(name, size-name, max-size)
 +
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;" 
 +
| '''Parameters'''
 +
| '''Type'''
 +
| '''Description'''
 +
|-
 +
| ''name''
 +
| String
 +
| Name of the structure or function that encapsulates the conformant array
 +
The following restrictions apply:
 +
* The structure type may not be pointed to by a sized pointer.
 +
* The structure type may not be used in an array.
 +
* The structure type may not be a member of an union.
 +
* The structure type may not be a member of any other structure unless it is the last member.
 +
* The structure type may not be passed as a formal parameter or return value of a function (but a pointer to it is allowed).
 +
* The structure type cannot reside within OUT memory block.
 +
|-
 +
| ''size-name''
 +
| Member
 +
| Name of the structure field or function parameter that contains the size of the array
 +
The following restrictions apply:
 +
* The type of the size-name must be an integral type.
 +
* The size-field must reside within the same payload block as the structure or the function payload.
 +
|-
 +
| ''max-size''
 +
| Integer
 +
| Maximum size of the conformant array
 +
|}
 +
 +
 +
=== Example ===
 +
<source lang=c>
 +
/* Constant defining the maximum array size */
 +
#define MAX_BUFFER_SIZE 20
 +
 +
/* Structure defining a message payload with a conformant array */
 +
/* The array field must be the last member in the payload      */
 +
typedef struct {
 +
  int f1;
 +
  short bufferSize;
 +
  char  buffer[1];
 +
} CmdPayload_t;
 +
 +
/* Use the scl_conform pragma to define the conformant arrays */
 +
#pragma scl_conform( CmdPayload_t, bufferSize, MAX_BUFFER_SIZE )
 +
</source>
 +
 +
=== See Also ===
 +
* For additional information on scl_conform, including constraints, refer to the section on scl_conform in the [[Media:s2sSCLReferenceGuide.pdf|SCL Reference Guide]].
 +
 +
 +
= scl_ptr =
 +
 +
The scl_ptr pragma is used to identify a pointer data type and assign it pointer-specific attributes, such as marshaling direction and memory usage.
 +
 +
=== Syntax ===
 +
#pragma scl_ptr(type-name, direction, usage)
 +
 +
#pragma scl_ptr(type-name, field-name, direction, usage)
 +
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;" 
 +
| '''Parameters'''
 +
| '''Type'''
 +
| '''Description'''
 +
|-
 +
| ''type-name''
 +
| Type
 +
| Name of the type that contains the pointer. The container type can be a structure, union, the pointer type itself, or a function. If the container type is a structure or union, the pointer is a member and the field-name must be specified. If the container type is a function, then the pointer is a parameter and the field-name must be specified.
 +
|-
 +
| ''field-name [Optional]''
 +
| Member
 +
| Name of the pointer field, which may be a member field contained within a structure/union, or a parameter in the ParameterList of a function.
 +
|-
 +
| ''direction''
 +
| String
 +
| Direction in which the pointer data is marshaled; refer to the Pointer Direction Table below. This affects read and write access to the pointer data.
 +
|-
 +
| ''usage''
 +
| String
 +
| Pointer usage indicator; refer to the Pointer Memory Usage Table below.
 +
|}
 +
 +
'''Pointer Direction Table'''
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;" 
 +
| '''Value'''
 +
| '''Meaning'''
 +
|-
 +
| ''"IN"''
 +
| Specifies that the pointer memory can be used only as input to the receiver of the pointer. The Owner of the interface may only consider this read-only memory.
 +
|-
 +
| ''"OUT"''
 +
| Specifies that the pointer memory can be used to output information. The memory is allocated by the User and only written to by the Owner.
 +
|-
 +
| ''"INOUT"''
 +
| Specifies that the pointer memory can be used as both input and output. The User may send in data when sending the command (or calling the function), and may read the Owner’s output upon receipt of the response (or return of the function).
 +
|-
 +
| ''"RETURN"''
 +
| Specifies that the pointer memory may be read by the User of the interface. The User may only consider this as read-only memory and must not free it.
 +
|-
 +
| ''"INRETURN"''
 +
| Specifies that the pointer memory is allocated by both user and owner. There is no single block of memory pointed to by an "INRETURN" pointer. Rather there is one block on the call (or message send) and a second block on the return (or completion of the two-way message). Thus the first block has the characteristics of an "IN" block and the second the characteristics of a "RETURN" block.
 +
|}
 +
 +
'''Pointer Memory Usage Table'''
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;" 
 +
| '''Value'''
 +
| '''Meaning'''
 +
|-
 +
| ''"PRIVATE"''
 +
| Pointer memory is private and may not be released by the Reader.
 +
|-
 +
| ''"POOL"''
 +
| Pointer memory is created from common pool and must be released by the Reader.
 +
|}
 +
 +
=== Notes ===
 +
* A compiler error will be reported if an pointer does not point to a fixed size type.
 +
* Response payloads cannot use the "OUT" or "INOUT" direction.
 +
* Pointers with "OUT" or "INOUT" direction cannot indicate POOL pointer usage.
 +
* One-way messages (command and response) cannot have data that contains an "OUT" or "INOUT" Pointer.
 +
* The pointers declared type cannot be pointer to void; e.g., void *. This is considered an opaque pointer.
 +
* For additional information on scl_ptr, including constraints, refer to the section on scl_ptr in the [[Media:s2sSCLReferenceGuide.pdf|SCL Reference Guide]].
 +
* As of STRIDE 3.0.0102 the direction and usage attributes are not symbolic tokens anymore. They became string literals (need to be quoted). See this [[Handling_of_pointer_attribute_tokens|page]] for details.
 +
 +
=== Examples ===
 +
 +
Two examples using the scl_ptr pragma are shown below:
 +
 +
# The first example uses the scl_ptr pragma to assign pointer attributes to a structure member and a parameter list member.
 +
# The second example uses the scl_ptr pragma to assign pointer attributes to type definitions.
 +
 +
==== Example 1 ====
 +
<source lang=c>
 +
/* Typedef defining a structure with a member of type pointer to char */
 +
typedef struct
 +
{
 +
  int f1;
 +
  char * f2;
 +
}data_t;
 +
 +
/* Function prototype with an "INOUT" pointer of type data_t */
 +
void modifyData( data_t * p );
 +
 +
/* Use the scl_function pragma to associate a SUID with the function ModifyData */
 +
#pragma scl_function( modifyData )
 +
/* Use the scl_ptr pragma to define the member f2 as a "RETURN" pointer */
 +
#pragma scl_ptr( data_t.f2, "OUT", "PRIVATE" )
 +
/* Use the scl_ptr pragma to define the parameter p as an "INOUT" pointer */
 +
#pragma scl_ptr( modifyData.p, "INOUT", "PRIVATE" )
 +
</source>
 +
 +
==== Example 2 ====
 +
<source lang=c>
 +
/* Typedef defining a pointer as a status type */
 +
typedef int * StatusCode;
 +
 +
/* Apply scl_ptr to the StatusCode type. It is always an "OUT" pointer type */
 +
#pragma scl_ptr ( StatusCode, "OUT", "PRIVATE" );
 +
 +
/* Prototype defining a function that returns a pointer to the data structure */
 +
void GetStatus( StatusCode outCode );
 +
 +
/* Mark getStatus as an SCL-compliant function */
 +
#pragma scl_function ( GetStatus );
 +
</source>
 +
 +
= scl_ptr_flist =
 +
 +
The scl_ptr_flist() pragma is used to specify the candidate functions that are available for a specific function pointer data type.
 +
 +
 +
=== Syntax ===
 +
 +
#pragma scl_ptr_flist(type-name, default-name)
 +
 +
#pragma scl_ptr_flist(type-name, field-name, default-name)
 +
 +
#pragma scl_ptr_flist(type-name, candidate-1, candidate-2..n)
 +
 +
#pragma scl_ptr_flist(type-name, field-name, candidate-1, candidate-2..n)
 +
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;" 
 +
| '''Parameters'''
 +
| '''Type'''
 +
| '''Description'''
 +
|-
 +
| ''type-name''
 +
| String
 +
| Name of the type that contains the function pointer
 +
|-
 +
| ''field-name''
 +
| Member
 +
| Name of the pointer member within the struct/union or in the parameter list of the function
 +
|-
 +
| ''candidate-1''
 +
| String
 +
| Name of the candidate function
 +
|-
 +
| ''candidate-2..n [Optional]''
 +
| String
 +
| Optional name(s) of additional candidate function(s)
 +
|-
 +
| ''default-name''
 +
| Quoted string
 +
| Name to be assigned to the default function (quoted string)
 +
|}
 +
 +
=== Notes ===
 +
* The syntax shown in form 1 of 4 above should only be used when function pointers are part of the command payload.
 +
* The syntax shown in form 2 of 4 above should only be used when returning function pointers.
 +
* A function pointer data type as written in ANSI C merely specifies the format of the prototype. The format of the prototype is the data type of the return value and the datatypes of the parameters, if any. The scl_ptr_flist() pragma is therefore required by the SCL compiler to indicate which SCL-compatible interfaces are associated with a particular function pointer data type.
 +
* When a payload contains a field that is a pointer to a function, it is possible that the receiver of such a payload may make a call using the value received. Because the set of possible functions that might be passed is very large, and because all remotable methods must be identified with a SUID, each such payload value be constrained to identify the specific set of functions that might be passed. These are referred to as the candidates. Each candidate must be known by its name. The [[scl_brew_class|scl_brew_class()]] and scl_ptr_flist() pragmas are used for constraining fields of type pointer to function in this way. 
 +
* Payload fields of type pointer to function that are not explicitly associated with a list of candidates are treated as if they have been declared as void *. 
 +
 +
=== See Also ===
 +
* For additional information on scl_ptr_flist(), including constraints, refer to the section on scl_ptr_flist() in the [[Media:s2sSCLReferenceGuide.pdf|SCL Reference Guide]].
 +
 +
 +
= scl_ptr_opaque =
 +
 +
The scl_ptr_opaque pragma is used to specify a pointer data type as pointing to opaque data that should not be marshaled.
 +
 +
=== Syntax ===
 +
#pragma scl_ptr_opaque(type-name)
 +
 +
#pragma scl_ptr_opaque(type-name, field-name)
 +
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;" 
 +
| '''Parameters'''
 +
| '''Type'''
 +
| '''Description'''
 +
|-
 +
| ''type-name''
 +
| Type
 +
| Name of the type that contains the Pointer. The container type may be the name of a structure, a union, the pointer type itself, or a function. If the container type is a structure or a union, then the pointer is a member and the field-name must be specified. If the container type is a function, then the pointer is a parameter and the field-name must be specified.
 +
|-
 +
| ''field-name [Optional]''
 +
| Member
 +
| Name of the Pointer field, which may be a member field contained within a structure/union, or a parameter in the parameter list of a function.
 +
|}
 +
 +
=== Notes ===
 +
* An opaque pointer is a pointer that points to opaque data. This means that the receiver of the pointer may not examine the data being pointed to. The meaningful part of an opaque pointer is the pointer value itself, or the pointer address. Opaque pointer are often used for the passing of handles.
 +
* A pointer of type void (i.e., void *) is by default an opaque pointer. No pragma may be applied to a void pointer.
 +
 +
=== Examples ===
 +
 +
Two examples using the scl_ptr_opaque pragma are shown below:
 +
 +
==== Example 1 ====
 +
The first example uses the scl_ptr_opaque pragma to declare a structure member and a parameter list member as an opaque pointer.
 +
<source lang=c>
 +
// Typedef defining a structure with a member of type pointer to char //
 +
typedef struct
 +
{
 +
  int f1;
 +
  char * f2;
 +
}data_t;
 +
 +
// Function prototype with an INOUT pointer of type data_t //
 +
void modifyData( data_t * p );
 +
 +
// Use the scl_function pragma to associate a SUID with the function ModifyData //
 +
#pragma scl_function( modifyData )
 +
// Use the scl_ptr_opaque pragma to define the member f2 as opaque //
 +
#pragma scl_ptr_opaque( data_t.f2 )
 +
// Use the scl_ptr_opaque pragma to define the parameter p as opaque //
 +
#pragma scl_ptr_opaque( modifyData.p )
 +
</source>
 +
 +
==== Example 2 ====
 +
The second example uses the scl_ptr_opaque pragma to declare pointer type definitions as opaque.
 +
<source lang=c>
 +
// Typedef defining a structure with two members //
 +
typedef struct
 +
{
 +
  int f1;
 +
  char f2;
 +
}data_t;
 +
 +
// Typedef defining a pointer to the data strucure //
 +
typedef data_t * pointerToData;
 +
// Prototype defining a function that returns a pointer to the data structure //
 +
data_t * getData( void );
 +
 +
// Use the scl_ptr_opaque pragma to define the type pointerToData as opaque //
 +
#pragma scl_ptr_opaque( pointerToData )
 +
// Use the scl_function pragma to associate a SUID with the function "getData" //
 +
#pragma scl_function( getData )
 +
// Use the scl_ptr pragma to define "getData" return value as opaque pointer //
 +
#pragma scl_ptr_opaque( getData )
 +
</source>
 +
 +
=== See Also ===
 +
For additional information on scl_ptr_opaque, including constraints, refer to the section on scl_ptr_opaque in the [[Media:s2sSCLReferenceGuide.pdf|SCL Reference Guide]].
 +
 +
= scl_ptr_sized =
 +
 +
The scl_ptr_sized pragma is used to identify a pointer data type, and assign to it attributes that are used to point to a series of elements allocated in contiguous memory. The pragma also assigns additional attributes, such as marshaling direction and memory usage.
 +
 +
=== Syntax ===
 +
#pragma scl_ptr_sized(type-name, direction, usage, max-size)
 +
 +
#pragma scl_ptr_sized(type-name, direction, usage, max-size, size-field-name)
 +
 +
#pragma scl_ptr_sized(type-name, field-name, direction, usage, max-size)
 +
 +
#pragma scl_ptr_sized(type-name, field-name, direction, usage, max-size, size-field-name)
 +
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;" 
 +
| '''Parameters'''
 +
| '''Type'''
 +
| '''Description'''
 +
|-
 +
| ''type-name''
 +
| Type
 +
| Name of the type that contains the pointer. The container type can be a structure, union, the pointer type itself, or a function. If the container type is a structure or union, the pointer is a member and the field-name must be specified. If the container type is a function, then the pointer is a parameter and the field-name must be specified.
 +
|-
 +
| ''field-name [Optional]''
 +
| Member
 +
| Name of the pointer field, which may be a member field contained within a structure/union, or a parameter in the parameter list of a function.
 +
|-
 +
| ''direction''
 +
| String
 +
| Direction in which the pointer data is marshaled; refer to the Pointer Direction Table below. This affects read and write access to the pointer data.
 +
|-
 +
| ''usage''
 +
| String
 +
| Pointer usage indicator; refer to the Pointer Memory Usage Table below.
 +
|-
 +
| ''max-size''
 +
| Integer
 +
| An integer constant that specifies the maximum number of elements pointed to.
 +
|-
 +
| ''size-field-name''
 +
| Member
 +
| The name of the field that specifies the current number of elements pointed to.
 +
|}
 +
 +
 +
'''Pointer Direction Table'''
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;" 
 +
| '''Value'''
 +
| '''Meaning'''
 +
|-
 +
| ''"IN"''
 +
| Specifies that the pointer memory can be used only as input to the receiver of the pointer. The Owner of the interface may only consider this read-only memory.
 +
|-
 +
| ''"OUT"''
 +
| Specifies that the pointer memory can be used to output information. The memory is allocated by the User and only written to by the Owner.
 +
|-
 +
| ''"INOUT"''
 +
| Specifies that the pointer memory can be used as both input and output. The User may send in data when sending the command (or calling the function), and may read the Owner’s output upon receipt of the response (or return of the function).
 +
|-
 +
| ''"RETURN"''
 +
| Specifies that the pointer memory may be read by the User of the interface. The User may only consider this as read-only memory and must not free it.
 +
|-
 +
| ''"INRETURN"''
 +
| Specifies that the pointer memory is allocated by both user and owner. There is no single block of memory pointed to by an "INRETURN" pointer. Rather there is one block on the call (or message send) and a second block on the return (or completion of the two-way message). Thus the first block has the characteristics of an "IN" block and the second the characteristics of a "RETURN" block.
 +
|}
 +
 +
 +
'''Pointer Memory Usage Table'''
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;" 
 +
| '''Value'''
 +
| '''Meaning'''
 +
|-
 +
| ''"PRIVATE"''
 +
| Pointer memory is private and may not be released by the Reader.
 +
|-
 +
| ''"POOL"''
 +
| Pointer memory is created from common pool and must be released by the Reader.
 +
|}
 +
 +
=== Notes ===
 +
* A sized pointer is a pointer to one or more elements of data. There are two types of sized pointers:
 +
:# Fixed-sized always points to the same number of elements as specified by max-size.
 +
:# Variable-sized points to a variable number of elements. The number of elements currently pointed to is indicated by size-field-name, which must be of type integer.
 +
* If the sized pointer is "IN", then size-field-name can be a non-pointer integer type; otherwise it must be a single pointer. In either case, the parameter size-field-name must have the same direction as its associated-sized pointer.
 +
* The type of the pointer cannot be pointer to void; e.g. void *. This is considered an opaque pointer.
 +
 +
=== Error Conditions ===
 +
* A compiler error will be reported if a pointer does not point to a fixed size type.
 +
* Sized pointers cannot use the "INOUT" direction.
 +
* Response payloads cannot use the "OUT" or "INOUT" direction.
 +
* Pointers with "OUT" or "INOUT" direction cannot indicate "POOL" pointer usage.
 +
* One-way messages (command and response) cannot have data that contains an "OUT" or "INOUT" pointer.
 +
 +
=== Examples ===
 +
This example uses the scl_ptr_sized pragma to assign pointer attributes to a parameter list member.
 +
<source lang=c>
 +
/* Constant defining the maximum buffer size */
 +
#define MAX_BUFFER_SIZE 256
 +
 +
/* Function prototype with a sized IN pointer of type char */
 +
void MemWrite( char * buffer, int size );
 +
 +
/* Function prototype with a sized OUT pointer of type char */
 +
void MemRead ( char * buffer, int size );
 +
 +
/* Use the scl_function pragma to define the function prototypes */
 +
#pragma scl_function(MemWrite)
 +
#pragma scl_function(MemRead)
 +
/* Use the scl_ptr_sized pragma to specify the attributes for the sized pointers */
 +
/* Direction = "IN", memory usage = "PRIVATE", max size = 256, size field name = "size" */
 +
#pragma scl_ptr_sized(MemWrite, buffer, "IN", "PRIVATE", MAX_BUFFER_SIZE, size)
 +
 +
/* Direction = "OUT", memory usage = "PRIVATE", max size = 256, size field name = "size" */
 +
#pragma scl_ptr_sized(MemRead, buffer, "OUT", "PRIVATE", MAX_BUFFER_SIZE, size)
 +
</source>
 +
 +
=== See Also ===
 +
For additional information on scl_ptr_sized, including constraints, refer to the [[Media:s2sSCLReferenceGuide.pdf|SCL Reference Guide]].

Revision as of 17:01, 5 July 2015

The SCL pragmas are designed to allow annotation of C language constructs in such a way as to identify and define messages, function calls, and test units so that they can be transparently intercepted and remoted.

scl_function

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.

Syntax

#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 defaults for IMPLICIT and STRIDE_TEST_GROUP when capturing boo 

int foo(int x);

void boo(void);

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


Setting a specific GROUP ID 

void boo(void);

#pragma scl_function(boo, "DEFINITION", ''IMPLICIT'', ''MY_TEST_GROUP'')


scl_cast

Constraining is the transformation of a data type so that it behaves like another data type. There are two forms of constraining: type constraining and value constraining (see scl_values pragma).

Type constraining, as in the C language, has a source type and a destination type. The source type is the data type that is originally specified (e.g., written in the header file). The destination type is the data type into which the source type is being transformed.

The scl_cast pragma is used for type constraining. It would commonly be used to map enumerations to other types, or to map a void pointer. The STRIDE host environment treats the constrained (or casted) field as if it were the new type, but the original type size is maintained.

Syntax

The following form changes the type inside the specified container (the function or structure): 

#pragma scl_cast(global-type-specifier, cast-type)

The following form changes the type globally: 

#pragma scl_cast(container-specifier, field-specifier, cast-type)
Parameters Type Description
container-specifier String Name of the container of the field to be cast
field-specifier String Name of the field to be cast
cast-type String Name of the new type for the cast result
global-type-specifier String Name of the global type to be cast

Notes

  • scl_cast() can only be used to cast items that are of exactly the same size.
  • scl_cast() can only be applied to the integral type and pointer type instances, or typedef names for integral types or pointer types. The type-specifier must designate a pointer type or integral type.
  • scl_cast() can be used to cast a data item of type void* to a union type, if all members of the union are of type pointer.
  • scl_cast() cannot be applied to bit fields.
  • An error will result if scl_cast() is applied to a set of runtime values that intersects with the set of values explicitly specified by any pragma that has appeared earlier (by way of lexical position) in the source code. In other words, scl_cast() cannot be used to "cast away" information conveyed by previous pragmas. (Refer to section 1.2.16, Absolute Specifiers, in the SCL Reference Guide for a description and definition of runtime value sets.)

Examples

Example 1

int func(void *p); 

#pragma scl_function(func)
#pragma scl_cast(func, p, int *)

Example 2

typedef unsigned int u32_t; 
typedef enum 
{
  ONE = 1, 
  TWO = 2, 
  THREE = 3
} numbers_e; 

// cast occurrences of u32_t to numbers_e
#pragma scl_cast(u32_t, numbers_e)

int func(u32_t x); 
#pragma scl_function(func)


scl_conform

The scl_conform pragma allows the user to define a conformant array within a payload. The payload can be a C structure or a parameter declaration list. The conformant array must be the last item in the payload (e.g., the last field in the structure, or the last parameter in the declaration list). Because of this, only the payload name and the name of the size field in that payload are required. The SCL compiler automatically assumes the conformant array field within the specified payload.

NOTE: For an alternative use case of sized structure please look at scl_struct_sized pragma.

Syntax

#pragma scl_conform(name, size-name, max-size)
Parameters Type Description
name String Name of the structure or function that encapsulates the conformant array

The following restrictions apply:

  • The structure type may not be pointed to by a sized pointer.
  • The structure type may not be used in an array.
  • The structure type may not be a member of an union.
  • The structure type may not be a member of any other structure unless it is the last member.
  • The structure type may not be passed as a formal parameter or return value of a function (but a pointer to it is allowed).
  • The structure type cannot reside within OUT memory block.
size-name Member Name of the structure field or function parameter that contains the size of the array

The following restrictions apply:

  • The type of the size-name must be an integral type.
  • The size-field must reside within the same payload block as the structure or the function payload.
max-size Integer Maximum size of the conformant array


Example

/* Constant defining the maximum array size */
#define MAX_BUFFER_SIZE 20

/* Structure defining a message payload with a conformant array */
/* The array field must be the last member in the payload       */
typedef struct {
  int f1;
  short bufferSize;
  char  buffer[1];
} CmdPayload_t;

/* Use the scl_conform pragma to define the conformant arrays */
#pragma scl_conform( CmdPayload_t, bufferSize, MAX_BUFFER_SIZE )

See Also

  • For additional information on scl_conform, including constraints, refer to the section on scl_conform in the SCL Reference Guide.


scl_ptr

The scl_ptr pragma is used to identify a pointer data type and assign it pointer-specific attributes, such as marshaling direction and memory usage.

Syntax

#pragma scl_ptr(type-name, direction, usage)

#pragma scl_ptr(type-name, field-name, direction, usage)
Parameters Type Description
type-name Type Name of the type that contains the pointer. The container type can be a structure, union, the pointer type itself, or a function. If the container type is a structure or union, the pointer is a member and the field-name must be specified. If the container type is a function, then the pointer is a parameter and the field-name must be specified.
field-name [Optional] Member Name of the pointer field, which may be a member field contained within a structure/union, or a parameter in the ParameterList of a function.
direction String Direction in which the pointer data is marshaled; refer to the Pointer Direction Table below. This affects read and write access to the pointer data.
usage String Pointer usage indicator; refer to the Pointer Memory Usage Table below.

Pointer Direction Table

Value Meaning
"IN" Specifies that the pointer memory can be used only as input to the receiver of the pointer. The Owner of the interface may only consider this read-only memory.
"OUT" Specifies that the pointer memory can be used to output information. The memory is allocated by the User and only written to by the Owner.
"INOUT" Specifies that the pointer memory can be used as both input and output. The User may send in data when sending the command (or calling the function), and may read the Owner’s output upon receipt of the response (or return of the function).
"RETURN" Specifies that the pointer memory may be read by the User of the interface. The User may only consider this as read-only memory and must not free it.
"INRETURN" Specifies that the pointer memory is allocated by both user and owner. There is no single block of memory pointed to by an "INRETURN" pointer. Rather there is one block on the call (or message send) and a second block on the return (or completion of the two-way message). Thus the first block has the characteristics of an "IN" block and the second the characteristics of a "RETURN" block.

Pointer Memory Usage Table

Value Meaning
"PRIVATE" Pointer memory is private and may not be released by the Reader.
"POOL" Pointer memory is created from common pool and must be released by the Reader.

Notes

  • A compiler error will be reported if an pointer does not point to a fixed size type.
  • Response payloads cannot use the "OUT" or "INOUT" direction.
  • Pointers with "OUT" or "INOUT" direction cannot indicate POOL pointer usage.
  • One-way messages (command and response) cannot have data that contains an "OUT" or "INOUT" Pointer.
  • The pointers declared type cannot be pointer to void; e.g., void *. This is considered an opaque pointer.
  • For additional information on scl_ptr, including constraints, refer to the section on scl_ptr in the SCL Reference Guide.
  • As of STRIDE 3.0.0102 the direction and usage attributes are not symbolic tokens anymore. They became string literals (need to be quoted). See this page for details.

Examples

Two examples using the scl_ptr pragma are shown below:

  1. The first example uses the scl_ptr pragma to assign pointer attributes to a structure member and a parameter list member.
  2. The second example uses the scl_ptr pragma to assign pointer attributes to type definitions.

Example 1

/* Typedef defining a structure with a member of type pointer to char */
typedef struct
{
  int f1;
  char * f2;
}data_t;

/* Function prototype with an "INOUT" pointer of type data_t */
void modifyData( data_t * p );

/* Use the scl_function pragma to associate a SUID with the function ModifyData */
#pragma scl_function( modifyData )
/* Use the scl_ptr pragma to define the member f2 as a "RETURN" pointer */
#pragma scl_ptr( data_t.f2, "OUT", "PRIVATE" )
/* Use the scl_ptr pragma to define the parameter p as an "INOUT" pointer */
#pragma scl_ptr( modifyData.p, "INOUT", "PRIVATE" )

Example 2

/* Typedef defining a pointer as a status type */
typedef int * StatusCode;

/* Apply scl_ptr to the StatusCode type. It is always an "OUT" pointer type */
#pragma scl_ptr ( StatusCode, "OUT", "PRIVATE" );

/* Prototype defining a function that returns a pointer to the data structure */
void GetStatus( StatusCode outCode );

/* Mark getStatus as an SCL-compliant function */
#pragma scl_function ( GetStatus );

scl_ptr_flist

The scl_ptr_flist() pragma is used to specify the candidate functions that are available for a specific function pointer data type.


Syntax

#pragma scl_ptr_flist(type-name, default-name)

#pragma scl_ptr_flist(type-name, field-name, default-name)

#pragma scl_ptr_flist(type-name, candidate-1, candidate-2..n)

#pragma scl_ptr_flist(type-name, field-name, candidate-1, candidate-2..n)
Parameters Type Description
type-name String Name of the type that contains the function pointer
field-name Member Name of the pointer member within the struct/union or in the parameter list of the function
candidate-1 String Name of the candidate function
candidate-2..n [Optional] String Optional name(s) of additional candidate function(s)
default-name Quoted string Name to be assigned to the default function (quoted string)

Notes

  • The syntax shown in form 1 of 4 above should only be used when function pointers are part of the command payload.
  • The syntax shown in form 2 of 4 above should only be used when returning function pointers.
  • A function pointer data type as written in ANSI C merely specifies the format of the prototype. The format of the prototype is the data type of the return value and the datatypes of the parameters, if any. The scl_ptr_flist() pragma is therefore required by the SCL compiler to indicate which SCL-compatible interfaces are associated with a particular function pointer data type.
  • When a payload contains a field that is a pointer to a function, it is possible that the receiver of such a payload may make a call using the value received. Because the set of possible functions that might be passed is very large, and because all remotable methods must be identified with a SUID, each such payload value be constrained to identify the specific set of functions that might be passed. These are referred to as the candidates. Each candidate must be known by its name. The scl_brew_class() and scl_ptr_flist() pragmas are used for constraining fields of type pointer to function in this way.
  • Payload fields of type pointer to function that are not explicitly associated with a list of candidates are treated as if they have been declared as void *.

See Also

  • For additional information on scl_ptr_flist(), including constraints, refer to the section on scl_ptr_flist() in the SCL Reference Guide.


scl_ptr_opaque

The scl_ptr_opaque pragma is used to specify a pointer data type as pointing to opaque data that should not be marshaled.

Syntax

#pragma scl_ptr_opaque(type-name)

#pragma scl_ptr_opaque(type-name, field-name)
Parameters Type Description
type-name Type Name of the type that contains the Pointer. The container type may be the name of a structure, a union, the pointer type itself, or a function. If the container type is a structure or a union, then the pointer is a member and the field-name must be specified. If the container type is a function, then the pointer is a parameter and the field-name must be specified.
field-name [Optional] Member Name of the Pointer field, which may be a member field contained within a structure/union, or a parameter in the parameter list of a function.

Notes

  • An opaque pointer is a pointer that points to opaque data. This means that the receiver of the pointer may not examine the data being pointed to. The meaningful part of an opaque pointer is the pointer value itself, or the pointer address. Opaque pointer are often used for the passing of handles.
  • A pointer of type void (i.e., void *) is by default an opaque pointer. No pragma may be applied to a void pointer.

Examples

Two examples using the scl_ptr_opaque pragma are shown below:

Example 1

The first example uses the scl_ptr_opaque pragma to declare a structure member and a parameter list member as an opaque pointer. 

// Typedef defining a structure with a member of type pointer to char //
typedef struct
{
  int f1;
  char * f2;
}data_t;

// Function prototype with an INOUT pointer of type data_t //
void modifyData( data_t * p );

// Use the scl_function pragma to associate a SUID with the function ModifyData //
#pragma scl_function( modifyData )
// Use the scl_ptr_opaque pragma to define the member f2 as opaque //
#pragma scl_ptr_opaque( data_t.f2 )
// Use the scl_ptr_opaque pragma to define the parameter p as opaque //
#pragma scl_ptr_opaque( modifyData.p )

Example 2

The second example uses the scl_ptr_opaque pragma to declare pointer type definitions as opaque. 

// Typedef defining a structure with two members //
typedef struct
{
  int f1;
  char f2;
}data_t;

// Typedef defining a pointer to the data strucure //
typedef data_t * pointerToData;
// Prototype defining a function that returns a pointer to the data structure //
data_t * getData( void );

// Use the scl_ptr_opaque pragma to define the type pointerToData as opaque //
#pragma scl_ptr_opaque( pointerToData )
// Use the scl_function pragma to associate a SUID with the function "getData" //
#pragma scl_function( getData )
// Use the scl_ptr pragma to define "getData" return value as opaque pointer //
#pragma scl_ptr_opaque( getData )

See Also

For additional information on scl_ptr_opaque, including constraints, refer to the section on scl_ptr_opaque in the SCL Reference Guide.

scl_ptr_sized

The scl_ptr_sized pragma is used to identify a pointer data type, and assign to it attributes that are used to point to a series of elements allocated in contiguous memory. The pragma also assigns additional attributes, such as marshaling direction and memory usage.

Syntax

#pragma scl_ptr_sized(type-name, direction, usage, max-size)

#pragma scl_ptr_sized(type-name, direction, usage, max-size, size-field-name)

#pragma scl_ptr_sized(type-name, field-name, direction, usage, max-size)

#pragma scl_ptr_sized(type-name, field-name, direction, usage, max-size, size-field-name)
Parameters Type Description
type-name Type Name of the type that contains the pointer. The container type can be a structure, union, the pointer type itself, or a function. If the container type is a structure or union, the pointer is a member and the field-name must be specified. If the container type is a function, then the pointer is a parameter and the field-name must be specified.
field-name [Optional] Member Name of the pointer field, which may be a member field contained within a structure/union, or a parameter in the parameter list of a function.
direction String Direction in which the pointer data is marshaled; refer to the Pointer Direction Table below. This affects read and write access to the pointer data.
usage String Pointer usage indicator; refer to the Pointer Memory Usage Table below.
max-size Integer An integer constant that specifies the maximum number of elements pointed to.
size-field-name Member The name of the field that specifies the current number of elements pointed to.


Pointer Direction Table

Value Meaning
"IN" Specifies that the pointer memory can be used only as input to the receiver of the pointer. The Owner of the interface may only consider this read-only memory.
"OUT" Specifies that the pointer memory can be used to output information. The memory is allocated by the User and only written to by the Owner.
"INOUT" Specifies that the pointer memory can be used as both input and output. The User may send in data when sending the command (or calling the function), and may read the Owner’s output upon receipt of the response (or return of the function).
"RETURN" Specifies that the pointer memory may be read by the User of the interface. The User may only consider this as read-only memory and must not free it.
"INRETURN" Specifies that the pointer memory is allocated by both user and owner. There is no single block of memory pointed to by an "INRETURN" pointer. Rather there is one block on the call (or message send) and a second block on the return (or completion of the two-way message). Thus the first block has the characteristics of an "IN" block and the second the characteristics of a "RETURN" block.


Pointer Memory Usage Table

Value Meaning
"PRIVATE" Pointer memory is private and may not be released by the Reader.
"POOL" Pointer memory is created from common pool and must be released by the Reader.

Notes

  • A sized pointer is a pointer to one or more elements of data. There are two types of sized pointers:
  1. Fixed-sized always points to the same number of elements as specified by max-size.
  2. Variable-sized points to a variable number of elements. The number of elements currently pointed to is indicated by size-field-name, which must be of type integer.
  • If the sized pointer is "IN", then size-field-name can be a non-pointer integer type; otherwise it must be a single pointer. In either case, the parameter size-field-name must have the same direction as its associated-sized pointer.
  • The type of the pointer cannot be pointer to void; e.g. void *. This is considered an opaque pointer.

Error Conditions

  • A compiler error will be reported if a pointer does not point to a fixed size type.
  • Sized pointers cannot use the "INOUT" direction.
  • Response payloads cannot use the "OUT" or "INOUT" direction.
  • Pointers with "OUT" or "INOUT" direction cannot indicate "POOL" pointer usage.
  • One-way messages (command and response) cannot have data that contains an "OUT" or "INOUT" pointer.

Examples

This example uses the scl_ptr_sized pragma to assign pointer attributes to a parameter list member. 

/* Constant defining the maximum buffer size */
#define MAX_BUFFER_SIZE 256
 
/* Function prototype with a sized IN pointer of type char */
void MemWrite( char * buffer, int size );
 
/* Function prototype with a sized OUT pointer of type char */
void MemRead ( char * buffer, int size );
 
/* Use the scl_function pragma to define the function prototypes */
#pragma scl_function(MemWrite)
#pragma scl_function(MemRead)
/* Use the scl_ptr_sized pragma to specify the attributes for the sized pointers */
/* Direction = "IN", memory usage = "PRIVATE", max size = 256, size field name = "size" */
#pragma scl_ptr_sized(MemWrite, buffer, "IN", "PRIVATE", MAX_BUFFER_SIZE, size)
 
/* Direction = "OUT", memory usage = "PRIVATE", max size = 256, size field name = "size" */
#pragma scl_ptr_sized(MemRead, buffer, "OUT", "PRIVATE", MAX_BUFFER_SIZE, size)

See Also

For additional information on scl_ptr_sized, including constraints, refer to the SCL Reference Guide.

Retrieved from "https://www.stridewiki.com/index.php?title=Pragmas&oldid=14353"