Difference between revisions of "Studio:Scl struct sized"

From STRIDE Wiki
Jump to: navigation, search
(→‎Syntax)
(→‎Syntax)
 
(45 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
= The scl_struct_sized pragma =
 
= The scl_struct_sized pragma =
  
−
The scl_struct_sized pragma identifies a particular struct or pointer-to-struct as a sized structure. A sized structure typically has bytes allocated past its type definition.
+
The scl_struct_sized pragma is used to identify a sized structure. A sized structure is a C programming convention for representing a structure whose size is variable and defined by one of the members of the structure. This pragma is infrequently used, but must be used, whenever the programmer defined size does not match the C language size of the structure (as calculated by the sizeof macro).
 +
 
 +
NOTE: ''For an alternative use case of sized structure please look at [[scl_conform]] pragma.''
  
 
== Syntax ==
 
== Syntax ==
−
  #pragma scl_struct_sized(type-name, max-size)
+
  #pragma scl_struct_sized(type-name, size-field)
 
   
 
   
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"   
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"   
−
| '''Parameters'''
+
| width="100" | '''Parameters'''
−
| '''Type'''
+
| width="100" | '''Type'''
 
| '''Description'''
 
| '''Description'''
 
|-
 
|-
 
| ''type-name''
 
| ''type-name''
−
| Struct or Struct*
+
| Structure Type
−
| Specifies a structure type that is to be sized (allocated bytes beyond its type definition).
+
| Identifies a structure type or structure instance whose runtime size is not the same as its C language size and contains a field whose value is the runtime size.
 +
The following restrictions apply:
 
* The structure type may not be pointed to by a sized pointer.
 
* The structure type may not be pointed to by a sized pointer.
−
* The structure type may not be a member of any other structure or union.
+
* The structure type may not be used in an array.
−
* The structure type may not be passed as a function parameter.
+
* The structure type may not be a member of an union.
−
* The structure type may only reside in IN/INOUT memory blocks.
+
* The structure type may not be a member of any other structure unless it is the last member.
 +
* The structure type may not be used 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.
 
* If the last member of the structure is an array, the array's size is calculated based upon max-size - (size of struct's other members).
 
* If the last member of the structure is an array, the array's size is calculated based upon max-size - (size of struct's other members).
 
|-
 
|-
−
| ''max-size''
+
| ''size-field''
−
| Member Field of type-name
+
| Member
−
| Specifies the number of bytes for the sized struct.
+
| Identifies a field within the sized structure whose value determines the actual runtime size of the structure. The following restrictions apply:
−
* The value contained by max_size may not be less than the structure's type size.
+
* The type of the size-field must be an integral type.
−
* The max-size value must be an integral type (int, short, char).
+
* The value (at runtime) is expected to be greater than the type size of the structure (as determined by the sizeof macro).
−
* The max-size may not exceed the maximum payload size.
+
* The size-field must reside within the same payload block as the sized structure.
−
* The max_size must reside in the same payload block as the sized struct (no indirection '*' or '->').
 
 
|}
 
|}
  
Line 35: Line 39:
 
<source lang=c>
 
<source lang=c>
 
typedef struct {
 
typedef struct {
−
     int nSize;
+
     int size;
−
     int nSomeJunk;
+
     int someJunk;
−
     int nMoreJunk;
+
     int moreJunk;
 
} SimpleSizedStruct;
 
} SimpleSizedStruct;
  
−
extern void f(SimpleSizedStruct* s);
+
#ifdef _SCL
−
#pragma scl_struct_sized(f.s, nSize);
+
#pragma scl_struct_sized(SimpleSizedStruct, size)
 +
#endif
  
 
</source>
 
</source>
  
 
=== Example 2 ===
 
=== Example 2 ===
−
This example shows the declaration of a sized struct with a conformant array.
+
This example shows the declaration of a sized struct containing a variable length array whose actual length is proportional to the value of the size field. In this case the array bound is declared as 1, but by convention is really controlled by the value of the size field.  
 
<source lang=c>
 
<source lang=c>
−
#define SOME_BOUND 0
+
 
 
typedef struct {
 
typedef struct {
−
     int nSize;
+
     int size;
−
     int nSomeJunk;
+
     int someJunk;
−
     int ary[SOME_BOUND];
+
     int ary[1]; // variable length array whose length depends on the size
 
} ConformantArraySizedStruct;
 
} ConformantArraySizedStruct;
  
−
extern void f(SimpleSizedStruct* s);
+
#ifdef _SCL
−
#pragma scl_struct_sized(f.s, nSize);
+
#pragma scl_struct_sized(ConformantArraySizedStruct, size)
 +
#endif
 
   
 
   
 
</source>
 
</source>
  
 
== See Also ==
 
== See Also ==
−
* For additional information on scl_string, including constraints, refer to the section on scl_struct_sized in the [[Media:s2sSCLReferenceGuide.pdf|SCL Reference Guide]].
+
* For additional information on scl_struct_sized, including constraints, refer to the section on scl_struct_sized in the [[Media:s2sSCLReferenceGuide.pdf|SCL Reference Guide]].
  
−
[[Category: SCL]]
+
[[Category:Studio:SCL]]

Latest revision as of 14:35, 4 January 2012

The scl_struct_sized pragma

The scl_struct_sized pragma is used to identify a sized structure. A sized structure is a C programming convention for representing a structure whose size is variable and defined by one of the members of the structure. This pragma is infrequently used, but must be used, whenever the programmer defined size does not match the C language size of the structure (as calculated by the sizeof macro).

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

Syntax

#pragma scl_struct_sized(type-name, size-field)
Parameters Type Description
type-name Structure Type Identifies a structure type or structure instance whose runtime size is not the same as its C language size and contains a field whose value is the runtime size.

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 used 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.
  • If the last member of the structure is an array, the array's size is calculated based upon max-size - (size of struct's other members).
size-field Member Identifies a field within the sized structure whose value determines the actual runtime size of the structure. The following restrictions apply:
  • The type of the size-field must be an integral type.
  • The value (at runtime) is expected to be greater than the type size of the structure (as determined by the sizeof macro).
  • The size-field must reside within the same payload block as the sized structure.

Examples

Example 1

This example shows the declaration for a simple sized struct. 

typedef struct {
    int size;
    int someJunk;
    int moreJunk;
} SimpleSizedStruct;

#ifdef _SCL
#pragma scl_struct_sized(SimpleSizedStruct, size)
#endif

Example 2

This example shows the declaration of a sized struct containing a variable length array whose actual length is proportional to the value of the size field. In this case the array bound is declared as 1, but by convention is really controlled by the value of the size field. 

typedef struct {
    int size;
    int someJunk;
    int ary[1];  // variable length array whose length depends on the size
} ConformantArraySizedStruct;

#ifdef _SCL
#pragma scl_struct_sized(ConformantArraySizedStruct, size)
#endif

See Also

  • For additional information on scl_struct_sized, including constraints, refer to the section on scl_struct_sized in the SCL Reference Guide.
Retrieved from "https://www.stridewiki.com/index.php?title=Studio:Scl_struct_sized&oldid=13644"