1.3.1. Commonly Used Options

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

1.3.1.1. Processor Options

1.3.1.1.1. Select a Target Arm Processor

-mcpu=<processor>

Select the target <processor> version.

The tiarmclang compiler supports the following Arm Cortex-M processor variants which support 16-bit and T32 THUMB instructions (as indicated):

  • -mcpu=cortex-m0 - 16-bit THUMB

  • -mcpu=cortex-m0plus - 16-bit THUMB

  • -mcpu=cortex-m3 - T32 THUMB

  • -mcpu=cortex-m4 - T32 THUMB

  • -mcpu=cortex-m33 - T32 THUMB

The tiarmclang compiler also supports Arm Cortex-R type processor variants, Cortex-R4, Cortex-R5, and Cortex-R52, which can execute ARM and T32 THUMB instructions. By default, the tiarmclang compiler assumes ARM instruction mode, but you can instruct the compiler to assume the use of T32 THUMB instructions for a given compilation by specifying the -mthumb option.

  • -mcpu=cortex-r4 - ARM (default) and/or T32 THUMB

  • -mcpu=cortex-r5 - ARM (default) and/or T32 THUMB

  • -mcpu=cortex-r52 - ARM (default) and/or T32 THUMB

1.3.1.1.2. Instruction Mode Options

The Cortex-M type Arm processors only support execution of THUMB mode instructions, so -mthumb is selected by default when using the -mcpu=cortex-m0, -mcpu=cortex-m0plus, -mcpu=cortex-m3, -mcpu=cortex-m4, or -mcpu=cortex-m33 processor options.

-mthumb

Select THUMB mode instructions (16-bit THUMB or T32 THUMB depending on which processor variant is selected) for current compilation; default for Cortex-M type architectures

Cortex-R type Arm processors can execute both ARM and T32 THUMB mode instructions. When the -mcpu=cortex-r4, -mcpu=cortex-r5, or -mcpu=cortex-r52 processor option is specified on the command line, the tiarmclang compiler assumes ARM instruction mode by default. This can be overridden for a given compilation by specifying the -mthumb option in combination with -mcpu=cortex-r4, -mcpu=cortex-r5, or -mcpu=cortex-r52 to cause the compiler to generate T32 THUMB instructions.

-marm

Select ARM mode instructions for current compilation; default for Cortex-R type processors

1.3.1.1.3. Endianness

All of the Arm Cortex-M type processor variants supported by the tiarmclang compiler are little-endian. The Arm Cortex-R type processor variants supported by the tiarmclang compiler may be big-endian or little-endian. The following options can be used to select the endian-ness to be assumed for a given compilation:

-mlittle-endian

Select little-endian; default

-mbig-endian

Select big-endian; only applicable for Cortex-R

1.3.1.1.4. Floating-Point Support Options

Some Arm processor variants can be used in conjunction with floating-point hardware processors to perform floating-point operations more efficiently. To enable this support, you must specify the -mfloat-abi=hard option in combination with the appropriate -mfpu option depending on what Arm processor variant is in use.

-mfloat-abi=<arg>

Select floating point ABI indicated by <arg>.

  • hard - floating-point hardware is available; select appropriate hardware with -mfpu option

  • soft - unless -mfloat-abi=hard is selected, floating-point operations are emulated in software

-mfpu=<arg>

Select floating-point hardware indicated by <arg>

Only certain Arm processor variants can be used in conjunction with floating-point hardware processors. The cortex-m0, cortex-m0plus, and cortex-m3 Arm processor variants are not compatible with any floating-point hardware processor.

  • vfpv3-d16 - available in combination with -mcpu=cortex-r4 or -mcpu=cortex-r5

  • fpv4-sp-d16 - available in combination with -mcpu=cortex-m4

  • fpv5-sp-d16 - available in combination with -mcpu=cortex-m33

1.3.1.2. Include Options

