5.1.1 Implementation-Defined Behavior

The C standard requires that conforming implementations provide documentation on how the compiler handles instances of implementation-defined behavior.

The TI compiler officially supports a freestanding environment. The C standard does not require a freestanding environment to supply every C feature; in particular the library need not be complete. However, the TI compiler strives to provide most features of a hosted environment.

The section numbers in the lists that follow correspond to section numbers in Appendix J of the C99 standard. The numbers in parentheses at the end of each item are sections in the C99 standard that discuss the topic. Certain items listed in Appendix J of the C99 standard have been omitted from this list.

J.3.1 Translation

• The compiler and related tools emit diagnostic messages with several distinct formats. Diagnostic messages are emitted to stderr; any text on stderr may be assumed to be a diagnostic. If any errors are present, the tool will exit with an exit status indicating failure (non-zero). (3.10, 5.1.1.3)
• Nonempty sequences of white-space characters are preserved and are not replaced by a single space character in translation phase 3. (5.1.1.2)

J.3.2 Environment

• The compiler does not support multibyte characters in identifiers, so there is no mapping from multibyte characters to the source character set. However, the compiler accepts multibyte characters in comments, string literals, and character constants in the physical source file. (5.1.1.2)
• The name of the function called at program startup is "main" (5.1.2.1)
• Program termination does not affect the environment; there is no way to return an exit code to the environment. By default, the program is known to have halted when execution reaches the special C$$EXIT label. (5.1.2.1)
• In relaxed ANSI mode, the compiler accepts "void main(void)" and "void main(int argc, char *argv[])" as alternate definitions of main. The alternate definitions are rejected in strict ANSI mode. (5.1.2.2.1)
• If space is provided for program arguments at link time with the --args option and the program is run under a system that can populate the .args section (such as CCS), argv[0] will contain the filename of the executable, argv[1] through argv[argc-1] will contain the command-line arguments to the program, and argv[argc] will be NULL. Otherwise, the value of argv and argc are undefined. (5.1.2.2.1)
• Interactive devices include stdin, stdout, and stderr (when attached to a system that honors CIO requests). Interactive devices are not limited to those output locations; the program may access hardware peripherals that interact with the external state. (5.1.2.3)
• Signals are not supported. The function signal is not supported. (7.14) (7.14.1.1)
• The library function getenv is implemented through the CIO interface. If the program is run under a system that supports CIO, the system performs getenv calls on the host system and passes the result back to the program. Otherwise the operation of getenv is undefined. No method of changing the environment from inside the target program is provided. (7.20.4.5)
• The system function is not supported. (7.20.4.6).

J.3.3. Identifiers

• The compiler does not support multibyte characters in identifiers. (6.4.2)
• The number of significant initial characters in an identifier is unlimited. (5.2.4.1, 6.4.2)

J.3.4 Characters

• The number of bits in a byte (CHAR_BIT) is 8. See Section 5.5 for details about data types. (3.6)
• The execution character set is the same as the basic execution character set: plain ASCII. Characters in the ISO 8859 extended character set are also supported. (5.2.1)
• The values produced for the standard alphabetic escape sequences are as follows: (5.2.2)

Escape Sequence	ASCII Meaning	Integer Value
\a	BEL (bell)	7
\b	BS (backspace)	8
\f	FF (form feed)	12
\n	LF (line feed)	10
\r	CR (carriage return)	13
\t	HT (horizontal tab)	9
\v	VT (vertical tab)	11

• The value of a char object into which any character other than a member of the basic execution character set has been stored is the ASCII value of that character. (6.2.5)
• Plain char is identical to unsigned char, but can be changed to signed char with the --plain_char=signed option. (6.2.5, 6.3.1.1)
• The source character set and execution character set are both plain ASCII, so the mapping between them is one-to-one. The compiler does accept multibyte characters in comments, string literals, and character constants. (6.4.4.4, 5.1.1.2)
• The compiler currently supports only one locale, "C". (6.4.4.4).
• The compiler currently supports only one locale, "C". (6.4.5).

J.3.5 Integers

• No extended integer types are provided. (6.2.5)
• Integer types are represented as two's complement, and there are no trap representations. (6.2.6.2)
• No extended integer types are provided, so there is no change to the integer ranks. (6.3.1.1)
• When an integer is converted to a signed integer type which cannot represent the value, the value is truncated (without raising a signal) by discarding the bits which cannot be stored in the destination type; the lowest bits are not modified. (6.3.1.3)
• Right shift of a signed integer value performs an arithmetic (signed) shift. The bitwise operations other than right shift operate on the bits in exactly the same way as on an unsigned value. That is, after the usual arithmetic conversions, the bitwise operation is performed without regard to the format of the integer type, in particular the sign bit. (6.5)

J.3.6 Floating point

• The accuracy of floating-point operations (+ - * /) is bit-exact. The accuracy of library functions that return floating-point results is not specified. (5.2.4.2.2)
• The compiler does not provide non-standard values for FLT_ROUNDS (5.2.4.2.2)
• The compiler does not provide non-standard negative values of FLT_EVAL_METHOD (5.2.4.2.2)
• The rounding direction when an integer is converted to a floating-point number is IEEE-754 "round to even". (6.3.1.4)
• The rounding direction when a floating-point number is converted to a narrower floating-point number is IEEE-754 "round to even". (6.3.1.5)
• For floating-point constants that are not exactly representable, the implementation uses the nearest representable value. (6.4.4.2)
• The compiler does not contract float expressions. (6.5)
• The default state for the FENV_ACCESS pragma is off. (7.6.1)
• The TI compiler does not define any additional float exceptions (7.6, 7.12)
• The default state for the FP_CONTRACT pragma is off. (7.12.2)
• The "inexact" floating-point exception cannot be raised if the rounded result equals the mathematical result. (F.9)
• The "underflow" and "inexact" floating-point exceptions cannot be raised if the result is tiny but not inexact. (F.9)

