3.5. Pragmas and Attributes

3.5.1. Pragmas

While the tiarmclang does support some of the same pragma directives that armcl supports, there are several pragma directives supported by armcl that are not supported in tiarmclang. Some of these can be converted into their functionally equivalent attribute or pragma forms while others may be supported in an indirect way or not supported at all. This section walks through all of the pragma directives that are supported in the armcl compiler, providing guidance on how to transition each pragma directive for a project to be built with the tiarmclang compiler.

In general, if there is a tiarmclang functionally equivalent attribute or pragma form for an armcl pragma directive, these should be converted to attribute or pragma form. The use of GNU-like attributes and pragmas in C/C++ source code is very likely to be portable between armcl and tiarmclang.

3.5.1.1. armcl Pragmas to be Converted to Attribute or Pragma Form

Listed below are several commonly occurring armcl pragmas that, when converted to attribute form, are supported by the tiarmclang compiler.

• CODE_SECTION pragma -> section attribute

  arcml pragma

  #pragma CODE_SECTION(func_name, "scn_name")
  

  tiarmclang functionally equivalent attribute

  __attribute__((section("scn_name")))
  

  The section attribute can be used to instruct the compiler to generate code associated with a function into a section called scn_name.

• DATA_ALIGN pragma -> aligned attribute

  arcml pragma

  #pragma DATA_ALIGN("sym_name", alignment)
  

  tiarmclang functionally equivalent attribute

  __attribute__((aligned(alignment)))
  

  The aligned attribute instructs the compiler to align the address where the data object that the attribute is associated with is defined to a specified alignment boundary (where alignment is indicated in bytes and must be a power of two).

• DATA_SECTION pragma -> section attribute

  arcml pragma

  #pragma DATA_SECTION(sym_name, "scn_name")
  

  tiarmclang functionally equivalent attribute

  __attribute__((section("scn_name")))
  

  The section attribute can be used to instruct the compiler to generate the definition of a data object into a section called scn_name.

• FUNC_ALWAYS_INLINE pragma -> always_inline attribute

  arcml pragma

  #pragma FUNC_ALWAYS_INLINE(func_name)
  

  tiarmclang functionally equivalent attribute

  __attribute__((always_inline))
  

  The always_inline attribute can be used to instruct the compiler to inline the definition of the function the attribute is associated with (func_name) wherever it is referenced in the C/C++ source code for an application.

• FUNC_CANNOT_INLINE pragma -> noinline attribute

  arcml pragma

  #pragma FUNC_CANNOT_INLINE(func_name)
  

  tiarmclang functionally equivalent attribute

  __attribute__((noinline))
  

  The noinline function attribute indicates to the compiler that it should not attempt to inline the function the attribute is associated with (func_name).

• LOCATION pragma -> location attribute

  arcml pragma

  #pragma LOCATION(address)
  

  tiarmclang functionally equivalent attribute

  __attribute__((location(address)))
  

  The location attribute can be used to instruct the compiler to generate information for the linker to dictate the specific memory address where the data object the attribute is associated with (sym_name) is to be placed.

• NOINIT pragma -> noinit attribute

  arcml pragma

  #pragma NOINIT(sym_name)
  

  tiarmclang functionally equivalent attribute

  __attribute__((noinit))
  

  The noinit attribute instructs the compiler to pass instructions to the linker to ensure that a global or static data object that the attribute is associated with (sym_name) does not get initialized at startup or reset.

• PERSISTENT pragma -> persistent attribute

  arcml pragma

  #pragma PERSISTENT(sym_name)
  

  tiarmclang functionally equivalent attribute

  __attribute__((persistent))
  

  The persistent attribute can be applied to a statically initialized data object to indicate to the compiler that the data object that the attribute is associated with (sym_name) need not be initialized at startup. The data object sym_name will be given an initial value when the application is loaded, but it is never again initialized.

