Studio:Scl ptr sized

The scl_ptr_sized pragma

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, pointer-usage, max-size)

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

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

#pragma scl_ptr_sized(type-name, field-name, direction, pointer-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	Constant	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.
pointer-usage	Constant	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 embedded pointer. In either case, the parameter size-field-name must have the same direction as its associated-sized pointer.
• Currently, the type of the data that is pointed to cannot be void; for example, void *. This is considered an opaque pointer.

Error Conditions

• A compiler error will be reported if an embedded 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].