J.3.7 Arrays and pointers

• When converting a pointer to an integer or vice versa, the pointer is considered an unsigned integer of the same size, and the normal integer conversion rules apply.
• When converting a pointer to an integer or vice versa, if the bitwise representation of the destination can hold all of the bits in the bitwise representation of the source, the bits are copied exactly. (6.3.2.3)
• The size of the result of subtracting two pointers to elements of the same array is the size of ptrdiff_t, which is defined in Section 5.5. (6.5.6)

J.3.8 Hints

• When the optimizer is used, the register storage-class specifier is ignored. When the optimizer is not used, the compiler will preferentially place register storage class objects into registers to the extent possible. The compiler reserves the right to place any register storage class object somewhere other than a register. (6.7.1)
• The inline function specifier is ignored unless the optimizer is used. For other restrictions on inlining, see Section 2.11.3. (6.7.4)

J.3.9 Structures, unions, enumerations, and bit-fields

• A "plain" int bit-field is treated as a signed int bit-field. (6.7.2, 6.7.2.1)
• In addition to _Bool, signed int, and unsigned int, the compiler allows char, signed char, unsigned char, signed short, unsigned shot, signed long, unsigned long, signed long long, unsigned long long, and enum types as bit-field types. (6.7.2.1)
• Bit-fields may not straddle a storage-unit boundary.(6.7.2.1)
• Bit-fields are allocated in endianness order within a unit. See Section 6.2.2. (6.7.2.1)
• Non-bit-field members of structures are aligned as specified in See Section 6.2.1. (6.7.2.1)
• The integer type underlying each enumerated type is described in Section 5.5.1. (6.7.2.2)

J.3.10 Qualifiers

• The TI compiler does not shrink or grow volatile accesses. It is the user's responsibility to make sure the access size is appropriate for devices that only tolerate accesses of certain widths. The TI compiler does not change the number of accesses to a volatile variable unless absolutely necessary. This is significant for read-modify-write expressions such as += ; for an architecture which does not have a corresponding read-modify-write instruction, the compiler will be forced to use two accesses, one for the read and one for the write. Even for architectures with such instructions, it is not guaranteed that the compiler will be able to map such expressions to an instruction with a single memory operand. It is not guaranteed that the memory system will lock that memory location for the duration of the instruction. In a multi-core system, some other core may write the location after a RMW instruction reads it, but before it writes the result. The TI compiler will not reorder two volatile accesses, but it may reorder a volatile and a non-volatile access, so volatile cannot be used to create a critical section. Use some sort of lock if you need to create a critical section. (6.7.3)

J.3.11 Preprocessing directives

• Include directives may have one of two forms, " " or < >. For both forms, the compiler will look for a real file on-disk by that name using the include file search path. See Section 2.5.2. (6.4.7).
• The value of a character constant in a constant expression that controls conditional inclusion matches the value of the same character constant in the execution character set (both are ASCII). (6.10.1).
• The compiler uses the file search path to search for an included < > delimited header file. See Section 2.5.2. (6.10.2).
• he compiler uses the file search path to search for an included " " delimited header file. See Section 2.5.2. (6.10.2). (6.10.2).
• There is no arbitrary nesting limit for #include processing. (6.10.2).
• See Section 5.10 for a description of the recognized non-standard pragmas. (6.10.6).
• The date and time of translation are always available from the host. (6.10.8).

J.3.12 Library functions

• Almost all of the library functions required for a hosted implementation are provided by the TI library, with exceptions noted in Section 5.15.1. (5.1.2.1).
• The format of the diagnostic printed by the assert macro is "Assertion failed, (assertion macro argument), file file, line line". (7.2.1.1).
• No strings other than "C" and "" may be passed as the second argument to the setlocale function (7.11.1.1).
• No signal handling is supported. (7.14.1.1).
• The +INF, -INF, +inf, -inf, NAN, and nan styles can be used to print an infinity or NaN. (7.19.6.1, 7.24.2.1).
• The output for %p conversion in the fprintf or fwprintf function is the same as %x of the appropriate size. (7.19.6.1, 7.24.2.1).
• The termination status returned to the host environment by the abort, exit, or _Exit function is not returned to the host environment. (7.20.4.1, 7.20.4.3, 7.20.4.4).
• The system function is not supported. (7.20.4.6).

J.3.13 Architecture

• The values or expressions assigned to the macros specified in the headers float.h, limits.h, and stdint.h are described along with the sizes and format of integer types are described in Section 5.5. (5.2.4.2, 7.18.2, 7.18.3)
• The number, order, and encoding of bytes in any object are described in Section 6.2.1. (6.2.6.1)
• The value of the result of the sizeof operator is the storage size for each type, in terms of bytes. See Section 6.2.1. (6.5.3.4)

Table 5-1 ARM C/C++ Data Types

The type of the storage container for an enumerated type is the smallest integer type that contains all the enumerated values. The container types for enumerators are shown in Table 5-2.

The compiler determines the type based on the range of the lowest and highest elements of the enumerator.

For example, the following code results in an enumerator type of int:

For example, the following code results in an enumerator type of short:

5.5.1 Size of Enum Types

An enum type is represented by an underlying integer type. The size of the integer type and whether it is signed is based on the range of values of the enumerated constants.

In strict C89 or C99 mode, the compiler allows only enumeration constants with values that will fit in "int" or "unsigned int".

