The compiler translates your source program into machine language object code that the ARM can execute. Source code must be compiled, assembled, and linked to create an executable object file. All of these steps are executed at once by using the compiler.

2.1 About the Compiler

The compiler lets you compile, optimize, assemble, and optionally link in one step. The compiler performs the following steps on one or more source modules:

• The compiler accepts C/C++ source code and assembly code. It produces object code.

You can compile C, C++, and assembly files in a single command. The compiler uses the filename extensions to distinguish between different file types. See Section 2.3.9 for more information.

• The linker combines object files to create an executable object file. The link step is optional, so you can compile and assemble many modules independently and link them later. See Section 4 for information about linking the files.

NOTE

Invoking the Linker

By default, the compiler does not invoke the linker. You can invoke the linker by using the --run_linker (-z)compiler option. See Section 4.1.1 for details.

For a complete description of the assembler and the linker, see the ARM Assembly Language Tools User's Guide.

2.2 Invoking the C/C++ Compiler

For example, if you want to compile two files named symtab.c and file.c, assemble a third file named seek.asm, and link to create an executable program called myprogram.out, you will enter:

armcl symtab.c file.c seek.asm --run_linker --library=lnk.cmd --output_file=myprogram.out

2.3 Changing the Compiler's Behavior with Options

Options control the operation of the compiler. This section provides a description of option conventions and an option summary table. It also provides detailed descriptions of the most frequently used options, including options used for type-checking and assembling.

For a help screen summary of the options, enter armcl with no parameters on the command line.

The following apply to the compiler options:

• There are typically two ways of specifying a given option. The "long form" uses a two hyphen prefix and is usually a more descriptive name. The "short form" uses a single hyphen prefix and a combination of letters and numbers that are not always intuitive.
• Options are usually case sensitive.
• Individual options cannot be combined.
• An option with a parameter should be specified with an equal sign before the parameter to clearly associate the parameter with the option. For example, the option to undefine a constant can be expressed as --undefine=name. Likewise, the option to specify the maximum amount of optimization can be expressed as -O=3. You can also specify a parameter directly after certain options, for example -O3 is the same as -O=3. No space is allowed between the option and the optional parameter, so -O 3 is not accepted.
• Files and options except the --run_linker option can occur in any order. The --run_linker option must follow all compiler options and precede any linker options.

You can define default options for the compiler by using the TI_ARM_C_OPTION environment variable. For a detailed description of the environment variable, see Section 2.4.1.

Table 2-7 through Table 2-28 summarize all options (including link options). Use the references in the tables for more complete descriptions of the options.

2.4 Controlling the Compiler Through Environment Variables

An environment variable is a system symbol that you define and assign a string to. Setting environment variables is useful when you want to run the compiler repeatedly without re-entering options, input filenames, or pathnames.

NOTE

C_OPTION and C_DIR -- The C_OPTION and C_DIR environment variables are deprecated. Use device-specific environment variables instead.

2.5 Controlling the Preprocessor

This section describes features that control the preprocessor, which is part of the parser. A general description of C preprocessing is in section A12 of K&R. The C/C++ compiler includes standard C/C++ preprocessing functions, which are built into the first pass of the compiler. The preprocessor handles:

• Macro definitions and expansions
• #include files
• Conditional compilation
• Various preprocessor directives, specified in the source file as lines beginning with the # character

The preprocessor produces self-explanatory error messages. The line number and the filename where the error occurred are printed along with a diagnostic message.

2.6 Passing Arguments to main()

Some programs pass arguments to main() via argc and argv. This presents special challenges in an embedded program that is not run from the command line. In general, argc and argv are made available to your program through the .args section. There are various ways to populate the contents of this section for use by your program.

To cause the linker to allocate an .args section of the appropriate size, use the --arg_size=size linker option. This option tells the linker to allocate an uninitialized section named .args, which can be used by the loader to pass arguments from the command line of the loader to the program. The size is the number of bytes to be allocated. When you use the --arg_size option, the linker defines the __c_args__ symbol to contain the address of the .args section.

It is the responsibility of the loader to populate the .args section. The loader and the target boot code can use the .args section and the __c_args__ symbol to determine whether and how to pass arguments from the host to the target program. The format of the arguments is an array of pointers to char on the target. Due to variations in loaders, it is not specified how the loader determines which arguments to pass to the target.

If you are using Code Composer Studio to run your application, you can use the Scripting Console tool to populate the .args section. To open this tool, choose View > Scripting Console from the CCS menus. You can use the loadProg command to load an object file and its associated symbol table into memory and pass an array of arguments to main(). These arguments are automatically written to the allocated .args section.

The loadProg syntax is as follows, where file is an executable file and args is an object array of arguments. Use JavaScript to declare the array of arguments before using this command.

loadProg(file, args)

The .args section is loaded with the following data for non-SYS/BIOS-based executables, where each element in the argv[] array contains a string corresponding to that argument:

Int argc; Char * argv[0]; Char * argv[1]; ... Char * argv[n];

For SYS/BIOS-based executables, the elements in the .args section are as follows:

Int argc; Char ** argv; /* points to argv[0] */ Char * envp; /* ignored by loadProg command */ Char * argv[0]; Char * argv[1]; ... Char * argv[n];

For more details, see the "Scripting Console" topic in the TI Processors Wiki.

2.7 Understanding Diagnostic Messages

One of the primary functions of the compiler and linker is to report diagnostic messages for the source program. A diagnostic message indicates that something may be wrong with the program. When the compiler or linker detects a suspect condition, it displays a message in the following format:

" file.c ", line n : diagnostic severity : diagnostic message

Diagnostic messages have a severity, as follows:

• A fatal error indicates a problem so severe that the compilation cannot continue. Examples of such problems include command-line errors, internal errors, and missing include files. If multiple source files are being compiled, any source files after the current one will not be compiled.
• An error indicates a violation of the syntax or semantic rules of the C/C++ language. Compilation may continue, but object code is not generated.
• A warning indicates something that is likely to be a problem, but cannot be proven to be an error. For example, the compiler emits a warning for an unused variable. An unused variable does not affect program execution, but its existence suggests that you might have meant to use it. Compilation continues and object code is generated (if no errors are detected).
• A remark is less serious than a warning. It may indicate something that is a potential problem in rare cases, or the remark may be strictly informational. Compilation continues and object code is generated (if no errors are detected). By default, remarks are not issued. Use the --issue_remarks compiler option to enable remarks.
• Advice provides information about recommended usage. It is not provided in the same way as the other diagnostic categories described here. Instead, it is only available in Code Composer Studio in the Advice area, which is a tab that appears next to the Problems tab. This advice cannot be controlled or accessed via the command line. The advice provided includes suggested settings for the --opt_level and --opt_for_speed options. In addition, messages about suggested code changes from the ULP (Ultra-Low Power) Advisor are provided in this tab.

Diagnostic messages are written to standard error with a form like the following example:

"test.c", line 5: error: a break statement may only be used within a loop or switch break; ^

By default, the source code line is not printed. Use the --verbose_diagnostics compiler option to display the source line and the error position. The above example makes use of this option.

The message identifies the file and line involved in the diagnostic, and the source line itself (with the position indicated by the ^ character) follows the message. If several diagnostic messages apply to one source line, each diagnostic has the form shown; the text of the source line is displayed several times, with an appropriate position indicated each time.

Long messages are wrapped to additional lines, when necessary.

You can use the --display_error_number command-line option to request that the diagnostic's numeric identifier be included in the diagnostic message. When displayed, the diagnostic identifier also indicates whether the diagnostic can have its severity overridden on the command line. If the severity can be overridden, the diagnostic identifier includes the suffix -D (for discretionary); otherwise, no suffix is present. For example:

"Test_name.c", line 7: error #64-D: declaration does not declare anything struct {}; ^ "Test_name.c", line 9: error #77: this declaration has no storage class or type specifier xxxxx; ^

Because errors are determined to be discretionary based on the severity in a specific context, an error can be discretionary in some cases and not in others. All warnings and remarks are discretionary.

For some messages, a list of entities (functions, local variables, source files, etc.) is useful; the entities are listed following the initial error message:

"test.c", line 4: error: more than one instance of overloaded function "f" matches the argument list: function "f(int)" function "f(float)" argument types are: (double) f(1.5); ^

In some cases, additional context information is provided. Specifically, the context information is useful when the front end issues a diagnostic while doing a template instantiation or while generating a constructor, destructor, or assignment operator function. For example:

"test.c", line 7: error: "A::A()" is inaccessible B x; ^ detected during implicit generation of "B::B()" at line 7

Without the context information, it is difficult to determine to what the error refers.

2.8 Other Messages

Other error messages that are unrelated to the source, such as incorrect command-line syntax or inability to find specified files, are usually fatal. They are identified by the symbol >> preceding the message.

2.9 Generating Cross-Reference Listing Information (--gen_cross_reference Option)

The --gen_cross_reference option generates a cross-reference listing file that contains reference information for each identifier in the source file. (The --gen_cross_reference option is separate from --asm_listing_cross_reference, which is an assembler rather than a compiler option.) The cross-reference listing file has the same name as the source file with a .crl extension.

The information in the cross-reference listing file is displayed in the following format:

sym-id name X filename line number column number

2.10 Generating a Raw Listing File (--gen_parser_listing Option)

The --gen_parser_listing option generates a raw listing file that can help you understand how the compiler is preprocessing your source file. Whereas the preprocessed listing file (generated with the --preproc_only, --preproc_with_comment, --preproc_with_line, and --preproc_dependency preprocessor options) shows a preprocessed version of your source file, a raw listing file provides a comparison between the original source line and the preprocessed output. The raw listing file has the same name as the corresponding source file with an .rl extension.

The raw listing file contains the following information:

• Each original source line
• Transitions into and out of include files
• Diagnostic messages
• Preprocessed source line if nontrivial processing was performed (comment removal is considered trivial; other preprocessing is nontrivial)

Each source line in the raw listing file begins with one of the identifiers listed in Table 2-30.

The --gen_parser_listing option also includes diagnostic identifiers as defined in Table 2-31.

Diagnostic raw listing information is displayed in the following format:

2.11 Using Inline Function Expansion

When an inline function is called, a copy of the C/C++ source code for the function is inserted at the point of the call. This is known as inline function expansion, commonly called function inlining or just inlining. Inline function expansion can speed up execution by eliminating function call overhead. This is particularly beneficial for very small functions that are called frequently. Function inlining involves a tradeoff between execution speed and code size, because the code is duplicated at each function call site. Large functions that are called frequently are poor candidates for inlining.

Function inlining is triggered by the following situations:

• The use of built-in intrinsic operations. Intrinsic operations look like function calls, and are inlined automatically, even though no function body exists.
• Use of the inline keyword or the equivalent __inline keyword. Functions declared with the inline keyword may be inlined by the compiler if you set --opt_level=3 (the default) or greater. The inline keyword is a suggestion from the programmer to the compiler. Even if your optimization level is high, inlining is still optional for the compiler. The compiler decides whether to inline a function based on the length of the function, the number of times it is called, your --opt_for_speed setting, and any contents of the function that disqualify it from inlining (see Section 2.11.3). Functions can be inlined at --opt_level=3 if the function body is visible in the same module or if -pm is also used and the function is visible in one of the modules being compiled. Functions may be inlined at link time if the file containing the definition and the call site were both compiled with --opt_level=4.
• Use of static inline functions. Functions defined as both static and inline are more likely to be inlined.
• When --opt_level=3 or greater is used, the compiler may automatically inline eligible functions even if they are not declared as inline functions. The same list of decision factors listed for functions explicitly defined with the inline keyword is used. For more about automatic function inlining, see Section 3.9
• The pragma FUNC_ALWAYS_INLINE forces a function to be inlined (where it is legal to do so) unless --opt_level=off. That is, the pragma FUNC_ALWAYS_INLINE forces function inlining even if --opt_level=0 or --opt_level=1.
• The pragma FUNC_CANNOT_INLINE prevents a function from being inlined.

NOTE

Function Inlining Can Greatly Increase Code Size

Function inlining increases code size, especially inlining a function that is called in a number of places. Function inlining is optimal for functions that are called only from a small number of places and for small functions.

The semantics of the inline keyword in C code follow the C99 standard. The semantics of the inline keyword in C++ code follow the C++ standard.

The inline keyword is supported in all C++ modes, in relaxed ANSI mode for all C standards, and in strict ANSI mode for C99. It is disabled in strict ANSI mode for C89, because it is a language extension that could conflict with a strictly conforming program. If you want to define inline functions while in strict ANSI C89 mode, use the alternate keyword _ _inline.

Compiler options that affect inlining are: --opt_level, --auto_inline, -remove_hooks_when_inlining, and -opt_for_speed.

In most cases, inlining will reduce the code size by a small amount.

2.12 Using Interlist

The compiler tools include a feature that interlists C/C++ source statements into the assembly language output of the compiler. The interlist feature enables you to inspect the assembly code generated for each C statement. The interlist behaves differently, depending on whether or not the optimizer is used, and depending on which options you specify.

The easiest way to invoke the interlist feature is to use the --c_src_interlist option. To compile and run the interlist on a program called function.c, enter:

armcl --c_src_interlist function

The --c_src_interlist option prevents the compiler from deleting the interlisted assembly language output file. The output assembly file, function.asm, is assembled normally.

When you invoke the interlist feature without the optimizer, the interlist runs as a separate pass between the code generator and the assembler. It reads both the assembly and C/C++ source files, merges them, and writes the C/C++ statements into the assembly file as comments.

Using the --c_src_interlist option can cause performance and/or code size degradation.

Example 2-1 shows a typical interlisted assembly file.

For more information about using the interlist feature with the optimizer, see Section 3.10.

2.13 Controlling Application Binary Interface

Application Binary Interface (ABI) defines the low level interface between object files, and between an executable and its execution environment. An ABI allows ABI-compliant object files to be linked together, regardless of their source, and allows the resulting executable to run on any system that supports that ABI.

Object files conforming to different ABIs cannot be linked together. The linker detects this situation and generates an error.

The ARM compiler now supports only the Embedded Application Binary Interface (EABI) ABI, which uses the ELF object format and the DWARF debug format. If you want support for the legacy TI_ARM9_ABI and TIARM ABIs, please use the ARM v5.2 Code Generation Tools and refer to SPNU151J and SPNU118J for documentation.

An industry consortium founded by ARM Ltd defined a standard ABI for binary code intended for the ARM architecture. This ABI is called the Application Binary Interface (ABI) for the ARM Architecture Version 2 (ARM ABIv2). This ABI is also referred to as Embedded Application Binary Interface (EABI). The terms ABIv2 and EABI can be used interchangeably.

For more details on the ABI, see Section 5.12.

2.14 VFP Support

The compiler includes support for generating vector floating-point (VFP) co-processor instructions through the --float_support=vfp option. The VFP co-processor is available in many variants of ARM11 and higher. The valid vfp entries are:

This is the current support for VFP:

• You must link any VFP compiled code with a separate version of the run-time support library. See Section 7.1.8 for information on library-naming conventions.
• The compiler follows the VFP argument passing and returning calling convention for qualified VFP arguments.
• Object files that do not contain any functions with floating point arguments or return values can be linked with both VFP and non-VFP files.
• Object files that do contain functions with floating point arguments or return values can only be linked with objects that were compiled with matching VFP support.
• All hand-coded VFP assembly must follow VFP calling conventions and EABI conventions to correctly compile and link. In addition to these, the appropriate VFP build attributes for EABI must be correctly set.
• The compile-time predefined macro __TI_VFP_SUPPORT__ can be used for conditionally compiling/assembling user code. VFP-specific user code can use this macro to ensure that the conditionally included code is compiled only when VFP is enabled.

Refer to the ARM architecture manual for more details on the VFPv3 and VFPv3D16 architectures and ISAs. Refer to the ARM AAPCS and EABI documents for more details on VFP calling conventions and build attributes.

2.15 Enabling Entry Hook and Exit Hook Functions

An entry hook is a routine that is called upon entry to each function in the program. An exit hook is a routine that is called upon exit of each function. Applications for hooks include debugging, trace, profiling, and stack overflow checking.

Entry and exit hooks are enabled using the following options:

The presence of the hook options creates an implicit declaration of the hook function with the given signature. If a declaration or definition of the hook function appears in the compilation unit compiled with the options, it must agree with the signatures listed above.

In C++, the hooks are declared extern "C". Thus you can define them in C (or assembly) without being concerned with name mangling.

Hooks can be declared inline, in which case the compiler tries to inline them using the same criteria as other inline functions.

Entry hooks and exit hooks are independent. You can enable one but not the other, or both. The same function can be used as both the entry and exit hook.

You must take care to avoid recursive calls to hook functions. The hook function should not call any function which itself has hook calls inserted. To help prevent this, hooks are not generated for inline functions, or for the hook functions themselves.

You can use the --remove_hooks_when_inlining option to remove entry/exit hooks for functions that are auto-inlined by the optimizer.

See Section 5.10.19 for information about the NO_HOOKS pragma.