• RETAIN pragma -> retain or used attribute

  arcml pragma

  #pragma RETAIN(sym_name)
  

  tiarmclang functionally equivalent attribute

  __attribute__((retain))
  __attribute__((used))
  

  The retain or used attribute, when applied to a function or a data object, indicates to the linker that the section in which the function or data object is defined must be included in the linked application, even if there are no references to the function/data object.

• SET_CODE_SECTION pragma -> clang section text pragma

  armcl pragma

  #pragma SET_CODE_SECTION("scn_name")
  

  tiarmclang functionally equivalent pragma

  #pragma clang section text="scn_name"
  

  This pragma will place enclosed functions within a named section, which can then be placed with the linker using a linker command file. Note that use of the section attribute will take priority over this pragma, and using the pragma means that enclosed functions will not be placed in individual subsections.

  The pragma can be reset by using

  #pragma clang section text=""
  

• SET_DATA_SECTION pragma -> clang section data pragma

  armcl pragma

  #pragma SET_DATA_SECTION("scn_name")
  

  tiarmclang functionally equivalent pragma

  #pragma clang section data="scn_name"
  

  This pragma will place enclosed variables within a named section, which can then be placed with the linker using a linker command file. Note that use of the section attribute will take priority over this pragma, and using the pragma means that enclosed variables will not be placed in individual subsections.

  The pragma can be reset by using

  #pragma clang section data=""
  

• UNROLL pragma -> clang loop unroll pragma

  armcl pragma

  #pragma UNROLL(n)
  

  tiarmclang functionally equivalent pragmas

  #pragma clang loop unroll_count(n)
  

  The tiarmclang compiler supports a clang loop unroll_count(n) pragma, where n is a positive integer indicating the number of times to unroll the loop in question. If the specified value for n is greater than the loop trip count, then the loop will be fully unrolled.

• WEAK pragma -> weak attribute

  arcml pragma

  #pragma #pragma WEAK(sym_name)
  

  tiarmclang functionally equivalent attribute

  __attribute__((weak))
  

  The weak attribute can be used to mark a symbol definition as having weak binding. If a strong definition of the symbol the attribute is associated with (sym_name) is available from an input object file at link time, it will preempt this weak definition. However, if a strong definition of sym_name is available in a referenced archive file, then the linker will not automatically pull in the strong definition from the archive file to preempt the weak definition.

3.5.1.2. pack Pragma

The following pack pragma directives are supported in both the armcl and tiarmclang compilers:

• pack(n)

#pragma pack(n)

The pack pragma instructs the compiler to apply an n-byte alignment to the fields within a class, struct, or union type, where n is an integer value that is also a power of 2. This form of the pack pragma applies to all subsequent class, struct, or union types in the same compilation unit. It forces the maximum alignment of each field to be the value specified by n. If the default alignment of a field is less than n, the alignment is not changed.

• pack(push,n) and pack(pop,n)

#pragma pack(push, n)
#pragma pack(pop)

The push and pop forms of the pack pragma define a region within the C/C++ source code in which the compiler will apply an n-byte maximum alignment to the fields in a class, struct, or union type that is specified within that region, where n is an integer value that is also a power of 2. If the default alignment of a field is less than n, the alignment is not changed.

• pack(show)

#pragma pack(show)

The show form of the pack pragma instructs the compiler to emit a warning to STDERR that displays the current pack alignment value in effect.

3.5.1.3. armcl Pragmas That Are Not Available in tiarmclang

The following armcl pragma directives are not supported by the tiarmclang compiler and don’t have a functionally equivalent attribute form:

• CHECK_MISRA

#pragma CHECK_MISRA("{all|required|advisory|none|rulespec}")

• CHECK_ULP

#pragma CHECK_ULP("{all|none|rulespec}")

• CLINK

#pragma CLINK(sym_name)

• DUAL_STATE

#pragma FUNC_EXT_CALLED(func_name)

• FUNC_EXT_CALLED

#pragma FUNC_EXT_CALLED(func_name)

• FUNCTION_OPTIONS