For C++ and relaxed C89/C99, the compiler allows enumeration constants up to the largest integral type (64 bits). The default, which is recommended, is for the underlying type to be the first type in the following list in which all the enumerated constant values can be represented: int, unsigned int, long, unsigned long long long, unsigned long long.

If you use the --small_enum option, the smallest possible byte size for the enumeration type is used. The underlying type is the first type in the following list in which all the enumerated constant values can be represented: signed char, unsigned char, short, unsigned short, int, unsigned int, long, unsigned long, long long, unsigned long long.

The following enum uses 8 bits instead of 32 bits when the --small_enum option is used.

The following enum fits into 16 bits instead of 32 when the --small_enum option is used.

5.6.1 The const Keyword

The C/C++ compiler supports the ANSI/ISO standard keyword const in all modes.

This keyword gives you greater optimization and control over allocation of storage for certain data objects. You can apply the const qualifier to the definition of any variable or array to ensure that its value is not altered.

Global objects qualified as const are placed in the .const section. The linker allocates the .const section from ROM or FLASH, which are typically more plentiful than RAM. The const data storage allocation rule has two exceptions:

• If the keyword volatile is also specified in the definition of an object (for example, volatile const int x). Volatile keywords are assumed to be allocated to RAM. (The program is not allowed to modify a const volatile object, but something external to the program might.)
• If the object has automatic storage (function scope).

In both cases, the storage for the object is the same as if the const keyword were not used.

The placement of the const keyword within a definition is important. For example, the first statement below defines a constant pointer p to a modifiable int. The second statement defines a modifiable pointer q to a constant int:

Using the const keyword, you can define large constant tables and allocate them into system ROM. For example, to allocate a ROM table, you could use the following definition:

5.6.2 The __interrupt Keyword

The compiler extends the C/C++ language by adding the __interrupt keyword, which specifies that a function is treated as an interrupt function. This keyword is an IRQ interrupt. The alternate keyword, "interrupt", may also be used except in strict ANSI C or C++ modes.

Note that the interrupt function attribute described in Section 5.10.15 is the recommended syntax for declaring interrupt functions.

Functions that handle interrupts follow special register-saving rules and a special return sequence. The implementation stresses safety. The interrupt routine does not assume that the C run-time conventions for the various CPU register and status bits are in effect; instead, it re-establishes any values assumed by the run-time environment. When C/C++ code is interrupted, the interrupt routine must preserve the contents of all machine registers that are used by the routine or by any function called by the routine. When you use the __interrupt keyword with the definition of the function, the compiler generates register saves based on the rules for interrupt functions and the special return sequence for interrupts.

You can only use the __interrupt keyword with a function that is defined to return void and that has no parameters. The body of the interrupt function can have local variables and is free to use the stack or global variables. For example:

The name c_int00 is the C/C++ entry point. This name is reserved for the system reset interrupt. This special interrupt routine initializes the system and calls the main() function. Because it has no caller, c_int00 does not save any registers.

5.6.3 The volatile Keyword

The C/C++ compiler supports the volatile keyword in all modes. In addition, the __volatile keyword is supported in relaxed ANSI mode for C89, C99, and C++.

The volatile keyword indicates to the compiler that there is something about how the variable is accessed that requires that the compiler not use overly-clever optimization on expressions involving that variable. For example, the variable may also be accessed by an external program, an interrupt, another thread, or a peripheral device.

The compiler eliminates redundant memory accesses whenever possible, using data flow analysis to figure out when it is legal. However, some memory accesses may be special in some way that the compiler cannot see, and in such cases you should use the volatile keyword to prevent the compiler from optimizing away something important. The compiler does not optimize out any accesses to variables declared volatile. The number of volatile reads and writes will be exactly as they appear in the C/C++ code, no more and no less and in the same order.

Any variable which might be modified by something external to the obvious control flow of the program (such as an interrupt service routine) must be declared volatile. This tells the compiler that an interrupt function might modify the value at any time, so the compiler should not perform optimizations which will change the number or order of accesses of that variable. This is the primary purpose of the volatile keyword. In the following example, the loop intends to wait for a location to be read as 0xFF:

However, in this example, *ctrl is a loop-invariant expression, so the loop is optimized down to a single-memory read. To get the desired result, define ctrl as:

Here the *ctrl pointer is intended to reference a hardware location, such as an interrupt flag.

The volatile keyword must also be used when accessing memory locations that represent memory-mapped peripheral devices. Such memory locations might change value in ways that the compiler cannot predict. These locations might change if accessed, or when some other memory location is accessed, or when some signal occurs.

Volatile must also be used for local variables in a function which calls setjmp, if the value of the local variables needs to remain valid if a longjmp occurs.

5.8.1 Local Register Variables and Parameters

The C/C++ compiler treats register variables (variables defined with the register keyword) differently, depending on whether you use the --opt_level (-O) option.

• Compiling with optimization

The compiler ignores any register definitions and allocates registers to variables and temporary values by using an algorithm that makes the most efficient use of registers.

• Compiling without optimization

If you use the register keyword, you can suggest variables as candidates for allocation into registers. The compiler uses the same set of registers for allocating temporary expression results as it uses for allocating register variables.

The compiler attempts to honor all register definitions. If the compiler runs out of appropriate registers, it frees a register by moving its contents to memory. If you define too many objects as register variables, you limit the number of registers the compiler has for temporary expression results. This limit causes excessive movement of register contents to memory.

Any object with a scalar type (integral, floating point, or pointer) can be defined as a register variable. The register designator is ignored for objects of other types, such as arrays.

The register storage class is meaningful for parameters as well as local variables. Normally, in a function, some of the parameters are copied to a location on the stack where they are referenced during the function body. The compiler copies a register parameter to a register instead of the stack, which speeds access to the parameter within the function.

