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 utilizes the include file directory search path to locate a header file that is included by a C/C++ source file via an #include preprocessor directive. The tiarmclang 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 tiarmclang compiler package and should be used in combination with linker and the runtime libraries that are included in the tiarmclang compiler tools installation.
- -I<dir>¶
The -I option lets you add your own directories to the include file directory path, allowing user-created header files to be easily accessible during compilation.
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|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 debug-ability.
- -O2¶
Most optimizations enabled; some optimizations that require significantly 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.
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