#pragma FUNCTION_OPTIONS(func_name, "added_opts")

• MUST_ITERATE

#pragma MUST_ITERATE(min[, max[, multiple]])

• NO_HOOKS

#pragma NO_HOOKS(func_name)

• RESET_MISRA

#pragma RESET_MISRA("{all|required|advisory|rulespec}")

• RESET_ULP

#pragma RESET_ULP("{all|rulespec}"

• SWI_ALIAS

#pragma SWI_ALIAS(func_name, swi_number)

• UNROLL

#pragma UNROLL(n)

For more information about these pragmas and how they function, please refer to the Arm Optimizing C/C++ Compiler User’s Guide (section 5.10).

3.5.2. Attributes

Both the armcl and tiarmclang compilers support the notion of attributes that can be applied to functions, variables, or types. The attributes supported in armcl and tiarmclang follow the guidelines for attributes that can be found in the Extensions to the C Language Family section of the GNU Compiler Collection user guide. This section of the Compiler Source Code Compatibility chapter will provide details of which function, variable, and type attributes are supported in both the armcl and tiarmclang compilers. This section will also provide details about which attributes are supported in the armcl compiler, but not the tiarmclang compiler. References to these attributes in your application’s source code will need to be addressed in some way before attempting to compile your application with the tiarmclang compiler. Finally, this section will provide information on additional attributes that are supported in the tiarmclang compiler, but not the armcl compiler.

3.5.2.1. Function Attributes

The function attributes listed below are supported in both the armcl and tiarmclang compilers. Please consult the Declaring Attributes of Functions page of the GNU Compiler Collection for more details about what they do.

• alias