For more information about register conventions, see Section 6.3.

5.8.2 Global Register Variables

The C/C++ compiler extends the C language by adding a special convention to the register storage class specifier to allow the allocation of global registers. This special global declaration has the form:

The regid parameter can be __R5, __R6, or __R9. The identifiers _ _R5, _ _R6, and _ _R9 are each bound to their corresponding register R5, R6 and R9, respectively.

When you use this declaration at the file level, the register is permanently reserved from any other use by the optimizer and code generator for that file. You cannot assign an initial value to the register. You can use a #define directive to assign a meaningful name to the register; for example:

There are two reasons that you would be likely to use a global register variable:

• You are using a global variable throughout your program, and it would significantly reduce code size and execution speed to assign this variable to a register permanently.
• You are using an interrupt service routine that is called so frequently that it would significantly reduce execution speed if the routine did not have to save and restore the register(s) it uses every time it is called.

You need to consider very carefully the implications of reserving a global register variable. Registers are a precious resource to the compiler, and using this feature indiscriminately may result in poorer code.

You also need to consider carefully how code with a globally declared register variable interacts with other code, including library functions, that does not recognize the restriction placed on the register.

Because the registers that can be global register variables are save-on-entry registers, a normal function call and return does not affect the value in the register and neither does a normal interrupt. However, when you mix code that has a globally declared register variable with code that does not have the register reserved, it is still possible for the value in the register to become corrupted. To avoid the possibility of corruption, you must follow these rules:

• Functions that alter global register variables cannot be called by functions that are not aware of the global register. Use the -r shell option to reserve the register in code that is not aware of the global register declaration. You must be careful if you pass a pointer to a function as an argument. If the passed function alters the global register variable and the called function saves the register, the value in the register will be corrupted.
• You cannot access a global register variable in an interrupt service routine unless you recompile all code, including all libraries, to reserve the register. This is because the interrupt routine can be called from any point in the program.
• The longjmp ( ) function restores global register variables to the values they had at the setjmp ( ) location. If this presents a problem in your code, you must alter the code for the function and recompile rts.src.

The -r register compiler command-line option allows you to prevent the compiler from using the named register. This lets you reserve the named register in modules that do not have the global register variable declaration, such as the run-time-support libraries, if you need to compile the modules to prevent some of the above occurrences.

5.10.1 The CALLS Pragma

The CALLS pragma specifies a set of functions that can be called indirectly from a specified calling function.

The CALLS pragma is used by the compiler to embed debug information about indirect calls in object files. Using the CALLS pragma on functions that make indirect calls enables such indirect calls to be included in calculations for such functions' inclusive stack sizes. For more information on generating function stack usage information, see the -cg option of the Object File Display Utility in the "Invoking the Object File Display Utility" section of the ARM Assembly Language Tools User's Guide.

The CALLS pragma can precede either the calling function's definition or its declaration. In C, the pragma must have at least 2 arguments—the first argument is the calling function, followed by at least one function that will be indirectly called from the calling function. In C++, the pragma applies to the next function declared or defined, and the pragma must have at least one argument.

The syntax for the CALLS pragma in C is as follows. This indicates that calling_function can indirectly call function_1 through function_n.

The syntax for the CALLS pragma in C++ is:

Note that in C++, the arguments to the CALLS pragma must be the full mangled names for the functions that can be indirectly called from the calling function.

The GCC-style "calls" attribute syntax, which has the same effect as the CALLS pragma, is as follows:

5.10.2 The CHECK_MISRA Pragma

The CHECK_MISRA pragma enables/disables MISRA C:2004 rules at the source level. This pragma is equivalent to using the --check_misra option.

The syntax of the pragma in C is:

The rulespec parameter is a comma-separated list of rule numbers. See Section 5.3 for details.

The RESET_MISRA pragma can be used to reset any CHECK_MISRA pragmas; see Section 5.10.21.

5.10.3 The CHECK_ULP Pragma

The CHECK_ULP pragma enables/disables ULP Advisor rules at the source level. This pragma is equivalent to using the --advice:power option.

The syntax of the pragma in C is:

The rulespec parameter is a comma-separated list of rule numbers. See Section 5.4 for the syntax. See www.ti.com/ulpadvisor for a list of rules.

The RESET_ULP pragma can be used to reset any CHECK_ULP pragmas; see Section 5.10.22.

5.10.4 The CLINK Pragma

The CLINK pragma can be applied to a code or data symbol. It causes a .clink directive to be generated into the section that contains the definition of the symbol. The .clink directive tells the linker that a section is eligible for removal during conditional linking. Thus, if the section is not referenced by any other section in the application being compiled and linked, it will not be included in the resulting output file.

The syntax of the pragma in C is:

The syntax of the pragma in C++ is:

The RETAIN pragma has the opposite effect of the CLINK pragma. See Section 5.10.23 for more details.

5.10.5 The CODE_SECTION Pragma

The CODE_SECTION pragma allocates space for the symbol in C, or the next symbol declared in C++, in a section named section name.

The syntax of the pragma in C is:

The syntax of the pragma in C++ is:

The CODE_SECTION pragma is useful if you have code objects that you want to link into an area separate from the .text section.

The following example demonstrates the use of the CODE_SECTION pragma.

5.10.6 The CODE_STATE Pragma

The CODE_STATE pragma overrides the compilation state of a file, at the function level. For example, if a file is compiled in thumb mode, but you want a function in that file to be compiled in 32-bit mode, you would add this pragma in the file. The compilation state for the function is changed to 16-bit mode (thumb) or 32-bit mode.

The syntax of the pragma is C is:

The syntax of the pragma in C++ is:

5.10.7 The DATA_ALIGN Pragma

The DATA_ALIGN pragma aligns the symbol in C, or the next symbol declared in C++, to an alignment boundary. The alignment boundary is the maximum of the symbol's default alignment value or the value of the constant in bytes. The constant must be a power of 2. The maximum alignment is 32768.

The DATA_ALIGN pragma cannot be used to reduce an object's natural alignment.

The syntax of the pragma in C is:

The syntax of the pragma in C++ is:

5.10.8 The DATA_SECTION Pragma

The DATA_SECTION pragma allocates space for the symbol in C, or the next symbol declared in C++, in a section named section name.

The syntax of the pragma in C is:

The syntax of the pragma in C++ is:

The DATA_SECTION pragma is useful if you have data objects that you want to link into an area separate from the .bss section.

Example 5-4 through Example 5-6 demonstrate the use of the DATA_SECTION pragma.

5.10.9 The Diagnostic Message Pragmas

The following pragmas can be used to control diagnostic messages in the same ways as the corresponding command line options:

The syntax of the diag_suppress, diag_remark, diag_warning, and diag_error pragmas in C is:

Notice that the names of these pragmas are in lowercase.

The diagnostic affected (num) is specified using either an error number or an error tag name. The equal sign (=) is optional. Any diagnostic can be overridden to be an error, but only diagnostic messages with a severity of discretionary error or below can have their severity reduced to a warning or below, or be suppressed. The diag_default pragma is used to return the severity of a diagnostic to the one that was in effect before any pragmas were issued (i.e., the normal severity of the message as modified by any command-line options).

The diagnostic identifier number is output with the message when you use the -pden command line option. The following example suppresses a diagnostic message and then restores the previous diagnostics severity state:

5.10.10 The DUAL_STATE Pragma

By default (that is, without the compiler -md option), all functions with external linkage support dual-state interworking. This support assumes that most calls do not require a state change and are therefore optimized (in terms of code size and execution speed) for calls not requiring a state change. Using the DUAL_STATE pragma does not change the functionality of the dual-state support, but it does assert that calls to the applied function often require a state change. Therefore, such support is optimized for state changes.

The pragma must appear before any declaration or reference to the function that you want to keep. In C, the argument func is the name of the function. In C++, the pragma applies to the next function declared.

The syntax of the pragma in C is:

The syntax of the pragma in C++ is:

For more information on dual-state interworking, see Section 6.11.

5.10.11 The FUNC_ALWAYS_INLINE Pragma

The FUNC_ALWAYS_INLINE pragma instructs the compiler to always inline the named function. The compiler only inlines the function if it is legal to inline the function and the compiler is invoked with any level of optimization (--opt_level=0). See Section 2.11 for details about interaction between various types of inlining.

This pragma must appear before any declaration or reference to the function that you want to inline. In C, the argument func is the name of the function that will be inlined. In C++, the pragma applies to the next function declared.

The syntax of the pragma in C is:

The syntax of the pragma in C++ is:

The following example uses this pragma:

5.10.12 The FUNC_CANNOT_INLINE Pragma

The FUNC_CANNOT_INLINE pragma instructs the compiler that the named function cannot be expanded inline. Any function named with this pragma overrides any inlining you designate in any other way, such as using the inline keyword. Automatic inlining is also overridden with this pragma; see Section 2.11.

The pragma must appear before any declaration or reference to the function that you want to keep. In C, the argument func is the name of the function that cannot be inlined. In C++, the pragma applies to the next function declared.

The syntax of the pragma in C is:

The syntax of the pragma in C++ is:

5.10.13 The FUNC_EXT_CALLED Pragma

When you use the --program_level_compile option, the compiler uses program-level optimization. When you use this type of optimization, the compiler removes any function that is not called, directly or indirectly, by main(). You might have C/C++ functions that are called by hand-coded assembly instead of main().

The FUNC_EXT_CALLED pragma specifies that the optimizer should keep these C functions or any functions these C/C++ functions call. These functions act as entry points into C/C++. The pragma must appear before any declaration or reference to the function to keep. In C, the argument func is the name of the function to keep. In C++, the pragma applies to the next function declared.

The syntax of the pragma in C is:

The syntax of the pragma in C++ is:

Except for _c_int00, which is the name reserved for the system reset interrupt for C/C++programs, the name of the interrupt (the func argument) does not need to conform to a naming convention.

When you use program-level optimization, you may need to use the FUNC_EXT_CALLED pragma with certain options. See Section 3.3.2.

5.10.14 The FUNCTION_OPTIONS Pragma

The FUNCTION_OPTIONS pragma allows you to compile a specific function in a C or C++ file with additional command-line compiler options. The affected function will be compiled as if the specified list of options appeared on the command line after all other compiler options. In C, the pragma is applied to the function specified. In C++, the pragma is applied to the next function.

The syntax of the pragma in C is:

The syntax of the pragma in C++ is:

Supported options for this pragma are --opt_level, --auto_inline, --code_state, and --opt_for_speed. In order to use --opt_level and --auto_inline with the FUNCTION_OPTIONS pragma, the compiler must be invoked with some optimization level (that is, at least --opt_level=0).

5.10.15 The INTERRUPT Pragma

The INTERRUPT pragma enables you to handle interrupts directly with C code. The pragma specifies that the function is an interrupt. The type of interrupt is specified by the pragma; the IRQ (interrupt request) interrupt type is assumed if none is given.

The syntax of the pragma in C is:

The syntax of the pragma in C++ is:

The GCC interrupt attribute syntax, which has the same effects as the INTERRUPT pragma, is as follows. Note that the interrupt attribute can precede either the function's definition or its declaration.