The tiarmclang compiler uses a directory search path to locate header files that are included by a C/C++ source file via an #include preprocessor directive. The compiler implicitly defines directories in its installation area where C/C++ standard header files and the runtime libraries provided by the tiarmclang compiler can be found.

There are two forms of the #include directive:

  • Quote form: #include "myfile.h" causes the compiler to look first in the same directory as the file containing the #include directive and then use the default search path.

  • Angle-bracket form: #include <math.h> causes the compiler to look only in the default search path.

The full search path sequence for finding included files is as follows. The search ends when the first matching file is found.

  1. Quote form only: Search the directory containing the current file.

  2. Quote form only: Search directories specified with the -iquote option (left-to-right command line order).

  3. Both forms: Search directories specified with the -I option (left-to-right order).

  4. Both forms: Search directories specified with the -isystem option (left-to-right order).

  5. Both forms: Search standard system directories. These directories are typically the compiler’s built-in library include files (for example, <install_dir>/lib/clang/22/include) and the standard system libraries (for example, <install_dir>/include/c) when compiling C source (and additional corresponding directories when compiling C++ source).

  6. Both forms: Search directories specified with the -idirafter option (left-to-right order).

The following options allow you to control which directories are searched for included files.

-I"<dir>"

For both forms of the #include directive, add a directory to the search path. This is the most commonly used option for adding user-supplied directories to the include file search path.

Note that there is a separate -I option that may be passed to the linker to control the search path for libraries. See Invoking the Linker for details.

-iquote"<dir>"

For quote forms of the #include directive only, add a directory to the search path. This directory is searched after the current directory and before directories specified with the -I option and the standard system directories.

-isystem"<dir>"

For both forms of the #include directive, add a directory to the search path. This directory is searched after any directories specified with the -I option and before the standard system directories. This option is typically used to specify vendor-supplies system header files.

-idirafter"<dir>"

For both forms of the #include directive, add a directory to the search path. This directory is searched after the standard system directories.

-nostdinc

Do not search for header files in any of the standard C system directories.

-nostdinc++

Do not search for header files in any of the standard C++ system directories. The standard C system directories are searched.

-nobuiltininc

Do not search for header files in the compiler’s built-in library include files directory.

-nostdlibinc

Do not search for header files in the compiler’s standard system library directory.

1.3.1.3. Predefined Symbol Options

In addition to the pre-defined macro symbols that the tiarmclang 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 will be 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.

tiarmclang -mcpu=cortex-m0 -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.

1.3.1.4. Optimization Options

To enable optimization passes in the tiarmclang compiler, select a level of optimization from among the following -O[0|1|2|3|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 is performed.

-O1  or -O

Restricted optimizations, providing a good trade-off between code size and debug-ability.

-O2

Most optimizations enabled; some optimizations that are likely to increase code size are disabled.

-O3

All optimizations available at -O2 plus others that may increase code size.

-Og

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

By default, the -Og option enables the -fextend-variable-liveness=all option, which improves debuggability of user variables.

-Os

All optimizations available at -O2 plus additional optimizations designed to reduce code size. In comparison to the -Oz option, the -Os option avoids code size optimizations that are likely to harm performance.

-Oz

All optimizations available at -O2 plus additional optimizations designed to reduce code size. In comparison to the -Os option, the -Oz option performs additional code size optimizations that may harm performance. This optimization setting is recommended if small code size is a priority.

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.

1.3.1.5. Debug Options

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

-g or -gdwarf-3

Emit DWARF version 3 debug information

1.3.1.6. Control Options

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

Several tiarmclang compiler options can be used to change this behavior and 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 compilation after emitting compiler-generated assembly files; do not call assembler or linker.

See Invoking the Compiler for examples.

1.3.1.7. Compiler Output Option

-o<file>

The -o option names the output file that results from a tiarmclang command. If tiarmclang 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 tiarmclang, then the linker produces an executable output file named a.out.

If the compiler is used to process a single source file, then the -o option names 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 produces 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 file that would normally be generated by the compiler:

tiarmclang -mcpu=cortex-m0 -c task_42.c -o task.o