__attribute__((alias("target_fcn"))

Declare function to be an alias of “target_fcn”.

• always_inline

__attribute__((always_inline))

Compiler should inline the definition of this function wherever it is referenced in the application’s source code.

• const

__attribute__((const))

Function has no effect except to compute the return value.

• constructor

__attribute__((constructor))

This function needs to be called/executed before main().

• format

__attribute__((format(archetype, string_index, first_to_check)))

Function takes printf, scanf, strftime, or strfmon style arguments which should be type-checked against a format string. The string_index argument indicates which function argument is the format string. The first_to_check argument indicates the first function argument that is to be checked against the format string.

• format_arg

__attribute__((format_arg(string_index)))

The function argument indicated by string_index is to be interpreted as a format string when passed to a printf, scanf, strftime, or strfmon function that is called from the function that the format_arg attribute is applied to.

• interrupt

__attribute__((interrupt("int_kind")))

In armcl, the available “int_kind”s are: DABT, FIQ, IRQ, PABT, RESET, or UNDEF. In tiarmclang, “int_kind” can be: IRQ, FIQ, SWI, ABORT, or UNDEF.

Note

FPU Registers are Not Automatically Preserved by tiarmclang for Interrupt Functions

The tiarmclang compiler will not generate code to preserve FPU registers in a function marked with the interrupt attribute. If floating-point operations are required in the scope of an interrupt, then the FPU registers must be preserved manually.

• malloc

__attribute__((malloc))

Function may be treated by the compiler as if it were a malloc function.

• naked

__attribute__((naked))

Function is to be treated as an embedded assembly function.

• noinline

__attribute__((noinline))

Compiler should not attempt to inline this function.

• noreturn

__attribute__((noreturn))

Calls to this function will never return to their caller.

• pure

__attribute__((pure))

This function has no effect except to compute the return value which is dependent only on the arguments passed into the function and/or global variables.

• section

__attribute__((section("scn_name"))

Generate code for the definition of this function into a section named “scn_name”.

• unused

__attribute__((unused))

This function might not be used by an application. The attribute can be useful in that the compiler knows not to generate a warning when the function is in fact not used.

• used

__attribute__((used))
__attribute-_((retain))

Generate code for this function even if the compiler knows that there are no references to the function. This attribute is also a synonym for tiarmclang’s retain attribute which tells the linker to include this function in the link whether or not it is referenced elsewhere in the application.

• warn_unused_result

__attribute__((warn_unused_result))

Compiler will generate a warning if any callers to this function do not use the function’s return value.

• weak

__attribute__((warn_unused_result))

The definition of this function is considered “weak” meaning that it will be preempted if a strong definition of the function is encountered among the object files specified to the linker. Note, however, that if a strong definition of the function is contained in a referenced archive, it will not automatically be pulled into the link to preempt the weak definition of the function.

The following list of armcl function attributes are not supported in the tiarmclang compiler:

• builtin

• calls

• deprecated

• impure

• ramfunc

• target

3.5.2.2. Variable Attributes

The variable attributes listed below are supported in both the armcl and tiarmclang compilers. Please consult the Specifying Attributes of Variables page of the GNU Compiler Collection for more details about what they do.

• aligned

__attribute__((aligned(alignment)))

Align this data object to a minimum of the specified alignment argument. The alignment argument must be a power of 2.

• deprecated

__attribute__((deprecated))

If there are references to this data object in the current application, then the compiler should generate a warning about remaining references to this data object which has been marked deprecated.

• location

__attribute__((location(address)))

The compiler will instruct the linker to place this data object at a specific address at link time.

• noinit

__attribute__((noinit))

The compiler will not auto-initialize this data object.

• packed

__attribute__((packed))

The packed attribute can be applied to individual fields within a struct or union. This tells the compiler to relax alignment constraints for a struct or union member that may be larger than a byte in size. A packed member of a struct or union will be aligned on a byte boundary and may require an unaligned load or store instruction to be properly accessed.

• persistent

__attribute__((persistent))

This data object is initialized once and is not re-initialized again in the event of a processor reset.

• section

__attribute__((section("scn_name")))

Generate the definition of this data object into a section named “scn_name”.

• unused

__attribute__((unused))

Avoid generating a diagnostic at compile time if this data object is not referenced.

• used

__attribute__((used))

Retain the definition of this static data object even if it is not referenced in the compilation unit where it is defined. In the tiarmclang compiler the used attribute acts as a synonym for the tiarmclang’s retain attribute which instructs the linker to include the definition of this data object in the link even if it is not referenced elsewhere in the application.

• weak

__attribute__((weak))

The weak attribute marks the definition of the variable that it is being applied to as a “weak” definition, meaning that if a strong definition of the same variable is provided to the link in another input object file, then that definition will preempt the weak definition of the variable. Note, however, that if a strong definition is present in a referenced archive file, the linker will not automatically pull in the strong definition of the variable from the archive to preempt the weak definition.

The following list of armcl variable attributes are not supported in the tiarmclang compiler:

• externally_visible

• memread

• memwrite

3.5.2.3. Type Attributes

• aligned

__attribute__((aligned(alignment)))

The aligned attribute, when applied to a type, instructs the compiler to align the address where a data object is defined of that type to a minimum of the specified alignment argument. The alignment argument must be an integer constant that is a power of 2.

• deprecated

__attribute__((deprecated))

The deprecated attribute instructs the compiler to emit warnings for any references to a type with this attribute. This is useful for finding remaining references to a type that should no longer be used by an application.

• packed

__attribute__((packed))

The packed attribute may be applied to a struct or union type definition. Members of a packed data structure are stored as closely to one another as possible, omitting additional bytes of padding between fields that would have been necessary to preserve alignment of a member within a structure. The packed attribute can only be applied to the original definition of a struct or union type. It cannot be applied with a typedef to a non-packed data structure type that has already been defined, nor can it be applied to the declaration of a struct or union data object.

• transparent_union

__attribute__((transparent_union))

The transparent_union attribute may be applied to the specification of a union type. If a function is declared with a parameter of this union type, then the argument type at the call site to the function determines which member of the union is initialized.

The following list of armcl type attributes are not supported in the tiarmclang compiler:

• unpacked