Except for _c_int00, which is the name reserved for the system reset interrupt for C programs, the name of the interrupt (the func argument) does not need to conform to a naming convention.

For the Cortex-M architectures, the interrupt_type can be nothing (default) or SWI. The hardware performs the necessary saving and restoring of context for interrupts. Therefore, the compiler does not distinguish between the different interrupt types. The only exception is for software interrupts (SWIs) which are allowed to have arguments (for Cortex-M architectures, C SWI handlers cannot return values).

5.10.16 The LOCATION Pragma

The compiler supports the ability to specify the run-time address of a variable at the source level. This can be accomplished with the LOCATION pragma or attribute.

The syntax of the pragma in C is:

The syntax of the pragmas in C++ is:

The syntax of the GCC attribute is:

The NOINIT pragma may be used in conjunction with the LOCATION pragma to map variables to special memory locations; see Section 5.10.18.

5.10.17 The MUST_ITERATE Pragma

The MUST_ITERATE pragma specifies to the compiler certain properties of a loop. When you use this pragma, you are guaranteeing to the compiler that a loop executes a specific number of times or a number of times within a specified range.

Any time the UNROLL pragma is applied to a loop, MUST_ITERATE should be applied to the same loop. For loops the MUST_ITERATE pragma's third argument, multiple, is the most important and should always be specified.

Furthermore, the MUST_ITERATE pragma should be applied to any other loops as often as possible. This is because the information provided via the pragma (especially the minimum number of iterations) aids the compiler in choosing the best loops and loop transformations (that is, nested loop transformations). It also helps the compiler reduce code size.

No statements are allowed between the MUST_ITERATE pragma and the for, while, or do-while loop to which it applies. However, other pragmas, such as UNROLL, can appear between the MUST_ITERATE pragma and the loop.

5.10.18 The NOINIT and PERSISTENT Pragmas

Global and static variables are zero-initialized. However, in applications that use non-volatile memory, it may be desirable to have variables that are not initialized. Noinit variables are global or static variables that are not zero-initialized at startup or reset.

Persistent and noinit variables behave identically with the exception of whether or not they are initialized at load time.

The NOINIT pragma may be used in conjunction with the LOCATION pragma to map variables to special memory locations, like memory-mapped registers, without generating unwanted writes. The NOINIT pragma may only be used with uninitialized variables.

The PERSISTENT pragma is similar to the NOINIT pragma, except that it may only be used with statically-initialized variables. Persistent variables disable startup initialization; they are given an initial value when the code is loaded, but are never again initialized.

If you are using non-volatile RAM, you can define a persistent variable with an initial value of zero loaded into RAM. The program can increment that variable over time as a counter, and that count will not disappear if the device loses power and restarts, because the memory is non-volatile and the boot routines do not initialize it back to zero. For example:

The syntax of the pragmas in C is:

The syntax of the pragmas in C++ is:

The syntax of the GCC attributes is:

5.10.19 The NO_HOOKS Pragma

The NO_HOOKS pragma prevents entry and exit hook calls from being generated for a function.

The syntax of the pragma in C is:

The syntax of the pragma in C++ is:

See Section 2.15 for details on entry and exit hooks.

5.10.20 The pack Pragma

The pack pragma can be used to control the alignment of fields within a class, struct, or union type. The syntax of the pragma in C/C++ can be any of the following.

The above form of the pack pragma affects all class, struct, or union type declarations that follow this pragma in a file. It forces the maximum alignment of each field to be the value specified by n. Valid values for n are 1, 2, 4, 8, and 16 bytes.

The above form of the pack pragma affects only class, struct, and union type declarations between push and pop directives. (A pop directive with no prior push results in a warning diagnostic from the compiler.) The maximum alignment of all fields declared is n. Valid values for n are 1, 2, 4, 8, and 16 bytes.

The above form of the pack pragma sends a warning diagnostic to stderr to record the current state of the pack pragma stack. You can use this form while debugging.

For more about packed fields, see Section 5.16.4.

5.10.21 The RESET_MISRA Pragma

The RESET_MISRA pragma resets the specified MISRA C:2004 rules to the state they were before any CHECK_MISRA pragmas (see Section 5.10.2) were processed. For instance, if a rule was enabled on the command line but disabled in the source, the RESET_MISRA pragma resets it to enabled. This pragma accepts the same format as the --check_misra option, except for the "none" keyword.

The syntax of the pragma in C is:

The rulespec parameter is a comma-separated list of rule numbers. See Section 5.3 for details.

5.10.22 The RESET_ULP Pragma

The RESET_ULP pragma resets the specified ULP Advisor rules to the state they were before any CHECK_ULP pragmas (see Section 5.10.3) were processed. For instance, if a rule was enabled on the command line but disabled in the source, the RESET_ULP pragma resets it to enabled. This pragma accepts the same format as the --advice:power option, except for the "none" keyword.

The syntax of the pragma in C is:

The rulespec parameter is a comma-separated list of rule numbers. See Section 5.4 for details. See www.ti.com/ulpadvisor for a list of rules.

5.10.23 The RETAIN Pragma

The RETAIN pragma can be applied to a code or data symbol. It causes a .retain directive to be generated into the section that contains the definition of the symbol. The .retain directive indicates to the linker that the section is ineligible for removal during conditional linking. Therefore, regardless whether or not the section is referenced by another section in the application that is being compiled and linked, it will be included in the output file result of the link.

The syntax of the pragma in C is:

The syntax of the pragma in C++ is:

The CLINK pragma has the opposite effect of the RETAIN pragma. See Section 5.10.4 for more details.

5.10.24 The SET_CODE_SECTION and SET_DATA_SECTION Pragmas

These pragmas can be used to set the section for all declarations below the pragma.

The syntax of the pragmas in C/C++ is:

In Example 5-7 x and y are put in the section mydata. To reset the current section to the default used by the compiler, a blank parameter should be passed to the pragma. An easy way to think of the pragma is that it is like applying the CODE_SECTION or DATA_SECTION pragma to all symbols below it.

The pragmas apply to both declarations and definitions. If applied to a declaration and not the definition, the pragma that is active at the declaration is used to set the section for that symbol. Here is an example:

In Example 5-8 func1 is placed in section func1. If conflicting sections are specified at the declaration and definition, a diagnostic is issued.

The current CODE_SECTION and DATA_SECTION pragmas and GCC attributes can be used to override the SET_CODE_SECTION and SET_DATA_SECTION pragmas. For example:

In Example 5-9 x is placed in x_data and y is placed in mydata. No diagnostic is issued for this case.

The pragmas work for both C and C++. In C++, the pragmas are ignored for templates and for implicitly created objects, such as implicit constructors and virtual function tables.

5.10.25 The SWI_ALIAS Pragma

The SWI_ALIAS pragma allows you to refer to a particular software interrupt as a function name and to invocations of the software interrupt as function calls. Since the function name is simply an alias for the software interrupt, no function definition exists for the function name.

The syntax of the pragma in C is:

The syntax of the pragma in C++ is:

Calls to the applied function are compiled as software interrupts whose number is swi_number. The swi_number variable must be an integer constant.

A function prototype must exist for the alias and it must occur after the pragma and before the alias is used. Software interrupts whose number is not known until run time are not supported.

For information about using the GCC function attribute syntax to declare function aliases, see Section 5.16.2

For more information about using software interrupts, including restrictions on passing arguments and register usage, see Section 6.7.5.

5.10.26 The TASK Pragma

The TASK pragma specifies that the function to which it is applied is a task. Tasks are functions that are called but never return. Typically, they consist of an infinite loop that simply dispatches other activities. Because they never return, there is no need to save (and therefore restore) registers that would otherwise be saved and restored. This can save RAM space, as well as some code space.

The syntax of the pragma in C is:

The syntax of the pragma in C++ is:

5.10.27 The UNROLL Pragma

The UNROLL pragma specifies to the compiler how many times a loop should be unrolled. The optimizer must be invoked (use --opt_level=[1|2|3] or -O1, -O2, or -O3) in order for pragma-specified loop unrolling to take place. The compiler has the option of ignoring this pragma.

No statements are allowed between the UNROLL pragma and the for, while, or do-while loop to which it applies. However, other pragmas, such as MUST_ITERATE, can appear between the UNROLL pragma and the loop.

The syntax of the pragma for C and C++ is:

5.10.28 The WEAK Pragma

The WEAK pragma gives weak binding to a symbol.

The syntax of the pragma in C is:

The syntax of the pragma in C++ is:

The WEAK pragma makes symbol a weak reference if it is a reference, or a weak definition, if it is a definition. The symbol can be a data or function variable. In effect, unresolved weak references do not cause linker errors and do not have any effect at run time. The following apply for weak references:

• Libraries are not searched to resolve weak references. It is not an error for a weak reference to remain unresolved.
• During linking, the value of an undefined weak reference is:
  • Zero if the relocation type is absolute
  • The address of the place if the relocation type is PC-relative
  • The address of the nominal base address if the relocation type is base-relative.

A weak definition does not change the rules by which object files are selected from libraries. However, if a link set contains both a weak definition and a non-weak definition, the non-weak definition is always used.

Table 5-3 ARM Intrinsic Support by Target

Table 5-4 ARM Compiler Intrinsics

5.15.1 Enabling C99 Mode (--c99)

The compiler supports the 1999 standard of C as standardized by the ISO. However, the following list of run-time functions and features are not implemented or fully supported:

• complex.h
• ctype.h
  • isblank()
• inttypes.h
  • wcstoimax() / wcstoumax()
• stdarg.h
  • va_copy macro
• stdio.h
  • %a and %A format specifiers for hexadecimal float
  • The %e specifier may produce "-0" when "0" is expected by the standard
  • snprintf() does not properly pad with spaces when writing to a wide character array
• stdlib.h
  • strtof() atof() / strtod() / strtold() do not support hexadecimal float strings
  • vfscanf() / vscanf() / vsscanf() return value on floating point matching failure is incorrect
• tgmath.h
• time.h
  • strftime()
• wchar.h
  • getws() / fputws()
  • mbrlen()
  • mbsrtowcs()
  • wcscat()
  • wcschr()
  • wcscmp() / wcsncmp()
  • wcscpy() / wcsncpy()
  • wcsftime()
  • wcsrtombs()
  • wcsstr()
  • wcstok()
  • wcsxfrm()
  • Wide character print / scan functions
  • Wide character conversion functions

5.15.2 Enabling Strict ANSI/ISO Mode and Relaxed ANSI/ISO Mode (--strict_ansi and --relaxed_ansi Options)

Under relaxed ANSI/ISO mode (the default), the compiler accepts language extensions that could potentially conflict with a strictly conforming ANSI/ISO C/C++ program. Under strict ANSI mode, these language extensions are suppressed so that the compiler will accept all strictly conforming programs.

Use the --strict_ansi option when you know your program is a conforming program and it will not compile in relaxed mode. In this mode, language extensions that conflict with ANSI/ISO C/C++ are disabled and the compiler will emit error messages where the standard requires it to do so. Violations that are considered discretionary by the standard may be emitted as warnings instead.

Examples:

The following is strictly conforming C code, but will not be accepted by the compiler in the default relaxed mode. To get the compiler to accept this code, use strict ANSI mode. The compiler will suppress the interrupt keyword language exception, and interrupt may then be used as an identifier in the code.

The following is not strictly conforming code. The compiler will not accept this code in strict ANSI mode. To get the compiler to accept it, use relaxed ANSI mode. The compiler will provide the interrupt keyword extension and will accept the code

The following code is accepted in all modes. The __interrupt keyword does not conflict with the ANSI/ISO C standard, so it is always available as a language extension.

The default mode is relaxed ANSI. This mode can be selected with the --relaxed_ansi (or -pr) option. Relaxed ANSI mode accepts the broadest range of programs. It accepts all TI language extensions, even those which conflict with ANSI/ISO, and ignores some ANSI/ISO violations for which the compiler can do something reasonable. The GCC language extensions described in Section 5.16 are available in relaxed ANSI/ISO mode.

5.16.1 Extensions

Most of the GCC language extensions are available in the TI compiler when compiling in relaxed ANSI mode (--relaxed_ansi).

The extensions that the TI compiler supports are listed in Table 5-5, which is based on the list of extensions found at the GNU web site. The shaded rows describe extensions that are not supported.

5.16.2 Function Attributes

The following GCC function attributes are supported:

• alias
• always_inline
• const
• constructor
• deprecated
• format
• format_arg
• interrupt
• malloc
• noinline
• noreturn
• pure
• ramfunc
• section
• unused
• used
• visibility
• warn_unused_result

For example, this function declaration uses the alias attribute to make "my_alias" a function alias for the "myFunc" function:

The format attribute is applied to the declarations of printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf, scanf, fscanf, vfscanf, vscanf, vsscanf, and sscanf in stdio.h. Thus when GCC extensions are enabled, the data arguments of these functions are type checked against the format specifiers in the format string argument and warnings are issued when there is a mismatch. These warnings can be suppressed in the usual ways if they are not desired.

See Section 5.10.15 for more about the interrupt function attribute.

The malloc attribute is applied to the declarations of malloc, calloc, realloc and memalign in stdlib.h.

The ramfunc attribute specifies that a function will be placed in and executed from RAM. The ramfunc attribute allows the compiler to optimize functions for RAM execution, as well as to automatically copy functions to RAM on flash-based devices. For example:

The --ramfunc=on option specifies that all functions compiled with this option are placed in and executed from RAM, even if this function attribute is not used.

Newer TI linker command files support the ramfunc attribute automatically by placing functions with this attribute in the .TI.ramfunc section. If you have a linker command file that does not include a section specification for the .TI.ramfunc section, you can modify the linker command file to place this section in RAM. See the Placing functions in RAM wiki page for more about the ramfunc attribute and option. See the ARM Assembly Language Tools User's Guide for details on section placement.

5.16.3 Variable Attributes

The following variable attributes are supported: aligned, deprecated, mode, noinit, persistent, section, transparent_union, unused, used, and weak.

The used attribute is defined in GCC 4.2 (see https://gcc.gnu.org/onlinedocs/gcc-4.2.4/gcc/Variable-Attributes.html#Variable-Attributes).

In addition, the packed attribute may be applied to individual fields within a struct or union. The packed attribute is supported on all ARM targets. See the description of the --unaligned_access option for more information on how the compiler accesses unaligned data.

5.16.4 Type Attributes

The following type attributes are supported: aligned, deprecated, packed, transparent_union, unused, and visibility.

The packed attribute is supported for struct and union types. It is supported on all ARM targets if the --relaxed_ansi option is used. See the description of the --unaligned_access option for more information on how the compiler accesses unaligned data.

Members of a packed structure are stored as closely to each other as possible, omitting additional bytes of padding usually added to preserve word-alignment. For example, assuming a word-size of 4 bytes ordinarily has 3 bytes of padding between members c1 and i, and another 3 bytes of trailing padding after member c2, leading to a total size of 12 bytes:

However, the members of a packed struct are byte-aligned. Thus the following does not have any bytes of padding between or after members and totals 6 bytes:

Subsequently, packed structures in an array are packed together without trailing padding between array elements.

Bit fields of a packed structure are bit-aligned. The byte alignment of adjacent struct members that are not bit fields does not change. However, there are no bits of padding between adjacent bit fields.

The packed attribute can only be applied to the original definition of a structure or union type. It cannot be applied with a typedef to a non-packed structure that has already been defined, nor can it be applied to the declaration of a struct or union object. Therefore, any given structure or union type can only be packed or non-packed, and all objects of that type will inherit its packed or non-packed attribute.

The packed attribute is not applied recursively to structure types that are contained within a packed structure. Thus, in the following example the member s retains the same internal layout as in the first example above. There is no padding between c and s, so s falls on an unaligned boundary:

It is illegal to implicitly or explicitly cast the address of a packed struct member as a pointer to any non-packed type except an unsigned char. In the following example, p1, p2, and the call to foo are all illegal.

However, it is legal to explicitly cast the address of a packed struct member as a pointer to an unsigned char:

The TI compiler also supports an unpacked attribute for an enumeration type to allow you to indicate that the representation is to be an integer type that is no smaller than int; in other words, it is not packed.

5.16.5 Built-In Functions

The following built-in functions are supported: __builtin_abs, __builtin_classify_type, __builtin_constant_p, __builtin_expect, __builtin_fabs, __builtin_fabsf, __builtin_frame_address, __builtin_labs, __builtin_llabs, __builtin_sqrt, __builtin_sqrtf, __builtin_memcpy, and __builtin_return_address.

The __builtin_frame_address function returns zero unless the argument is a constant zero.

The __builtin_return_address function always returns zero.