2. Using the c29clang Compiler and Linker

2.1. Using the Compiler and Linker

Both the TI C29x Clang (c29clang) Compiler Tools’ compiler and linker can be invoked from the c29clang command-line. The following subsections describe the basics of how to manage the compile and link steps of building an application from the c29clang command-line.

2.1.1. Compiling and Linking

The default behavior of the c29clang compiler is to compile specified C and C++ source files into temporary object files, and then pass those object files along with any explicitly specified object files and any specified linker options to the linker.

c29clang [options] [source file names] [object file names] [-Wl,<linker options>]

In the following example, assume that the C code in file1.c references a data object that is defined in an object file named file2.o. The specified c29clang command compiles file1.c into a temporary object file. That object file, along with file2.o and a linker command file, link_test.cmd, are sent to the linker and linked with applicable object files from the c29clang runtime libraries to create an executable output file named test.out:

c29clang -mcpu=c29.c0 file1.c file2.o -o test.out -Wl,link_test.cmd

Note that there is no mention of the c29clang runtime libraries on the c29clang command-line or inside the link_test.cmd linker command file. When the linker is invoked from the c29clang command-line, the c29clang compiler implicitly tells the linker where to find applicable runtime libraries, such as the C runtime library (libc.a).

In the above c29clang command-line, the -Wl, prefix in front of the specification of the link_test.cmd file name indicates to the compiler that the link_test.cmd file should be sent directly to the TI linker (you can also use the -Xlinker prefix for this purpose).

2.1.2. Compiling and Linking with Verbose Linker Output

If you add the verbose (-v) option to the above c29clang command, you will see exactly how the linker (c29lnk) is invoked and with what options. For example, this command:

c29clang -mcpu=c29.c0 -v file1.c file2.o -o test.out -Wl,link_test.cmd

shows the following with regards to how the c29lnk command is invoked by the c29clang compiler:

<install directory>/bin/c29lnk -I<install directory>/lib
-o test.out /tmp/file1-98472f.o file2.o link_test.cmd
--start-group -llibc++.a -llibc++abi.a -llibc.a -llibsys.a
-llibsysbm.a -llibclang_rt.builtins.a -llibclang_rt.profile.a --end-group

In the above invocation of the linker, the compiler inserts a -I<install directory>/lib option, which tells the linker where to find the c29clang runtime libraries. The compiler also inserts the --start_group/--end_group option list, which specifies exactly which runtime libraries to incorporate into the link.

2.1.3. Compiling Only

You can avoid invoking the linker by specifying the -c option on the c29clang command-line.

c29clang -c [options] [source file names]

The following example generates object files file1.o and file2.o from the C files file1.c and file2.c, respectively:

c29clang -c -mcpu=c29.c0 file1.c file2.c

2.2. Useful Compiler Options

The commonly used options listed in the subsections below are available on the c29clang compiler command-line.

2.2.1. Processor Options

  • -mcpu - select the target processor version

The c29clang compiler supports the following C29x processor variant:

  • -mcpu=c29.c0

If an -mcpu variant is not specified on the c29clang command-line, the compiler assumes a default of -mcpu=c29.c0.

2.2.3. Endianness

C29x devices are little-endian.

2.2.4. Floating-Point Support Options

Native support for 32-bit floating-point operations is always provided for C29x. Optionally, you can also enable 64-bit hardware instructions for floating-point operations using the -mfpu option, which can have either of the following settings:

  • -mfpu=none - Use native 32-bit floating-point hardware operations, but emulate 64-bit floating-point operations in software.

  • -mfpu=f64 - Use native 32-bit and 64-bit floating-point hardware operations.

2.2.5. Include Options

The c29clang compiler utilizes the include file directory search path to locate header files that are included by a C/C++ source file via #include preprocessor directives. The c29clang compiler implicitly defines an initial include file directory search path to contain directories relative to the tools installation area where C/C++ standard header files can be found. These C/C++ standard header files are considered part of the c29clang compiler package and should be used in combination with linker and the runtime libraries that are included in the c29clang compiler tools installation.

  • -I<dir>

    The -I option allows you to add your own directories to the include file directory path, allowing user-created header files to be easily accessible during compilation.

2.2.6. Predefined Symbol Options

In addition to the pre-defined macro symbols that the c29clang compiler defines depending on which processor options are selected, you can also manage your own symbols at compile-time using the -D and -U options. These options are useful when the source code is configured to behave differently based on whether a compile-time symbol is defined and/or what value it has.

  • -D<name>[=<value>]

    A user-created pre-defined compile symbol can be defined and given a value using the -D option. In the following example, MySym is defined and given a value 123 at compile-time. MySym will then be available for use during the compilation of the test.c source file.

