4.5. Pragmas and Attributes

4.5.1. Pragmas

While the c29clang compiler does support some of the same pragma directives that the cl2000 compiler supports, there are several pragma directives supported by cl2000 that are not supported by c29clang. 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 cl2000 compiler, providing guidance on how to transition each pragma directive for a project to be built with the c29clang compiler.

In general, if there is a c29clang functionally equivalent attribute or pragma form for an cl2000 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 cl2000 and c29clang.

4.5.1.1. cl2000 Pragmas to be Converted to Attribute or Pragma Form

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

  • CODE_ALIGN pragma -> aligned attribute

    cl2000 pragma:

    #pragma CODE_ALIGN(func_name, n)

    c29clang functionally equivalent attribute:

    __attribute__((aligned(n)))

    The CODE_ALIGN pragma aligns the function along the specified alignment boundary. The alignment constant must be a power of 2. The CODE_ALIGN pragma is useful if you have functions that you want to start at a certain boundary.

  • CODE_SECTION pragma -> section attribute

    cl2000 pragma:

    #pragma CODE_SECTION(func_name, "scn_name")

    c29clang 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

    cl2000 pragma:

    #pragma DATA_ALIGN("sym_name", alignment)

    c29clang 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

    cl2000 pragma:

    #pragma DATA_SECTION(sym_name, "scn_name")

    c29clang 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.

  • FORCEINLINE pragma -> [[clang::always_inline]] statement attribute

    cl2000 pragma:

    #pragma FORCEINLINE

    c29clang functionally equivalent attribute:

    [[clang::always_inline]] *statement*;

    The [[clang::always_inline]] statement attribute can be used before a statement to cause any function calls made in that statement to be inlined. It has no effect on other calls to the same functions. It cannot be used as a prefix for a declaration statement, even if that statement calls a function. For example:

    [[clang::always_inline]] myFunc1(); // attempts to inline myFunc1
[[clang::always_inline]] i = myFunc2(); // attempts to inline myFunc2

    The [[clang::always_inline]] attribute is part of the C23 and C++11 standards.

    This attribute does not force inline substitution to occur. The compiler only inlines a function if it is legal to inline the function. Functions are never inlined if the compiler is invoked with the -O0 or -fno-inline-functions option. If the -finline-functions or -O2 (or higher) option is used, the compiler attempts to inline functions even if they are not called with the [[clang::always_inline]] attribute. See Optimization Options for more about inlining.

  • FUNC_ALWAYS_INLINE pragma -> always_inline function attribute

    cl2000 pragma:

    #pragma FUNC_ALWAYS_INLINE(func_name)

    c29clang functionally equivalent attribute:

    __attribute__((always_inline))

    The always_inline attribute instructs the compiler to inline the definition of the function the attribute precedes wherever it is referenced in the C/C++ source code for an application.

  • FUNC_CANNOT_INLINE pragma -> noinline attribute

    cl2000 pragma:

    #pragma FUNC_CANNOT_INLINE(func_name)

    c29clang 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

    cl2000 pragma:

    #pragma LOCATION(address)

    c29clang 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

    cl2000 pragma:

    #pragma NOINIT(sym_name)

    c29clang 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.

  • NOINLINE pragma -> [[clang::noinline]] statement attribute

    cl2000 pragma:

    #pragma NOINLINE

    c29clang functionally equivalent attribute:

    [[clang::noinline]] *statement*;

    The [[clang::noinline]] statement attribute can be used before a statement to prevent any function calls made in that statement from being inlined. It has no effect on other calls to the same functions. It cannot be used as a prefix for a declaration statement, even if that statement calls a function. For example:

    [[clang::noinline]] myFunc1(); // prevents inlining of myFunc1
[[clang::noinline]] i = myFunc2(); // prevents inlining of myFunc2

    The [[clang::noinline]] attribute is part of the C23 and C++11 standards.

    See Optimization Options for more about inlining.

  • PERSISTENT pragma -> persistent attribute

    cl2000 pragma:

    #pragma PERSISTENT(sym_name)

    c29clang 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

    cl2000 pragma:

    #pragma RETAIN(sym_name)

    c29clang 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

    cl2000 pragma:

    #pragma SET_CODE_SECTION("scn_name")

    c29clang 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

    cl2000 pragma:

    #pragma SET_DATA_SECTION("scn_name")

    c29clang 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

    cl2000 pragma:

    #pragma UNROLL(n)

    c29clang functionally equivalent pragmas:

    #pragma clang loop unroll_count(n)

    The c29clang 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

    cl2000 pragma:

    #pragma #pragma WEAK(sym_name)

    c29clang 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.

4.5.1.3. cl2000 Pragmas That Are Not Available in c29clang

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

  • CLINK

#pragma CLINK(sym_name)

  • FORCEINLINE_RECURSIVE

#pragma FORCEINLINE_RECURSIVE)

  • 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)

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

4.5.2. Attributes

Both the cl2000 and c29clang compilers support the notion of attributes that can be applied to functions, variables, or types. The attributes supported in cl2000 and c29clang 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 provides details of which function, variable, and type attributes are supported in both the cl2000 and c29clang compilers. This section also provides details about which attributes are supported in the cl2000 compiler, but not the c29clang 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 c29clang compiler. Finally, this section provides information on additional attributes that are supported in the c29clang compiler, but not the cl2000 compiler.

4.5.2.1. Function Attributes

The function attributes listed below are supported in both the cl2000 and c29clang 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 cl2000, the available “int_kind”s are: DABT, FIQ, IRQ, PABT, RESET, or UNDEF. In c29clang, “int_kind” can be: IRQ, FIQ, SWI, ABORT, or UNDEF.

  • 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 c29clang’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 cl2000 function attributes are not supported in the c29clang compiler:

  • aligned

  • calls

  • deprecated

  • ramfunc

4.5.2.2. Variable Attributes

The variable attributes listed below are supported in both the cl2000 and c29clang 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”.

  • 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. A transparent union can accept an argument of any type that matches that of one of its members without an explicit cast.

Transparent unions are not supported in C++.

  • unused

__attribute__((unused))

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

  • used

__attribute__((retain))
__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 c29clang compiler the used attribute acts as a synonym for the c29clang’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 cl2000 variable attributes are not supported in the c29clang compiler:

  • aligned

  • blocked

  • mode

  • noblocked

  • preserve

  • update

4.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. A transparent union can accept an argument of any type that matches that of one of its members without an explicit cast.

Transparent unions are not supported in C++.

  • unused

__attribute__((unused))

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

The following list of cl2000 type attributes are not supported in the c29clang compiler:

  • byte_peripheral

4.5.2.4. For Loop Attributes

  • TI::unroll for loop attribute -> clang loop unroll pragma

    cl2000 attribute:

    [[TI::unroll(4)]]
for (...)
{
    ...
}

    c29clang functionally equivalent pragma:

    #pragma unroll 4
 for (...)
 {
     ...
 }

The following cl2000 for loop attributes are not supported in the c29clang compiler:

  • TI::must_iterate