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 and Cortex-R5, which can execute ARM and T32 THUMB instructions. By default, the tiarmclang compiler will assume ARM instruction mode, but the user 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
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 either the -mcpu=cortex-r4 or -mcpu=cortex-r5 processor option is specified on the command-line, the tiarmclang compiler will assume ARM instruction mode by default. This can be overridden for a given compilation by specifying the -mthumb option in combination with -mcpu=cortex-r4 or -mcpu=cortex-r5 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, the user 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 provides the user with the capability to add their 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 will define depending on which processor options are selected, the user can also manage their 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. Use of -Oz will still retain performance gains from many of the -O2 level optimizations that are performed.
- -O0¶
No optimization
- -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 debug-ability
- -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 -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 will generate DWARF debug information when the -g or -gdwarf-3 option is selected.
- -g or -gdwarf-3¶
Emit DWARF version 3 debug information
1.3.1.6. Control Options¶
Some tiarmclang 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
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 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:
tiarmclang -mcpu=cortex-m0 -c task_42.c -o task.o