c29clang -mcpu=c29.c0 -DMySym=123 -c test.c

  • -U<name>

    The -U option can be used to cancel a previous definition of a specified <name> whether it was pre-defined implicitly by the compiler or with a prior -D option.

2.2.7. Optimization Options

To enable optimization passes in the c29clang compiler, select a level of optimization from among the following -O[0|1|2|3|fast|g|s|z] options. In general, the options below represent various levels of optimization with some options designed to favor smaller compiler-generated code size over performance, while others favor performance at the cost of increased compiler-generated code size.

Among the options listed below, -Oz is recommended as the optimization option to use if small compiler-generated code size is a priority for an application. Using -Oz retains performance gains from many of the -O2 level optimizations that are performed.

  • -O0 - No optimization. This setting is not recommended, because it can make debugging difficult.

  • -O1 or -O - Restricted optimizations, providing a good trade-off between code size and debuggability.

  • -O2 - Most optimizations enabled; some optimizations that require significant additional compile time are disabled.

  • -O3 - All optimizations available at -O2 plus others that require additional compile time to perform.

  • -Ofast - All optimizations available at -O3 plus additional aggressive optimizations with potential for additional performance gains, but also not guaranteed to be in strict compliance with language standards.

  • -Og - Restricted optimizations while preserving debuggability. All optimizations available at -O1 are performed with the addition of some optimizations from -O2.

  • -Os - All optimizations available at -O2 plus additional optimizations that are designed to reduce code size while mitigating negative impacts on performance.

  • -Oz - All optimizations available at -O2 plus additional optimizations to further reduce code size with the risk of sacrificing performance.

Note

Optimization Option Recommendations:

  • The -O1 option is recommended for maximum debuggability.

  • The -Oz option is recommended for optimizing code size.

  • The -O3 option is recommended for optimizing performance, but it is likely to increase compiler-generated code size.

2.2.8. Debug Options

The c29clang compiler generates DWARF debug information when the -g or -gdwarf-3 option is selected.

  • -g or -gdwarf-3 - emit DWARF version 3 debug information

2.2.9. Control Options

Some c29clang compiler options can be used to halt compilation at different stages:

  • -c - stop compilation after emitting compiler-generated object files; do not call linker

  • -E - stop compilation after the pre-processing phase of the compiler; this option can be used in conjunction with several other options that provide further control over the pre-processor output:

    • -dD - print macro definitions in addition to normal preprocessor output

    • -dI - print include directives in addition to normal preprocessor output

    • -dM - print macro symbol definitions instead of normal preprocessor output

  • -S - stop compilations after emitting compiler-generated assembly files; do not call assembler or linker

2.2.10. Compiler Output Option

  • -o<file>

    The -o option names the output file that results from a c29clang command. If c29clang is used to compile and link an executable output file, then the -o option’s <file> argument names that output file. If no -o option is specified in a compile and link invocation of c29clang then the linker will produce an executable output file named a.out.

    If the compiler is used to process a single source file, then the -o option will name the output of the compilation. This is sometimes useful in case there is a need to name the output file from the compiler something other than what the compiler will produce by default. In the following example, the output object file from the compilation of C source file task_42.c is named task.o by the -o option, replacing the task_42.o that would normally be generated by the compiler:

c29clang -mcpu=c29.c0 -c task_42.c -o task.o

2.2.11. Source File Interpretation Option

The c29clang compiler interprets source files with a recognized file extension in a predictable manner. The recognized file extensions include:

  • .c - C source file

  • .C or .cpp - C++ source file

The c29clang compiler also supports a -x <language> option that permits you to dictate how subsequent input files on the command-line are to be treated by the compiler. This can be used to override default file extension interpretations or to instruct the compiler how to interpret a file extension that is not automatically recognized by the compiler. The following <language> types are available with the -x option:

  • -x none - reset compiler to default file extension interpretation

  • -x c - interpret subsequent input files as C source files

  • -x c++ - interpret subsequent input files as C++ source files

Note

The -x<language> option is position-dependent. A given -x option on the c29clang command-line will be in effect until the end of the command-line or until a subsequent -x option is encountered on the command-line.

2.3. Linker Options

2.3.2. Basic Linker Options

Listed below are some of the basic options that are commonly used when invoking the linker. They can be specified on the command-line or inside of a linker command file. The c29clang tool’s linker is nearly identical to the linker in the proprietary TI compiler toolchain. You can find more information about linker options in Linker Options.

  • --map_file=<file> or -m<file> - emit information about the result of a link into the specified map <file>

  • --output_file=<file> or -o<file> - emit linked output to specified <file>

  • --args_size=<size> or --args=<size> - reserve <size> bytes of space to store command-line arguments that are passed to the linked application

  • --heap_size=<size> or --heap=<size> - reserve <size> bytes of heap space to be used for dynamically allocated memory

  • --stack_size=<size> or --stack=<size> - reserve <size> bytes of stack space for the run-time execution of the linked application

2.3.3. Specifying Linker Options on the c29clang Command-Line

As noted in a few of the above examples, when invoking the linker from the c29clang command, options that are to be passed directly to the linker must be preceded with a -Wl, (note that the comma is required) or -Xlinker prefix. In this example, the c29clang compiler passes the link_test.cmd linker command file directly to the linker:

c29clang -mcpu=c29.c0 file1.c file2.o -o test.out -Wl,link_test.cmd

The c29clang command line provides the following ways to pass options to the linker:

  • The -Wl, option passes a comma-separated list of options to the linker. (A comma after -Wl is required.)

  • The -Xlinker option passes a single option to the linker and can be used multiple times on the same command line.

  • A linker command file can specify options to pass to the linker.

For example, the following command line passes several linker options using the -Wl, option:

c29clang -mcpu=c29.c0 hello.c -o a.out -Wl,-stack=0x8000,--ram_model,link_test.cmd

The following command line passes the same linker options using the -Xlinker option instead:

c29clang -mcpu=c29.c0 hello.c -o a.out -Xlinker -stack=0x8000 -Xlinker --ram_model -Xlinker link_test.cmd

The following lines from a linker command file, pass the same linker options to the linker:

/*********************************************************************/
/* Example Linker Command File                                       */
/*********************************************************************/
-stack  0x8000                  /* SOFTWARE STACK SIZE               */
--ram_model                     /* INITIALIZE VARIABLES AT LOAD TIME */

2.4. Runtime Support

2.4.1. Predefined Macro Symbols

The c29clang compiler pre-defines compile-time macro symbols for use in source to help distinguish code written particularly for C29x, for a specific C29x processor variant, or to be compiled by the c29clang compiler (as opposed to other C29x compilers) from other source code.

The c29clang compiler pre-defines several TI-specific and C29-specific pre-defined macro symbols that can be used to distinguish the use of the c29clang compiler from other C29x compilers. These include:

__ti__            1     - identify compiler vendor as TI
__ti_major__      1     - identify major version number
__ti_minor__      0     - identify minor version number
__ti_patchlevel__ 0     - identify patch version number
__ti_version__    10000 - (__ti_major__*10000)+(__ti_minor__*100)+__ti_patchlevel
__C29_ARCH__      0
__C29_C0__        1
__C29_OPTF64__    1
__C29__           1
__c29__           1

For a complete list of pre-defined macro symbols that are defined by the c29clang compiler for a given compilation, the processor options can be combined with the -E -dM preprocessor option combination. This will instruct the compiler to run only the preprocessor pass of the compilation and emit the list of pre-defined macro symbols that are defined along with their values to stdout.

2.4.2. Header Files

The header files provided with the installation of the c29clang compiler tools must be used when using functions from any of the runtime libraries provided with the tools installation. These include the C and C++ standard header files. The c29clang compiler implicitly defines the initial include file directory search path so that these header files are accessible during a compilation.

2.4.3. Runtime Libraries

When linking an application containing object files that were generated by the c29clang compiler, the appropriate c29clang runtime libraries must be included in the link so that references to functions and data objects that are defined in the runtime libraries can be properly resolved at link time.

When the c29clang command is used to invoke the linker, the compiler implicitly defines the initial object file directory search path to contain directories relative to the tools installation area where runtime libraries can be found. The c29clang compiler also implicitly adds the following --start-group/--end-group option list to the linker invocation:

--start-group -llibc++.a -llibc++abi.a -llibc.a -llibsys.a
-llibsysbm.a -llibclang_rt.builtins.a -llibclang_rt.profile.a --end-group

This option list instructs the linker to search among the list of specified runtime libraries for definitions of unresolved symbol references. When a definition of a function or data object that resolves a previously unresolved reference is encountered, the section containing the definition is pulled into the link from the runtime library where it is defined. If new unresolved symbol references are introduced while this process is in progress, the libraries are re-read until no further needed definitions can be found among the --start_group/--end_group list of runtime libraries.

There are several different runtime library configurations supported in the c29clang compiler toolchain. An application built using the c29clang compiler tools must use a combination of target options that is compatible with one of the following configurations: