# Use the compilers
The LLVM compilers translate C and C++ programs into Arm processor
code.
C and C++ programs are stored in source files, which are text files
created with a text editor. Arm processor code is stored in object
files, which are executable binary files.
## Start the compilers
To start the C compiler from the command line, enter:
>
>
> **clang [***options*…**]** *input\_files*…
To start the C++ compiler from the command line, enter:
>
>
> **clang++ [***options*…**]** *input\_files*…
The compilers accept one or more input files on the command line.
Input files can be C/C++ source files or object files. For example:
`clang hello.c mylib.c`
Command switches are used to control various
[compiler options](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#compiler-options). A switch consists of a dash
character (-) followed by a switch name and optional parameter.
Switches are case-sensitive and must be separated by at least one
space. For example:
>
>
> **clang hello.c -o hello**
To list the available command options, use the –help option:
>
>
> **clang –help clang++ –help**
This option causes the compiler to display the command line syntax,
followed by a list of the available command options. clang is the
name of the front-end driver for the LLVM compiler framework.
## Input and output files
The LLVM compilers preprocess and compile one or more source files
into object files. The compilers then invoke the linker to combine
the object files into an executable file.
Following are the input file types and the tool that processes files
of each type. The compilers use the filename extension to determine
how to process the file.
| **Extension** | **Description** | **Tool** |
| --- | --- | --- |
| .c | C source file | C compiler |
| .i | C preprocessed file | |
| .h | C header file | |
| .cc
.cp
.cxx
.cpp
.CPP
.c++
.C | C++ source file | C++ compiler |
| .ii | C++ preprocessed file | |
| .h
.hh
.H | C++ header file | |
| .bc
.ll | LLVM intermediate representation
(IR) file | C/C++ compiler |
| .s
.S | Assembly source file | Assembler |
| Other | Binary object file | Linker |
All filename extensions are case-sensitive literal strings. Input
files with unrecognized extensions are treated as object files. For
more information on LLVM IR files, see
[llvm.org](http://llvm.org/).
The following table lists the output file types and the tools used to generate
each file type. [Compiler options](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#compiler-options) are used to specify
the output file type.
| File type | Default
file
name | Input files |
| --- | --- | --- |
| Executable file | a.out | The specified source files are
compiled and linked to a single
executable file. |
| Object file | file.o | Each specified source file is
compiled to a separate object file
(where file is the source filename). |
| Assembly source
file | file.s | Each specified source file is
compiled to a separate assembly
source file (where file is the source
filename). |
| Preprocessed
C/C++ source
file | stdout | The preprocessor output is written to
the standard output. |
## Compiler options
The LLVM compilers can be controlled by [command-line options](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#start-the-compilers).
Many of the GCC options are supported, along with options that are
LLVM-specific.
Many of the -f, -m, and -W` options can be written in two ways:
-f*<option>* to enable a binary option, or -fno-*<option>* to
disable the option.
-mllvm is not a standalone option, but rather a standard prefix that
appears in many LLVM-specific option names.
The following is a quick reference of the options.
- [Display](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-display)
-help
-v
Copy to clipboard
- [Compilation](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-compilation)
-###
-c
-cc1
-ccc-print-phases
-E
-no-canonical-prefixes
-pipe
-o
-S
-Wa,[,...]
-Wl,[,...]
-Wp,[,...]
-x
-Xclang
Copy to clipboard
- [C dialect](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-c-dialect)
-ansi
-fblocks
-fgnu-runtime
-fgnu89-inline
-fno-asm
-fsigned-bitfields
-fsigned-char
-funsigned-char
-no-integrated-cpp
-std=(c89|gnu89|c99|gnu99|c11|gnu11)
-traditional
-Wpointer-sign
Copy to clipboard
- [C++ dialect](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-cpp-dialect)
-cxx-isystem
-ffor-scope | -fno-for-scope
-fno-gnu-keywords
-ftemplate-depth-n
-fvisibility-inlines-hidden
-fuse-cxa-atexit
-nobuiltininc
-nostdinc++
-std=(c++98|gnu++98|c++11|gnu++11|c++14|gnu++14|c++17|gnu++17)
-Wc++0x-compat
-Wno-deprecated
-Wnon-virtual-dtor
-Woverloaded-virtual
-Wreorder
Copy to clipboard
- [Warning and error messages](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-warning-and-error-messages)
c++98|c++11|c++14|c++17-compat-pedantic cast-calling-convention
comma
constant-conversion expansion-to-defined
-ferror-limit=
-ferror-warn float-overflow-conversion
float-zero-conversion
-ftemplate-backtrace-limit=
-fsyntax-only incompatible-sysroot nonportable-include-path
nonportable-system-include-path null-dereference
openmp-target
-pedantic | -Wpedantic pedantic-core-features
-pedantic-errors
-Qunused-arguments
shadow-field-in-constructor-modified shadow-field-in-constructor
undefined-func-template
undefined-var-template unguarded-availability unknown-argument
unsupported-cb
varargs
-w
-W
-Wno-
-Wall
-Warray-bounds
-Wcast-align
-Wchar-subscripts
-Wcomment
-Wconversion
-Wdeclaration-after-statement
-Wno-deprecated-declarations
-Wempty-body
-Wendif-labels
-Werror
-Werror=
-Wno-error=
-Werror-implicit-function-declaration
-Weverything
-Wextra
-Wfloat-equal
-Wformat
-Wformat=2
-Wformat-nonliteral
-Wformat-security
-Wignored-qualifiers
-Wimplicit
-Wimplicit-function-declaration
-Wimplicit-int
-Wno-format-extra-args
-Wno-invalid-offsetof
-Wlong-long
-Wmain
-Wmissing-braces
-Wmissing-declarations
-Wmissing-noreturn
-Wmissing-prototypes
-Wno-multichar
-Wnonnull
-Wpacked
-Wpadded
-Wparentheses
-Wpedantic
-Wpointer-arith
-Wreturn-type
-Wshadow
-Wsign-compare
-Wswitch | -Wswitch-enum
-Wsystem-headers
-Wtrigraphs
-Wundef
-Wuninitialized
-Wunknown-pragmas
-Wunreachable-code
-Wunused
-Wunused-function
-Wunused-label
-Wunused-parameter
-Wunused-value
-Wunused-variable
-Wno-vectorizer-no-neon
-Wwrite-strings
Copy to clipboard
- [Debugging](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-debugging)
-dumpmachine
-dumpversion
-feliminate-unused-debug-symbols
-time | -ftime-report
-g[]
-gline-tables-only
-print-diagnostic-categories
-print-file-name=
-print-libgcc-file-
-print-multi-directory
-print-multi-lib
-print-multi-os-directory
-print-prog-name=
-print-search-dirs
-save-temps
Copy to clipboard
- [Diagnostic format](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-diagnostic-format)
-fcaret-diagnostics | -fno-caret-diagnostics
-fdiagnostics-show-option | -fno-diagnostics-show-option
-fdiagnostics-show-category=(none|id|name)
-fdiagnostics-print-source-range-info
-fno-diagnostics-print-source-range-info
-fdiagnostics-parseable-fixits
-fdiagnostics-show-template-tree
-fmessage-length=
Copy to clipboard
- [Individual warning groups](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-individual-warning-groups)
-Wextra-tokens
-Wambiguous-member-template
-Wbind-to-temporary-copy
Copy to clipboard
- [Compiler crash diagnostics](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-compiler-crash-diagnostics)
-fno-crash-diagnostics
Copy to clipboard
- [Linker](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-linker)
-fuse-ld=(gold|bfd|qcld)
Copy to clipboard
- [Preprocessor](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-preprocessor)
-A pred=
-A -pred=
-ansi
-C
-CC
-d(DMNU)
-D | -D =
-fexec-charset=charset
-finput-charset=charset
-fpch-deps
-fpreprocessed
-fstrict-overflow
-ftabstop=
-fwide-exec-charset=charset
-fworking-directory
-H
--help
-I
-I-
-include
-isystem
-isystem-prefix
-ino-system-prefix
-M
-MD
-MF
-MG
-MM
-MMD
-MP
-MQ
-MT
-nostdinc
-nostdinc++
-o
-P
-remap
--target-help
-traditional-cpp
-trigraphs
-U
-v
-version
--version
-w
-Wall
-Wcomment | -Wcomments
-Wendif-labels
-Werror
-Wimport
-Wsystem-headers
-Wtrigraphs
-Wundef
-Wunused-macros
Copy to clipboard
- [Assembling](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-assembling)
-fintegrated-as | -fno-integrated-as
-Xassembler
Copy to clipboard
- [Linking](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-linking)
object_file_name
-c
-dynamic
-E
-l
-moslib=
-nodefaultlibs
-nostartfiles
-nostdlib
-pie
-s
-S
-shared
-shared-libgcc
-static
-static-libgcc
-symbolic
-u
-Xlinker
Copy to clipboard
- [Directory search](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-directory-search)
-B
-F
--gcc-toolchain=
-I
-I-
-L
Copy to clipboard
- [Processor version](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-processor-version)
-target
-march=
-mcpu=
-mfpu=
-mfloat-abi=(soft|softfp|hard)
Copy to clipboard
- [Code generation](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-code-generation)
-fchar-array-precise-tbaa | -fno-char-array-precise-tbaa
-femit-all-data
-femit-all-decls
-ffp-contract=(fast|on|off)
-finstrument-functions
-fmerge-functions | -fno-merge-functions
-fno-exceptions
-fpic
-fPIC
-fpie | -fPIE
-fsanitize=address | -fno-sanitize=address
-fsanitize=memory | -fno-sanitize=memory
-fsanitize=[<,event>...] | -fno-sanitize=[<,event>...]
-fsanitize=integer
-fsanitize=undefined
-fsanitize-blacklist= | -fno-sanitize-blacklist
-fsanitize-memory-track-origins[=]
-fsanitize-messages | -fno-sanitize-messages
-fsanitize-opt-size | -fno-sanitize-opt-size
-fsanitize-source-loc | -fno-sanitize-source-loc
-fsanitize-use-embedded-rt
-fshort-enums | -fno-short-enums
-fshort-wchar | -fno-short-wchar
-ftrap-function=
-ftrapv
-ftrapv-handler=
-funwind-tables
-fverbose-asm
-fvisibility=[default|internal|hidden|protected]
-fwrapv
-mhwdiv=(arm|thumb|arm,thumb|none)
-mllvm -aarch64-disable-abs-reloc
-mllvm -aggressive-jt
-mllvm -arm-expand-memcpy-runtime
-mllvm -arm-memset-size-threshold
-mllvm -arm-memset-size-threshold-zeroval
-mllvm -arm-opt-memcpy
-mllvm -disable-thumb-scale-addressing
-mllvm -emit-cp-at-end
-mllvm -enable-android-compat
-mllvm -enable-arm-addressing-opt
-mllvm -enable-arm-peephole
-mllvm -enable-arm-zext-opt
-mllvm -enable-print-fp-zero-alias
-mllvm -enable-round-robin-RA
-mllvm -enable-select-to-intrinsics
-mllvm -favor-r0-7
-mllvm -force-div-attr
-mllvm -prefetch-locality-policy=(L1|L2|L3|stream)
-mrestrict-it | -mno-restrict-it
Copy to clipboard
- [Vectorization](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-vectorization)
-ftree-vectorize
-fvectorize-loops
-fvectorize-loops-debug
-fprefetch-loop-arrays[=] | -fno-prefetch-loop-arrays
Copy to clipboard
- [Parallelization](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-parallelization)
-fparallel
Copy to clipboard
- [Optimization](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-optimization)
-O0
-O | -O1
-O2
-O3
-O4
-Ofast
-Os
-Osize
-Oz
Copy to clipboard
- [Specific optimizations](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-specific-optimizations)
-faggressive-unroll
-fdata-sections
-ffp-contract=[off|on|fast]
-ffunction-sections
-finline
-finline-functions
-floop-pragma
-fno-zero-initialized-in-bss
-fnomerge-all-constants
-fomit-frame-pointer
-foptimize-sibling-calls
-fstack-protector
-fstack-protector-all
-fstack-protector-strong
-fstrict-aliasing
-funit-at-a-time
-funroll-all-loops
-funroll-loops
-maggressive-size-opts
--param ssp-buffer-size=
Copy to clipboard
- [Math optimization](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-math-optimizations)
-fassociative-math
-ffast-math
-ffinite-math-only
-fno-math-errno
-freciprocal-math
-fno-signed-zeros
-fno-trapping-math
-funsafe-math-optimizations
Copy to clipboard
- [Link-time optimization (compiler and linker)](https://docs.qualcomm.com/doc/80-VB419-99/topic/code_optimization.html#sec-link-time-optimization)
-flto
Copy to clipboard
- [Profile-guided optimization](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-profile-guided-optimizations)
-fprofile-instr-generate[=]
-fprofile-instr-use=
-fprofile-sample-use=
Copy to clipboard
- [Optimization reports](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-use-compiler-optimization-reports)
-fopt-reporter=(vectorizer|parallelizer|all)
-polly-max-pointer-aliasing-checks
-Rpass=loop-opt
-Rpass-missed=loop-opt
Copy to clipboard
- [Compiler security](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-compiler-security)
--analyze
-analyzer-checker=
-analyzer-checker-help
-analyzer-disable-checker=
--analyzer-output html
--analyzer-Werror
--compile-and-analyze
--compile-and-analyze-high
--compile-and-analyze-medium
-ffcfi
-fno-fcfi
Copy to clipboard
### Display
- **-help**
- Displays compiler command and option summary.
- **-v**
- Displays compiler release version.
### Compilation
- **-###**
- Prints commands used to perform the compilation.
- **-c**
- Compiles the source file, but does not link it.
- **-cc1**
- Bypasses the compiler driver and go directly to LLVM.
- **-ccc-print-phases**
- Prints the compilation stages as they occur.
- **-E**
- Preprocesses the source file only; does not compile it.
- **-no-canonical-prefixes**
- When processing a pathname:
- Does not expand any symbolic links
- Does not resolve any references to /./ or /../
- Does not make relative prefixes absolute
- **-pipe**
- Communicates between compiler stages using pipes not temporary files.
- **-o** *file*
- Specify the name of the compiler output file.
- **-S**
- Compiles the source file, but does not assemble it.
- **-Wa,<arg>[,<arg>…]**
- Passes the specified arguments to the assembler.
- **-Wl,<arg>[,<arg>…]**
- Passes the specified arguments to the linker.
- **-Wp,<arg>[,<arg>…]**
- Passes the specified arguments to the preprocessor.
- **-x <language>**
- Specifies the language of the subsequent source files specified on the command line.
- **-Xclang <arg>**
- Passes the specified argument to the compiler.
### C dialect
- **-ansi**
- For C, supports ISO C90.
For C++, removes conflicting GNU extensions.
- **-fblocks**
- Enables the Apple blocks extension.
- **-fgnu-runtime**
- Generates output compatible with the standard GNU Objective-C runtime.
- **-fgnu89-inline**
- Uses the gnu89 inline semantics.
- **-fno-asm**
- Does not recognize asm, inline, or typeof as keywords.
- **-fsigned-bitfields**
- Defines bit fields as signed.
- **-fsigned-char**
- Defines the char type as signed.
- **-funsigned-char**
- Defines the char type as unsigned.
- **-no-integrated-cpp**
- Compiles using separate preprocessing and compilation stages.
- **-std=(c89|gnu89|c99|gnu99|c11|gnu11)**
- LLVM C language mode. The default setting is gnu11.
- **-traditional**
- Supports pre-standard C language.
- **-Wpointer-sign**
- Flag pointers when assigned or passed values with a differing sign.
### C++ dialect
- **-cxx-isystem <dir>**
- Adds a specified directory to C++ SYSTEM include search path.
- **-ffor-scope** | **-fno-for-scope**
- Controls whether the scope of a variable declared in a for statement
is limited to the statement or to the scope enclosing the statement.
- **-fno-gnu-keywords**
- Disables recognizing typeof as a keyword.
- **-ftemplate-depth-n**
- Specifies the maximum instantiation depth of a template class.
- **-fvisibility-inlines-hidden**
- Specifies the default visibility for inline C++ member functions.
- **-fuse-cxa-atexit**
- Registers destructors with function cxa\_atexit (instead of atexit).
This option applies only to objects that have static storage
duration.
- **-nobuiltininc**
- Disables built-in #include directories.
- **-nostdinc++**
- Disables standard #include directories for the C++ standard library.
- **-std=(c++98|gnu++98|c++11|gnu++11|c++14|gnu++14|c++17|gnu++17)**
- LLVM C++ language mode. The default setting is gnu++14.
- **-Wc++0x-compat**
- Generates warnings for C++ constructs with different semantics in ISO
C++ 1998 and ISO C++ 200x.
- **-Wno-deprecated**
- Does not generate warnings when deprecated features are used.
- **-Wnon-virtual-dtor**
- Generates a warning when a polymorphic class is declared with a
non-virtual destructor.
- **-Woverloaded-virtual**
- Generates a warning when a function hides virtual functions from a
base class.
- **-Wreorder**
- Generates a warning when member initializers do not appear in the
code in the required execution order.
### Warning and error messages
- **c++98|c++11|c++14|c++17-compat-pedantic**
- Hexadecimal floating literals are incompatible with C++ standards
before C++1z.
Warns if the compiled code uses experimental features added to
language standards more recent than C++17.
- **cast-calling-convention**
- Cast between incompatible %0 and %1 calling conventions. Calls
through this pointer might abort at runtime.
- **comma**
- Possible misuse of comma operator here.
- **constant-conversion**
- Implicit conversion from %2 to %3 changes the value from %0 to %1.
- **expansion-to-defined**
- Macro expansion producing defined has undefined behavior.
- **-ferror-limit=<n>**
- Stops emitting diagnostics after *n* errors have been produced. The
default setting is 20. Disable the error limit with -ferror-limit=0.
- **-ferror-warn <filename>**
- Converts the specified set of compiler warnings into errors.
The specified text file contains a list of warning names, with each
warning name separated by whitespace in the file.
Warning names are based on the switch names of the corresponding
compiler warning message options. For example, to convert the
warnings generated by
`-Wunused-variable`, use the warning name, unused-variable. You can
specify this option multiple times.
Note
You can integrate this option (and its associated file)
into a build system and use it to iteratively resolve the warning
messages generated by a project.
- **float-overflow-conversion**
- Implicit conversion of out of range value from %0 to %1 changes the
value from %2 to %3.
- **float-zero-conversion**
- Implicit conversion from %0 to %1 changes the non-zero value from %2
to %3.
- **-ftemplate-backtrace-limit=<n>**
- Only emits up to *n* template instantiation notes within the template
instantiation backtrace for a single warning or error. The default
setting is 10. Disable the limit with `-ftemplate-backtrace-limit=0`.
- **-fsyntax-only**
- Checks for syntax errors only.
- **incompatible-sysroot**
- Uses sysroot for %0 but targets %1.
- **nonportable-include-path**
- Non-portable path to file %0. The specified path differs in case from
the filename on the disk.
- **nonportable-system-include-path**
- Non-portable path to file %0. The specified path differs in case from
the filename on the disk.
- **null-dereference**
- Binding dereferenced NULL pointer to reference has undefined behavior.
- **openmp-target**
- Declaration is not declared in any declare target region.
- **-pedantic** | **-Wpedantic**
- Generate all warnings required by the ISO C and ISO C++ standards.
- **pedantic-core-features**
- OpenCL extension %0 is a core feature or a supported optional core
feature; ignoring.
- **-pedantic-errors**
- Equivalent to -pedantic, but generate errors instead of warnings.
- **-Qunused-arguments**
- Does not generate warnings for unused driver arguments.
- **shadow-field-in-constructor-modified**
- Modifying constructor parameter %0 that shadows a field of %1.
- **shadow-field-in-constructor**
- Constructor parameter %0 shadows the field %1 of %2.
- **undefined-func-template**
- Instantiation of function %q0 is required, but no definition is available.
- **undefined-var-template**
- Instantiation of variable %q0 is required, but no definition is available.
- **unguarded-availability**
- Using \* case here; platform %0 is not accounted for.
- **unknown-argument**
- Unknown argument is ignored in clang-cl: %0.
- **unsupported-cb**
- Ignoring -mcompact-branches= option because the %0 architecture does not support it.
- **varargs**
- Passing an object that undergoes a default argument promotion to
va\_start has undefined behavior.
- **-w**
- Suppresses all warnings.
- **-W<foo>**
- Enables the diagnostic *foo*.
- **-Wno-<foo>**
- Disables the diagnostic *foo*.
- **-Wall**
- Enables all -W options.
- **-Warray-bounds**
- Generates a warning if array subscripts are out of bounds.
- **-Wcast-align**
- Generates a warning if a pointer cast increases the required
alignment of the target.
- **-Wchar-subscripts**
- Generates a warning if array subscript is type char.
- **-Wcomment**
- Generates a warning if a comment symbol appears inside a comment.
- **-Wconversion**
- Generates a warning if an implicit conversion might alter a value.
- **-Wdeclaration-after-statement**
- Generates a warning when a declaration appears in a block after a statement.
- **-Wno-deprecated-declarations**
- Does not generate warnings for functions, variables, or types
assigned the attribute deprecated.
- **-Wempty-body**
- Generates a warning if an if, else, or do while statement contains an
empty body.
- **-Wendif-labels**
- Generates a warning if an #else or #endif directive is followed by
text.
- **-Werror**
- Converts all warnings into errors.
- **-Werror=<foo>**
- Converts the diagnostic *foo* into an error.
- **-Wno-error=<foo>**
- Keeps the diagnostic *foo* as a warning, even if `-Werror` is used.
- **-Werror-implicit-function-declaration**
- Generates a warning or error if a function is used before being
declared.
- **-Weverything**
- Enables all warnings.
- **-Wextra**
- Enables selected warning options, and generate warnings for selected events.
- **-Wfloat-equal**
- Generates a warning if two floating-point values are compared for equality.
- **-Wformat**
- In calls to printf, scanf and other functions with format strings,
ensures that the arguments are compatible with the specified format
string.
- **-Wformat=2**
- Equivalent to specifying the following options:
- `-Wformat`
- `-Wformat-nonliteral`
- `-Wformat-security`
- `-Wformat-y2k`
- **-Wformat-nonliteral**
- Generates a warning if the format string is not a string literal,
except if the format arguments are passed through va\_list.
- **-Wformat-security**
- Generates a warning for format function calls that might cause
security risks.
- **-Wignored-qualifiers**
- Generates a warning if a return type has a qualifier (such as const).
- **-Wimplicit**
- Equivalent to -Wimplicit-int and -Wimplicit-function-declaration.
- **-Wimplicit-function-declaration**
- Generates a warning if a function is used before it is declared.
- **-Wimplicit-int**
- Generates a warning if a declaration does not specify a type.
- **-Wno-format-extra-args**
- Does not generate a warning for passing extra arguments to printf or scanf.
- **-Wno-invalid-offsetof**
- Does not generate a warning if a non-POD type is passed to the
offsetof macro.
- **-Wlong-long**
- Generates a warning if typelong long is used.
- **-Wmain**
- Generates a warning if the main() function has any suspicious
properties.
- **-Wmissing-braces**
- Generates a warning if an aggregate or union initializer is not
properly bracketed.
- **-Wmissing-declarations**
- Generates a warning if a global function is defined without being
first declared.
- **-Wmissing-noreturn**
- Generates a warning if a function does not include a return
statement.
- **-Wmissing-prototypes**
- Generates a warning if a global function is defined without a
prototype.
- **-Wno-multichar**
- Does not generate a warning if a multiple-character constant is used.
- **-Wnonnull**
- Generates a warning if a NULL pointer is passed to an argument that
is specified to require a non-NULL value (with the nonnull
attribute).
- **-Wpacked**
- Generates a warning if the memory layout of a structure is not
affected after the structure is specified with the packed attribute.
- **-Wpadded**
- Generates a warning if the memory layout of a structure includes
padding.
- **-Wparentheses**
- Generates a warning if the parentheses are omitted in certain cases.
- **-Wpedantic**
- See -pedantic.
- **-Wpointer-arith**
- Generates a warning if any code depends on the size of void or a
function type.
- **-Wreturn-type**
- Generates a warning if a function returns a type that defaults to
int, or a value is incompatible with the defined return type.
- **-Wshadow**
- Generates a warning if a local variable shadows another local
variable, global variable, or parameter; or if a built-in function
gets shadowed.
- **-Wsign-compare**
- Generates a warning in a signed/unsigned compare operation if the
result might be inaccurate due to the signed operand being converted
to unsigned.
- **-Wswitch** | **-Wswitch-enum**
- Generates a warning if a switch statement uses an enum type for the
index, and does not specify a case for every possible enumeration
value, or specifies a case with a value outside the enumeration
range.
- **-Wsystem-headers**
- Generates a warning for constructs declared in system header files.
- **-Wtrigraphs**
- Generates a warning if a trigraph forms an escaped newline in a
comment.
- **-Wundef**
- Generates a warning if an undefined non-macro identifier appears in
an #if directive.
- **-Wuninitialized**
- Generates a warning if referencing an uninitialized automatic variable.
- **-Wunknown-pragmas**
- Generates a warning if a #pragma directive is not recognized by the compiler.
- **-Wunreachable-code**
- Generates a warning if code will never be executed.
- **-Wunused**
- Specifies all of the -Wunused options.
- **-Wunused-function**
- Generates a warning if a static function is declared without being
defined or used.
Note
No warning is generated for functions declared or defined
in header files.
- **-Wunused-label**
- Generates a warning if a label is declared without being used.
- **-Wunused-parameter**
- Generates a warning if a function argument is not used in its function.
- **-Wunused-value**
- Generates a warning if the value of a statement is not subsequently used.
- **-Wunused-variable**
- Generates a warning if a local or non-constant static variable is not
used in its function.
- **-Wno-vectorizer-no-neon**
- Does not generate the warning, Vectorization flags ignored because
armv7/armv8 and neon not set.
Vectorization requires an Armvv7 or Armvv8 target, and the NEON
feature must be enabled. If the vectorization options are used
without these required options, a warning is normally generated and
the vectorization options are ignored.
- **-Wwrite-strings**
- For C, assigns string constants the type const char[*length*] to
ensure that a warning is generated if the string address gets copied
to a non-const char \* pointer.
For C++, generates a warning that states a string constant is being
converted to char \*.
#### Warning—Argument unused during compilation: -mfpu=%0
Clang generates a warning when setting -mfpu in addition to
specifying AArch64. To avoid this warning, do not specify the -mfpu
option when specifying AArch64.
#### LLVM 4.0 release
**Table 4-3 LLVM 4.0 release: new warnings**
| **Category** | **Description** |
| --- | --- |
| -Wunused-command-line-argument | -fdiagnostics-show-hotness argument
requires profile-guided optimization
information. |
| -Wslash-u-filename | /UA treated as the /U option. |
| -Wunable-to-open-stats-file | Unable to open statistics output file
A: B. |
| -Wprivate-module | Top-level module A in a private
module map; expected a submodule of
B. |
| -Wempty-decomposition | ISO C++1z does not allow a
decomposition group to be empty. |
| -Wc++1z-extensions | Use of multiple declarators in a
single using declaration is a C++1z
extension. |
| -Wc++98-c++11-c++14-compat | Initialization statements are
incompatible with C++ standards
before C++1z. |
| -Wignored-pragma-intrinsic | A is not a recognized built-in
intrinsic; consider including
<intrin.h> to access non-built-in
intrinsics. |
| -Wignored-pragmas | Ignored. Expected *enable*,
*disable*, *begin*, or *end*. |
| -Wmax-unsigned-zero | Call to function without interrupt
attribute could clobber VFP registers
of the interruptee. |
| -Wextra | Call to function without interrupt
attribute could clobber VFP registers
of the interruptee. |
| -Wunused-lambda-capture | Variable explicitly captured by a
lambda is not used in the body of the
lambda. |
| -Wshadow-uncaptured-local | Declaration shadows a local variable. |
| -Wdynamic-exception-spec | ISO C++1z does not allow dynamic
exception specifications. |
| -Wc++1z-compat | Mangled name of A will change in
C++17 due to non- throwing exception
specification in function signature. |
| -Wreturn-type | Control might reach end of non-void
coroutine. |
| -Wmain | Boolean literal returned from *main.* |
| -Wincompatible-exception-spec | Exception specifications of return
type differ. |
| -Winconsistent-missing-
destructor-override | A overrides a destructor but is not
marked as *override.* |
| -Walloca-with-align-alignof | Second argument to
builtin\_alloca\_with\_align is supposed
to be in bits. |
| -Wsigned-enum-bitfield | Enums in the Microsoft ABI are signed
integers by default. Consider giving
the enum A an unsigned underlying
type to make this code portable. |
| -Wunguarded-availability | A is only available on B, C, or
newer. |
| -Win
valid-partial-specialization | Class/variable template partial
specialization is not more
specialized than the primary
template. |
| -Wstrict-prototypes | Function declaration is not a
prototype. |
| -Wblock-capture-autoreleasing | Block captures an auto-releasing
out-parameter, which might result in
use-after-free bugs. |
| -Waddress-of-packed-member | Taking address of packed member A of
class or structure B might result in
an unaligned pointer value. |
| -Wambiguous-delete | Multiple suitable A functions for B;
no *operator delete* function will be
invoked if initialization throws an
exception. |
| -Win
compatible-function-pointer-
types | Incompatible function pointer types
used. |
| -Wformat | Using A format specifier annotation
outside of os\_log()/os\_trace(). |
| -Wspir-compat | Sampler initializer has invalid A
bits. |
| -Wnullability
-completeness-on-
arrays | Array parameter is missing a NULL
type specifier (\_Nonnull,
\_Nullable, or \_Null\_unspecified). |
| -Wgcc-compat | final is a GNU extension. Consider
using C++11 final. |
#### LLVM 6.0 release
The following warning flags are new for LLVM 6.0:
- -Wbinary-literal
- -Wbinding-in-condition
- -Wbitfield-enum-conversion
- -Wc++17-compat
- -Wc++17-compat-mangling
- -Wc++17-compat-pedantic
- -Wc++17-extensions
- -Wc++1z-compat-mangling
- -Wc++2a-compat
- -Wc++2a-compat-pedantic
- -Wc++2a-extensions
- -Wc++98-c++11-compat-binary-literal
- -Wcoroutine-missing-unhandled-exception
- -Wcpp
- -Wenum-compare-switch
- -Wmissing-noescape
- -Wmsvc-not-found
- -Wnsconsumed-mismatch
- -Wnsreturns-mismatch
- -Wnull-pointer-arithmetic
- -Wobjc-flexible-array
- -Wobjc-messaging-id
- -Wout-of-scope-function
- -Wpragma-clang-attribute
- -Wpragma-pack
- -Wpragma-pack-suspicious-include
- -Wprofile-instr-missing
- -Wredundant-parens
- -Wtautological-constant-compare
- -Wtautological-unsigned-enum-zero-compare
- -Wtautological-unsigned-zero-compare
- -Wundefined-internal-type
- -Wunguarded-availability-new
- -Wunicode-homoglyph
- -Wunsupported-availability-guard
- -Wunused-template
- -Wzero-as-null-pointer-constant
For details, visit the llvm.org page:
[releases.llvm.org/6.0.0/tools/clang/docs/DiagnosticsReference.html](http://releases.llvm.org/6.0.0/tools/clang/docs/DiagnosticsReference.html)
#### LLVM 8.0 release
The following warning flags are new for LLVM 8.0:
- -Wargument-outside-range
- -Watimport-in-framework-header
- -Watomic-alignment
- -Watomic-implicit-seq-cst
- -Wc++98-compat-extra-semi
- -Wcast-qual-unrelated
- -Wdangling
- -Wdefaulted-function-deleted
- -Wdeprecated-this-capture
- -Wfixed-enum-extension
- -Wframework-include-private-from-public
- -Wfunction-multiversion
- -Wignored-pragma-optimize
- -Wimplicit-float-conversion
- -Wimplicit-int-conversion
- -Wincomplete-framework-module-declaration
- -Wmemset-transposed-args
- -Wnontrivial-memaccess
- -Wobjc-property-assign-on-object-type
- -Wordered-compare-function-pointers
- -Wquoted-include-in-framework-header
- -Wreturn-std-move
- -Wreturn-std-move-in-c++11
- -Wself-assign-overloaded
- -Wstdlibcxx-not-found
- -Wsuspicious-bzero
- -Wsuspicious-memaccess
- -Wunicode-zero-width
- -Wunsupported-target-opt
For details, visit the llvm.org page:
[https:\\clang.llvm.org/docs/DiagnosticsReference.html](https://clang.llvm.org/docs/DiagnosticsReference.html)
#### LLVM 10.0 release
The following warning flags are new for LLVM 10.0:
- -Walloca
- -Wavr-rtlib-linking-quirks
- -Wc++2a-designator
- -Wc99-designator
- -Wcall-to-pure-virtual-from-ctor-dtor
- -Wconcepts-ts-compat
- -Wctad-maybe-unsupported
- -Wctu
- -Wdangling-gsl
- -Wdarwin-sdk-settings
- -Wdelete-abstract-non-virtual-dtor
- -Wdelete-non-abstract-non-virtual-dtor
- -Wdeprecated-comma-subscript
- -Wempty-init-stmt
- -Wexport-unnamed
- -Wexport-using-directive
- -Wextra-semi-stmt
- -Wfinal-dtor-non-final-class
- -Wfortify-source
- -Wimplicit-fixed-point-conversion
- -Wimplicit-int-float-conversion
- -Wincomplete-setjmp-declaration
- -Winitializer-overrides
- -Wint-in-bool-context
- -Wmicrosoft-drectve-section
- -Wmisexpect
- -Wmissing-constinit
- -Wmodule-import
- -Wnoderef
- -Wobjc-bool-constant-conversion
- -Wobjc-boxing
- -Wobjc-signed-char-bool
- -Wobjc-signed-char-bool-implicit-float-conversion
- -Wobjc-signed-char-bool-implicit-int-conversion
- -Woverride-init
- -Wpointer-compare
- -Wpointer-integer-compare
- -Wpoison-system-directories
- -Wreorder-ctor
- -Wreorder-init-list
- -Wsigned-unsigned-wchar
- -Wsizeof-array-div
- -Wsizeof-pointer-div
- -Wstack-exhausted
- -Wtautological-objc-bool-compare
- -Wunderaligned-exception-object
- -Wxor-used-as-pow
For details, visit the llvm.org page:
[https://clang.llvm.org/docs/DiagnosticsReference.html](https://clang.llvm.org/docs/DiagnosticsReference.html)
#### LLVM 12.0 release
To review the warning flags that are new for LLVM 12.0, visit the
llvm.org page: [https://clang.llvm.org/docs/DiagnosticsReference.html](https://clang.llvm.org/docs/DiagnosticsReference.html)
### Debugging
- **-dumpmachine**
- Displays the target machine name.
- **-dumpversion**
- Displays the compiler version.
- **-feliminate-unused-debug-symbols**
- Generates debug information only for the symbols that are used.
(Debug information is generated in STABS format.)
- **-time** | **-ftime-report**
- Displays the elapsed time for each stage of the compilation.
- **-g[<level>]**
- Generates complete source-level debug information.
- **-gline-tables-only**
- Generates source-level debug information with line number tables only.
- **-print-diagnostic-categories**
- Displays mapping of diagnostic category names to category identifiers.
- **-print-file-name=<library>**
- Displays the full library path of the specified file.
- **-print-libgcc-file-name**
- Displays the library path for the libgcc.a file.
- **-print-multi-directory**
- Displays the directory names of the multiple libraries specified by
other compiler options in the current compilation.
- **-print-multi-lib**
- Displays the directory names of the multiple libraries paired with
the compiler options that specified the libraries in the current
compilation.
- **-print-multi-os-directory**
- Displays the relative path that is appended to the multi-lib search paths.
- **-print-prog-name=<program>**
- Displays the absolute path of the specified program.
- **-print-search-dirs**
- Displays the search paths used to locate libraries and programs
during compilation.
- **-save-temps**
- Saves the normally-temporary intermediate files generated during compilation.
### Diagnostic format
The LLVM compilers aim to produce beautiful diagnostics by default,
especially for new users just beginning to use LLVM. However,
different users have different preferences, and sometimes LLVM is
driven by another program that requires the diagnostic output to be
simple and consistent rather than user-friendly. For these cases,
LLVM provides a wide range of options to control the output format of
the diagnostics that it generates.
- **-fcaret-diagnostics** | **-fno-caret-diagnostics**
- Print source line and ranges from source code in diagnostic format.
This option controls whether LLVM prints the source line, source
ranges, and caret when emitting a diagnostic. The default setting is
enabled. When enabled, LLVM prints information like the following
example:
test.c:28:8: warning: extra tokens at end of #endif directive
[-Wextra-tokens]
#endif bad
^
//
Copy to clipboard
- **-fdiagnostics-format=(clang|msvc|vi)**
- Changes diagnostic output format to better match IDEs and command
line tools.
This option controls the output format of the filename, line number,
and column printed in diagnostic messages. The default setting is
clang. The effect of the setting the output format is shown in the
following examples.
- clang
t.c:3:11: warning: conversion specifies type 'char *' but the
argument has type 'int'
Copy to clipboard
- msvc
t.c(3,11) : warning: conversion specifies type 'char *' but the
argument has type 'int'
Copy to clipboard
- vi
t.c +3:11: warning: conversion specifies type 'char *' but the
argument has type 'int'
Copy to clipboard
- **-fdiagnostics-show-option** | **-fno-diagnostics-show-option**
- Enable [-W<option>] information in diagnostic line.
This option controls whether LLVM prints the associated warning group
option name ([Section 4.3.30.3](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#diagnostic-categories)) when
outputting a warning diagnostic. The default setting is disabled.
For example, given the following diagnostic output:
test.c:28:8: warning: extra tokens at end of #endif directive
[-Wextra-tokens]
#endif bad
^
//
Copy to clipboard
In this case, specifying `-fno-diagnostics-show-option` prevents LLVM
from printing the [-Wextra-tokens] information in the diagnostic
output. This information indicates the option that is required to
enable or disable the diagnostic, either from the command line or by
using the GCC diagnostic pragma ([control diagnostics with pramas](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-control-diagnostics-with-pragmas)).
- **-fdiagnostics-show-category=(none|id|name)**
- Enables printing category information in diagnostic line.
This option controls whether LLVM prints the category associated with
a diagnostic when emitting it. The default setting is none. The
effect of the setting the output format is shown in the following
examples.
- none
t.c:3:11: warning: conversion specifies type 'char \*' but the
argument has type 'int' [-Wformat]
Copy to clipboard
- id
t.c:3:11: warning: conversion specifies type 'char \*' but the
argument has type 'int' [-Wformat,1]
Copy to clipboard
- name
t.c:3:11: warning: conversion specifies type 'char \*' but the
argument has type 'int' [-Wformat,Format String]
Copy to clipboard
Each diagnostic can have an associated category. If it has one, it is
listed in the diagnostic category field of the diagnostic line (in
the [] brackets).
This option can be used to group diagnostics by category, so it
should be a high-level category; the goal is to have dozens of
categories, not hundreds or thousands of them.
- **-fdiagnostics-print-source-range-info** | **-fno-diagnostics-print-source-range-info**
- Print machine-parseable information about source ranges.
This option controls whether LLVM prints information about source
ranges in a machine-parseable format after the file/line/column
number information. The default setting is disabled. The information
is a simple sequence of brace-enclosed ranges, where each range lists
the start and end line/column locations.
For example, given the following output:
exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float')
P = (P-42) + Gamma*4;
~~~~~~ ^ ~~~~~~~
Copy to clipboard
In this case, -fdiagnostics-print-source-range-info generates the
braces, {}.
The printed column numbers count bytes from the beginning of the
line; take care if the source contains multiple-byte characters.
- **-fdiagnostics-parseable-fixits**
- Prints Fix-Its in a machine-parseable format.
This option makes LLVM print available Fix-Its in a machine-parseable
format at the end of diagnostics. The following example illustrates
the format:
`fix-it:"t.cpp":{7:25-7:29}:"Gamma"`
In this case, the range printed is half-open, so the characters from
column 25 up to (but not including) column 29 on line 7 of file t.cpp
should be replaced with the string Gamma. Either the range or
replacement string can be empty (representing strict insertions and
strict erasures, respectively). Both the filename and insertion
string escape backslash (as \\), tabs (as \t), newlines (as \n),
double quotes (as \”), and non-printable characters (as octal
\xxx).
The printed column numbers count bytes from the beginning of the
line; take care if the source contains multiple-byte characters.
- **-fdiagnostics-show-template-tree**
- For large templated types, this option causes LLVM to display the
templates as an indented text tree, with one argument per line, and
any differences marked inline.
- default
t.cc:4:5: note: candidate function not viable: no known conversion
from 'vector>>' to 'vector>>' for 1st argument;
Copy to clipboard
- -fdiagnostics-show-template-tree
t.cc:4:5: note: candidate function not viable: no known conversion
for 1st argument;
vector< map<
[...],
map<
[float != float], [...]>>>
Copy to clipboard
- **-fmessage-length=<n>**
- Formats error messages to fit on lines with the specified number of characters.
### Individual warning groups
- **-Wextra-tokens**
- Warns about excess tokens at the end of a preprocessor directive.
This option enables warnings about extra tokens at the end of
preprocessor directives. The default setting is enabled. For example:
test.c:28:8: warning: extra tokens at end of #endif directive
[-Wextra-tokens]
#endif bad
^
Copy to clipboard
These extra tokens are not strictly conforming and are usually best
handled by commenting them out.
- **-Wambiguous-member-template**
- Warns about unqualified uses of a member template whose name resolves
to another template at the location of the use.
This option (which is enabled by default) generates a warning in the
following code:
template struct set{};
template struct trait { typedef const T& type; }; struct
Value {
template void set(typename trait::type value){}
};
void foo() { Value v;
v.set(3.2);
}
Copy to clipboard
C++ requires this to be an error, but because it is difficult to work
around, LLVM downgrades it to a warning as an extension.
- **-Wbind-to-temporary-copy**
- Warns about an unusable copy constructor when binding a reference to
a temporary.
This option enables warnings about binding a reference to a temporary
when the temporary does not have a usable copy constructor.
The default setting is enabled. For example:
struct NonCopyable { NonCopyable();
private:
NonCopyable(const NonCopyable&);
};
void foo(const NonCopyable&); void bar() {
foo(NonCopyable()); // Disallowed in C++98; allowed in C++11.
}
struct NonCopyable2 { NonCopyable2();
NonCopyable2(const NonCopyable2&);
};
void foo(const NonCopyable2&); void bar() {
foo(NonCopyable2()); // Disallowed in C++98; allowed in C++11.
}
Copy to clipboard
Note
If `NonCopyable2::NonCopyable2()` has a default argument
whose instantiation produces a compile error, that error will still
be a hard error in C++98 mode, even if this warning is disabled.
### Compiler crash diagnostics
The LLVM compilers might crash once in a while. Generally, this only
occurs when using the latest versions of LLVM.
LLVM goes to great lengths to provide assistance in filing a bug
report. Specifically, after a crash, it generates preprocessed source
files and associated run scripts. Attach these files to a bug report
to ease reproducibility of the failure. The following compiler option
is used to control the crash diagnostics.
- **-fno-crash-diagnostics**
- Disables auto-generation of preprocessed source files during an LLVM crash.
This option can be helpful for speeding up the process of generating
a delta reduced test case.
### Linker
- **-fuse-ld=(gold|bfd|qcld)**
- Specifies an alternative linker to use in place of the default system
linker.
Several mechanisms are provided for specifying the system linker that
is used in the Snapdragon LLVM Arm toolchain:
- **-fuse-ld**
- Causes the toolchain to use the specified linker as the system
linker. For example, gold, bfd, or qcld.
- **–gcc-toolchain**
- If -fuse-ld is not used, causes the toolchain to use whatever linker
is found in the GCC toolchain option path.
- **–sysroot**
- If neither -fuse-ld nor –gcc-toolchain are used, causes the
toolchain to use whatever linker is found in the specified sysroot.
If none of the these options are used, the toolchain uses the host
linker by default. However, this results in errors during linking.
The gold and bfd options are typically included in the GNU GCC
sysroots (version 4.7 and later). gold provides the plugin interface
that is necessary to support [Link-time optimization](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-use-compiler-link-time-optimization), while bfd does not.
The qcld option specifies the Snapdragon LLVM Arm linker. For more
information, see the *Qualcomm Snapdragon LLVM Arm Linker User Guide*
(80-VB419-102).
When using link-time optimization, the default system linker changes
to qcld. In this case, either qcld or gold must be used as the system
linker (otherwise, the optimization will fail).
Note
For more information on sysroots, see [Use GCC cross-compile environments](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-use-gcc-cross-compile-environments).
### Preprocessor
- **-A pred=<ans>**
- Asserts the predicate *pred* and answer *ans*.
- **-A -pred=<ans>**
- Cancels the specified assertion.
- **-ansi**
- Uses C89 standard.
- **-C**
- Retains comments during preprocessing.
- **-CC**
- Retains comments during preprocessing, including during macro expansion.
- **-d(DMNU)**
- Prints macro definitions or names based on the following arguments:
- **D**
- Prints macro definitions in -E mode in addition to normal output.
- **M**
- Prints macro definitions in -E mode instead of normal output.
- **N**
- Prints macro names in -E mode in addition to normal output.
- **U**
- Prints referenced macro definitions in -E mode in addition to normal
output. It also prints #undefs for macros that are undefined when
referenced.
- **-D <name>**
- Both are printed at the point they are referenced.
- **-D <name>=<definition>**
- Defines the specified macro symbol.
- **-fexec-charset=charset**
- Specifies the character set used to encode strings and character
constants. The default character set is UTF-8.
- **-finput-charset=charset**
- Specifies the character set used to encode the input files. The
default setting is UTF-8.
- **-fpch-deps**
- Causes the dependency-output options to additionally list the files
from a precompiled header’s dependencies.
- **-fpreprocessed**
- Notifies the preprocessor that the input file has already been
preprocessed.
- **-fstrict-overflow**
- Enforces strict language semantics for pointer arithmetic and signed
overflow.
- **-ftabstop=<width>**
- Specifies the tab stop distance.
- **-fwide-exec-charset=charset**
- Specifies the character set used to encode wide strings and character
constants. The default character set is UTF-32 or UTF-16, depending
on the size of wchar\_t.
- **-fworking-directory**
- Generates line markers in the preprocessor output. The compiler uses
this to determine what the current working directory was during
preprocessing.
- **-H**
- Displays the header includes and nesting depth.
- **–help**
- Displays the preprocessor release version.
- **-I <dir>**
- Adds the specified directory to the list of search directories for
header files.
- **-I-**
- Deprecated.
- **-include <file>**
- Includes the contents of the specified source file.
- **-isystem <prefix>**
- Treats an included file as a system header if it is found on the
specified path ([Section 4.3.30.6](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#control-diagnostics-in-system-headers)).
- **-isystem-prefix <prefix>**
- Treats an included file as a system header if it is found on the
specified sub-path of a defined include path ([Section 4.3.30.6](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#control-diagnostics-in-system-headers)).
- **-ino-system-prefix <prefix>**
- Does not treat an included file as a system header if it is found on
the specified sub- path of a defined include path ([Section 4.3.30.6](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#control-diagnostics-in-system-headers)).
- **-M**
- Outputs a make rule describing the dependencies of the main source file.
- **-MD**
- Equivalent to -M -MF *file*, except -E is not implied.
- **-MF <file>**
- Writes dependencies to the specified file.
- **-MG**
- Adds missing headers to the dependency list.
- **-MM**
- Equivalent to -M, except this operation does not mention header files
found in the system header directories.
- **-MMD**
- Equivalent to -MD, except this option only mention user header files,
not system header files.
- **-MP**
- Creates artificial target for each dependency.
- **-MQ <target>**
- Specify a target to quote for dependency.
- **-MT <target>**
- Specify target for dependency.
- **-nostdinc**
- Omits searching for header files in the standard system directories.
- **-nostdinc++**
- Omits searching for header files in the C++-specific standard directories.
- **-o <file>**
- Specifies the name of the preprocessor output file.
- **-P**
- Disables line marker output when using -E.
- **-remap**
- Generates code for file systems that only support short filenames.
- **–target-help**
- Displays all command options and exit immediately.
- **-traditional-cpp**
- Emulates pre-standard C preprocessors.
- **-trigraphs**
- Preprocesses trigraphs.
- **-U <name>**
- Cancels any previous definition of the specified macro symbol.
- **-v**
- Equivalent to -help.
- **-version**
- Displays the preprocessor version during preprocessing.
- **–version**
- Displays the preprocessor version and exit immediately.
- **-w**
- Suppresses all preprocessor warnings.
- **-Wall**
- Enables all warnings.
- **-Wcomment** | **-Wcomments**
- Generates a warning if a comment symbol appears inside a comment.
- **-Wendif-labels**
- Generates a warning if an #else or #endif directive is followed by text.
- **-Werror**
- Converts all warnings into errors.
- **-Wimport**
- Generates a warning when #import is used the first time.
- **-Wsystem-headers**
- Generates a warning for constructs declared in system header files.
- **-Wtrigraphs**
- Generates a warning if a trigraph forms an escaped newline in a comment.
- **-Wundef**
- Generates a warning if an undefined non-macro identifier appears in an #if directive.
- **-Wunused-macros**
- Generates a warning if a macro is defined without being used.
### Assembling
- **-fintegrated-as** | **-fno-integrated-as**
- Use the LLVM integrated assembler when compiling C and C++ source files.
-fno-integrated-as explicitly disables the use of the integrated
assembler. By default, the integrated assembler is enabled.
If a program can potentially generate hardware divide instructions
(SDIV, UDIV), we strongly recommend using the integrated assembler.
Older GNU assemblers might not understand these instructions.
When directly assembling a\*.s source file, the LLVM still invokes
the external assembler because it cannot correctly translate all GNU
assembly language constructions. As a result, not all GNU assembler
options (which are passed with the
-Wa option) will work with the integrated assembler.
The integrated assembler can process its own assembly-generated code,
along with most hand-written assembly that conforms to the GNU
assembly syntax.
- **-Xassembler <arg>**
- Passes the specified argument to the assembler.
### Linking
Starting with the LLVM 3.7 release, use clang as the driver for
linking.
- **object\_file\_name**
- Linker input file.
- **-c**
- Does not perform linking. This option is used with spec strings.
- **-dynamic**
- Links with a shared library (instead of a static library).
- **-E**
- Does not perform linking. This option is used with spec strings.
- **-l <library>**
- Searches the specified library file while linking.
- **-moslib=<library>**
- Searches the RTOS-specific library named liblibrary.a. The search
paths for the library and include files must be explicitly specified.
- **-nodefaultlibs**
- Does not use the standard system libraries when linking.
- **-nostartfiles**
- Does not use the standard system startup files when linking.
- **-nostdlib**
- Does not use the standard system startup files or libraries when linking.
- **-pie**
- Generates a position-independent executable as the output file.
- **-s**
- Deletes all symbol table information and relocation information from the executable.
- **-S**
- Does not perform linking. This option is used with spec strings.
- **-shared**
- Generates a shared object as the output file. The resulting file can
be subsequently linked with other object files to create an executable.
- **-shared-libgcc**
- Links with the shared version of the libgcc library.
- **-static**
- Does not link with the shared libraries. Only relevant when using dynamic libraries.
- **-static-libgcc**
- Links with the static version of the libgcc library.
- **-symbolic**
- Binds references to global symbols when building a shared object.
- **-u <symbol>**
- Pretends the *symbol* is undefined to force linking of library
modules to define *symbol*.
- **-Xlinker <arg>**
- Passes the specified argument to the linker.
### Directory search
- **-B<prefix>**
- Specifies the top-level directory of the compiler.
- **-F <dir>**
- Adds the specified directory to the search path for framework includes.
- **–gcc-toolchain=<prefix>**
- Equivalent to -B*prefix*.
- **-I <dir>**
- Adds the specified directory to the include file search path.
- **-I-**
- Deprecated.
- **-L<dir>**
- Adds the specified directory to the list of directories searched by the -l option.
- **–sysroot=<prefix>**
- Specifies the root directory of the system tools environment
([Section 4.4](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#use-gcc-cross-compile-environments)).
### Processor version
LLVM defines the -target, -march, and -mcpu options that are used to
specify the Arm processor version for which code is generated. If
none of these options are specified, the LLVM compilers, by default,
generate code for the lowest Armv4t instruction set architecture, in
Arm mode, for the Armv7tdmi CPU.
If the Armv7 or Armv8 architecture is specified using the -march or
-mcpu options, but Arm mode (that is, 32-bit-only mode) is not
specified on the command line, the LLVM compilers default to
generating code in Thumb-2 mode. To disable Thumb mode, use the
-mno-thumb or -marm options.
- **-target <triple>**
- Specifies the Arm architecture, operating system, and ABI for code
generation. The triple argument has the following format:
arch-platform-abi
For example, to generate code for Armv7-A architecture, which runs on
Linux and conforms to gnueabi, specify the following option:
`clang -target armv7a-linux-gnueabi foo.c`
The best way to specify the architecture version and CPU is by using
the -march and
-mcpu options respectively. Even though a target triple can be used
to specify the architecture, it must match the GCC tools sysroot
([Section 4.4](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#use-gcc-cross-compile-environments)).
Thus, the example command can be alternately expressed as follows:
clang -target arm-linux-gnueabi -mcpu=cortex-a9 foo.c Where cortex-a9
indicates the Armv7-A processor as the CPU. Following are some
commonly used target triples:
- arm-linux-gnueabi
- arm-none-linux-gnueabi (equivalent to arm-linux-gnueabi)
- arm-linux-androideabi (for code conforming to Android EABI)
- aarch64-linux-gnu (for Armv8 AArch64 mode)
- aarch64-linux-android (for code conforming to Android EABI)
- armv8-linux-gnu (for Armv8 AArch32 mode)
- arm-none-eabi (for Arm bare metal executables)
Note
In older versions of LLVM, the -target option was named
`-triple`.
- **-march=<version>**
- Specifies the Arm architecture for code generation. This option has
the following possible values:
- armv5e
- armv6j
- armv7
- armv7-a
- armv7-m
- armv8
- armv8-a
For more information on architecture versions, see [Section 4.3.15](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#processor-version).
- **-mcpu=<version>**
- Specifies the Arm CPU for code generation.
For a complete list of the values defined for this option, run the
following command:
`llvm-as | ras, uaops |
| -march=armv8.3-a | All armv8.2-a features plus ccidx, complxnum,
cpc, jsconv, pa |
| -march=armv8.4-a | All armv8.3-a features plus am, dit, dotprod,
fmi, mpam, nv, rasv8\_4, rcpc-immo, sel2,
tlb-rmi, tracev8.4 |
| -march=armv8.5-a | All armv8.4-a features plus altnzcv, bti,
ccdp, fptoint, predres, sb, specrestrict, ssbs |
[Table 4-5](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#_bookmark48) lists all the AArch64 features per
extension.
**Table 4-5 AArch64 extension-enabled features**
| aes | Enable AES support |
| --- | --- |
| altnzcv | Enable Armv8.5 alternative NZCV format for
floating-point comparisons |
| am | Enable Armv8.4-A Activity Monitors extension |
| bti | Enable Armv8.5 branch target identification |
| ccdp | Enable Armv8.5 cache clean to point of deep
persistence |
| ccidx | Enable Armv8.3-A extension of the CCSIDR number of
sets |
| ccpp | Enable Armv8.2 data cache clean to point of
persistence |
| complxnum | Enable Armv8.3-A floating-point complex number
support |
| crc | Enable Armv8 CRC-32 checksum instructions |
| crypto | Enable cryptographic instructions |
| dit | Enable Armv8.4-A data independent timing
instructions |
| dotprod | Enable dot product support |
| fmi | Enable Armv8.4-A flag manipulation instructions |
| fp-armv8 | Enable Armv8 FP |
| fp16fml | Enable FP16 FML instructions |
| fptoint | Enable Armv8.5 FRInt[32|64][Z|X] instructions that
round a floating-point number to an integer (in FP
format), forcing it to fit into a 32- or 64-bit
integer |
| fullfp16 | Enable Full FP16 instructions |
| jsconv | Enable Armv8.3-A JavaScript FP conversion
enhancement |
| lor | Enable Armv8.1 Limited Ordering Regions extension |
| lse | Enable Armv8.1 Large System Extension (LSE) atomic
instructions |
| mpam | Enable Armv8.4-A Memory System Partitioning and
Monitoring extension |
| neon | Enable advanced SIMD instructions |
| nv | Enable Armv8.4-A nested virtualization
enhancement |
| pa | Enable Armv8.3-A pointer authentication
enhancement |
| pan | Enable Armv8.1 Privileged Access-Never
extension |
| pan-rwv | Enable Armv8.2 PAN s1e1R and s1e1W variants |
| perfmon | Enable Armv8 PMUv3 Performance Monitors extension |
| predres | Enable Armv8.5-A execution and data prediction
invalidation instructions |
| rand | Enable random number generation instructions |
| ras | Enable Armv8 Reliability, Availability, and
Serviceability extensions |
| rasv8\_4 | Enable Armv8.4-A Reliability, Availability, and
Serviceability extension |
| rcpc | Enable support for RCPC extension |
| rcpc-immo | Enable Armv8.4-A RCPC instructions with immediate
offsets |
| rdm | Enable Armv8.1 rounding double multiply
add/subtract instructions |
| sb | Enable Armv8.5 speculation barrier |
| sel2 | Enable Armv8.4-A Secure Exception Level 2
extension |
| sha2 | Enable SHA1 and SHA256 support |
| sha3 | Enable SHA512 and SHA3 support |
| sm4 | Enable SM3 and SM4 support |
| spe | Enable Statistical Profiling extension |
| specrestrict | Enable Armv8.5 architectural speculation
restriction |
| ssbs | Enable Armv8.5 speculative store bypass safe bit |
| sve | Enable Scalable Vector Extension (SVE)
instructions |
| tlb-rmi | Enable Armv8.4-A TLB range and maintenance
instructions |
| tme | Enable Transactional Memory extension |
| tracev8.4 | Enable Armv8.4-A Trace extension |
| uaops | Enable Armv8.2 UAO PState |
| vh | Enable Armv8.1 Virtual Host extension |
#### AArch32 state
[Table 4-6](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#_bookmark50) lists the features enabled by default
with each architecture extension version. The features are
cumulative, for example, armv8.2-a enables all armv8.1-a features
plus some new features.
**Table 4-6 AArch32 features enabled by default**
| Extension version | Enabled features |
| --- | --- |
| -march=armv8.1-a | db, fp-armv8, neon, dsp, trustzone,
virtualization, crc, crypto |
| -march=armv8.2-a | All armv8.1-a features plus ras |
| -march=armv8.3-a | All armv8.2-a features |
| -march=armv8.4-a | All armv8.3-a features plus dotprod |
| -march=armv8.5-a | All armv8.4-a features plus sb |
| -march=armv8-r | Supports real-time profile (R series)
db, fp-armv8, neon, dsp, crc, dfb, mp,
virtualization |
| -mar
ch=armv8-m.base | Supports Armv8-M baseline instructions
db, 8msecext, noarm, acquire-release, hwdiv,
thumb-mode, mclass, strict- align, v7clrex |
| -mar
ch=armv8-m.main | Supports Armv8-M mainline instructions
db, 8msecext, noarm, acquire-release, hwdiv,
thumb-mode |
| -march
=armv8.1-m.main | Supports Armv8.1-M mainline instructions All
armv8-m.main features plus ras, lob |
[Table 4-7](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#_bookmark51) lists all the AArch32 features per
extension.
**Table 4-7 AArch32 extension-enabled features**
| 8msecext | Enable support for Armv8-M Security extensions |
| --- | --- |
| acquire-release | Enable support for Armv8 acquire and release
instructions |
| aes | Enable AES support |
| crc | Enable support for CRC instructions |
| crypto | Enable Cryptography extensions |
| db | Enable data barrier (dmb/dsb) instructions |
| dfb | Enable full data barrier instruction |
| dotprod | Enable support for dot product instructions |
| dsp | Enable DSP instructions in Arm or Thumb-2 |
| fp-armv8 | Enable Armv8 FP |
| fp16fml | Enable full half-precision floating-point FML
instructions |
| fpregs16 | Enable 16-bit FP registers |
| fpregs64 | Enable 64-bit FP registers |
| fullfp16 | Enable full half-precision floating point |
| hwdiv | Enable Divide Instructions in Thumb |
| lob | Enable Low Overhead Branch extensions |
| mp | Enable Multiprocessing extension |
| mve | Enable M-Class Vector extension with integer
operations
Implies support for Armv8.1-M mainline
instructions plus dsp, fpregs16, fpregs64 |
| mve.fp | Enable M-Class Vector extension with integer and
floating operations Implies mve plus fp-armv8,
fpregs16, fullfp16 |
| neon | Enable NEON instructions |
| noarm | Does not support Arm mode execution |
| ras | Enable Reliability, Availability, and
Serviceability extensions |
| sb | Enable Armv8.5-a speculation barrier |
| sha2 | Enable SHA1 and SHA256 support |
| strict-align | Disallow all unaligned memory access |
| thumb-mode | Support Thumb mode execution |
| trustzone | Enable support for Arm TrustZone security
extensions |
| v7clrex | Has Armv7-A clrex instruction |
| virtualization | Enable Virtualization extension |
#### Pointer Authentication Extension (PAuth)
PAuth can protect the integrity of code and data by detecting
malicious change of pointer values stored in memory. It can prevent
use of contaminated addresses as return addresses, C function
pointers, C++ virtual functions, C++ member function pointers, and so
on. The protection mechanism adds a signature to every code pointer
and certain data pointers, and then it authenticates the signatures
before using the pointers. In summary:
- A pointer is signed before being stored in memory.
- A pointer is authenticated before use.
- A signature or Pointer Authentication Code (PAC) is computed at
signing and compared at authenticating.
- When PAC authentication fails upon use of the pointer, the CPU traps,
allowing the operating system to choose the course of action.
The hardware support for the PAuth extension is available in
Armv8.3-A for AArch64 targets. It includes operations for signing and
authenticating pointers, stripping signatures out of pointers, and
PAC computation, which is performed by a hardware algorithm such as
QARMA
([https://www.qualcomm.com/media/documents/files/whitepaper-pointer-authentication-](https://www.qualcomm.com/media/documents/files/whitepaper-pointer-authentication-on-armv8-3.pdf)
[on-armv8-3.pdf](https://www.qualcomm.com/media/documents/files/whitepaper-pointer-authentication-on-armv8-3.pdf)).
Following is an example of using PAuth for software stack protection (PACRET).
PACIASP ; sign x30
SUB sp, sp, #0x40
STP x29, x30, [sp, #0x30]
ADD x29, sp, #0x30
...
...
LDP x29, x30, [sp, #0x30]
ADD sp, sp, #0x40
AUTIASP ; authenticate x30
RET
Copy to clipboard
The protection code is automatically generated by the compiler in the
function prologue and epilogue as shown in the assembly language, in
which the return address is saved on the stack after being signed
with PACIASP. Then it is authenticated with AUTIASP before use when
returning from the function.
LLVM toolchain support for PAuth is currently under development.
However, PACRET is currently supported. To enable it, set the
following flag:
`-mbranch-protection= -march=armv8.3-a` (or a
later version) The *<protection>* field can be set to
pac-ret{+leaf+b-key} where:
- pac-ret enables return address signing for non-leaf functions using
the A-key.
- +leaf increases the scope of return address signing to include leaf
functions.
- +b-key uses B-key instructions to sign addresses instead of A-key
instructions. For more details on PAuth, see the Arm documentation.
#### Branch Target Identification (BTI)
BTI is another security feature used to mitigate the JOP code reuse
form of attacks. These attacks take advantage of the fact that
indirect branches in the code can legally land anywhere in the
program.
BTI ensures that indirect branches must land on corresponding
instructions; it pairs every indirect instruction with a
corresponding legal instruction. Branching to an incompatible
instruction raises a branch target exception.
The different BTI identifications for a target consist of the
following:
- c - Target of indirect calls (BLR rn)
- j - Target of indirect jumps (BR rn)
- jc - Target of indirect jumps or calls
Following is an example of code protected by BIT, in which an
attacker finds an exploitable gadget in the code. The attacker
overwrites a stack location with a new function address to point to,
and then it tries to execute an indirect branch to it. However, the
call site expects that only an indirect call instruction can land on
that location, and thus an exception will be raised.
\_getBitsInByte:
bti c ;only an indirect call (blr) instruction can land on this target
mov x0, 0x8 ;return number of bits in a byte ldr x30, sp
ret
Copy to clipboard
\_readPasswordHeader:
mov x17, 0x1f0174ed0 ;put address of password file in scratch
register
ldr x0, x17 ;load from it (address left in register)
ldr x1, sp, #32 ;attacker overwrites [sp, #32] with start
address of _getBitsInByte
br x1 ;indirect jump using x1
...
Copy to clipboard
This security extension is available in Armv8.5a for AArch64 targets.
All the BTI instructions are in the NOP space, which means binaries
protected with BTI are backward– compatible.
The LLVM toolchain supports the BTI feature. To enable, set the
following flag:
`-mbranch-protection=bti -march=armv8.5-a` (or a later version)
For more details on BTI, see the Arm documentation.
#### Scalable Vector Extensions (SVE)
SVE is a SIMD vector extension introduced in Armv8.3 for Armv8-A
AArch64 target.
The extension is vector-length agnostic. It allows hardware
implementations to choose a vector register length between 128 to
2048 bits, in increments of 128 bits. With this extension, there is
no need to define a new ISA for new vector lengths.
In addition, this extension allows for a new programming model in
which software scales dynamically to the available vector length,
without requiring recompilation or rewriting hand-coded assembly or
compiler intrinsics for new vector lengths. This feature reduces
software deployment and deployment effort and cost.
Besides the support for scalable and longer vector types, SVE
supports predication, which is central to its design. A set of
scalable predicate registers govern predicates for load, store and
arithmetic operations, additional predicates for loop management, and
a first fault register (FFR) for software speculation.
When combined, all the these features help tackle traditional
barriers for compiler auto- vectorization. For example, the
extensions support software-managed speculative vectorization,
allowing uncounted loops to be vectorized. Moreover, in-vector
serialized inner loop permits outer loop vectorization in spite of
dependencies. These features help increase vector utilization, which
in turn leads to better program performance. Following are more
details on the new features:
- Gather-load and scatter-store
These instructions provide enhanced addressing modes for non-linear
data accesses. For example, instructions to load a single vector
register from non-contiguous memory locations.
- Per-lane predication
These instructions operate on individual lanes of a vector controlled
by of a governing predicate register. This feature allows
vectorization of loops containing complex control flow.
- Predicate-driven loop control and management
These instructions eliminate loop heads and tails and other overhead
by processing partial vectors, such as when handling leftover
iterations.
- Vector partitioning and software-managed speculation
Predicates help create sub-vectors (that is, partitions) in response
to data and dynamic faults. The extension supports first-fault load
instructions that allow vector access to safely cross a page
boundary, which, in turn, enables vectorizing uncounted loops with
break conditions or data dependent exits.
- Extended floating-point and bitwise horizontal reductions
These instructions are applicable to more types of reducible
loop-carried dependencies. For example, instructions that allow
in-order or tree-based floating-point sum.
SVE is not an extension of NEON. It is a separate, optional extension
with a new set of instruction encodings that target increased
parallelism in High Performance Computing (HPC) scientific code. You
can enable SVE in conjunction with the NEON extension.
The SDLLVM toolchain includes support to assemble source code
containing SVE instructions, disassemble ELF object files containing
SVE instructions, and use intrinsics to write SVE instructions
directly from C code.
SDLLVM also includes the Polly auto-vectorizer that takes advantage
of SVE scatter load and store instructions. Support for SVE
predication instructions within Polly is currently under development.
The following sections provide examples of these features.
##### Gather-load example
In this C code example and its corresponding assembly code, even and
odd indexed values are accessed separately, gathering non-contiguous
data from memory into vector registers with instruction ld2w. At the
end, Z0 contains the values A[0], A[2], A[4], A[6]; and Z1 contains
the values A[1], A[3], A[5], A[7]
C code:
void gather_load(int \*A, int \*B, int n) {
for (int I = 0; I < n; ++i) {
B[i] = A[0] + A[1]; A+=2;
}
}
Copy to clipboard
Assembly code:
.LBB1_9: // %polly.loop_header
// =>This Inner Loop Header: Depth=1
ld2w { z0.s, z1.s }, p0/z, [x15]
add x10, x10, x11
cmp x10, x9
add x15, x15, x14
add z0.s, z1.s, z0.s st1w { z0.s }, p0, [x16] add x16, x16, x13
b.ne .LBB1_9
Copy to clipboard
Memory and register layout:
##### Scatter-store example
In this C code example and its corresponding assembly code, even and
odd indexed values are stored into non-contiguous memory. Values 1
and 2 are stored into even indexed and odd indexed locations of A,
respectively, with instruction st2w. Z0 contains all 1s, and Z1
contains all 2s.
C code:
void scatter_store(int \*A, int \*B, int \*C, int n) {
for (int i =0; i < n; ++i) {
A[0] = 1;
A[1] = 2; A+=2;
}
}
Copy to clipboard
Assembly code:
mov z0.s, #1 // =0x1
...
mov z1.s, #2 // =0x2
...
.LBB2_4: // %polly.loop_header
// =>This Inner Loop Header: Depth=1
add x11, x11, x12
st2w { z0.s, z1.s }, p0, [x14]
cmp x11, x10
add x14, x14, x13
b.ne .LBB2_4
Copy to clipboard
Memory and register layout:
##### Per-lane predication example
This C code example and its corresponding assembly code use per-lane
predication through ACLE SVE intrinsics. SVE register Z0 contains
argument vector A, and Z1 corresponds to vector B. Predicate register
P0 corresponds to cc. Only the lanes mentioned as active by cc are used
for the addition.
C code:
#include
svint32_t per_lane_add(svbool_t cc, svint32_t A, svint32_t B) {
return svadd_s32_m(cc, A, B);
}
Copy to clipboard
Assembly code:
per_lane_add:
add z0.s, p0/m, z0.s, z1.s
ret
Copy to clipboard
Register layout:
##### For more details
See the ARM documentation.
### Security threat mitigation
As security vulnerabilities are discovered in software or hardware,
the LLVM community is committed to addressing them by fixing security
holes in compiler-generated code and related tools, as well as
providing hardware workarounds to mitigate threats. Following is an
overview of the current mitigation features available in the
compiler.
#### Spectre-Meltdown mitigation
Speculative Load Hardening is a best-effort mitigation against
information leak attacks that use control flow miss-speculation,
specifically miss-speculation of whether a branch is taken or not.
For a detailed discussion on Spectre-Meltdown mitigatio, go to the
discussion at: [https://llvm.org/docs/SpeculativeLoadHardening.html](https://llvm.org/docs/SpeculativeLoadHardening.html)
Enable the mitigation through a compiler flag:
`-mspeculative-load-hardening` and `-mno-speculative-load-hardening`
Or by using a function attribute:
>
>
> \_\_attribute\_\_((speculative\_load\_hardening))
> \_\_attribute\_\_((no\_\_speculative\_load\_hardening))
Check the Clang documentation for the precedence rules when combining
this flag and function attribute, and for the implications of
inlining optimization. Go to:
[https://clang.llvm.org/docs/AttributeReference.html#no-speculative-load-hardening](https://clang.llvm.org/docs/AttributeReference.html#no-URL%20speculative-load-hardening)
Finally, be aware this feature impacts performance.
### Code generation
- **-fasynchronous-unwind-tables**
- Generates an unwind table. The table is stored in DWARF2 format.
- **-fchar-array-precise-tbaa** | **-fno-char-array-precise-tbaa**
- Prevents aliasing of char arrays by non-char pointers.
This option causes the compiler to assume that no pointer other than
a pointer to char can reference an element in a char array.
The default setting is disabled.
Note
**-fchar-array-precise-tbaa** is enabled by default at the -Ofast level.
In the following example, enabling -fchar-array-precise-tbaa results
in the statement d = \*p being hoisted out of loops, because p is a
pointer to int.
typedef struct {
char a;
char b[100]; char c;
} S;
int \*p;
S x;
void func1 (char d) {
for (int i = 0; i < 100; i++) {
x.b[i] += 1;
d = *p;
x.a += d;
}
}
Copy to clipboard
- **-femit-all-data**
- Emits all data, even if unused.
- **-femit-all-decls**
- Emits all declarations, even if unused.
- **-ffp-contract=(fast|on|off)**
- Fused multiply add and subtract operations (VFMLA,VFMS) are more
accurate than chained multiply add and subtract operations (VMLA,
VMLS) because the chained operations perform rounding both after the
multiply and before the add/subtract. While rounding itself
introduces only a small error, cumulatively it can have a huge impact
on the final result.
While fused operations are IEEE compliant, it is not IEEE compliant
for the compiler to automatically replace a multiply followed by an
add/subtract (or VMLA/VMLS) with the equivalent fused operation,
since the numeric result can differ so much.
However, if you are explicitly specifying the use of a fused
operation, the substitution is considered IEEE compliant.
Fused operations are explicitly specified with the -ffp-contract
option. It has the following possible values:
- **fast**
Enables fused operations throughout the program.
- **on**
Enables fused operations according to the FP\_CONTRACT pragma (default).
- **off**
Disables fused operations throughout the program.
Note
This option must be used with the `-mfpu=neon-vfpv4` option.
Enabling fused operations causes the compiler to relax IEEE
compliance for floating- point computation.
- **-finstrument-functions**
- Generates instrumentation calls in function entries and exits.
- **-fmerge-functions** | **-fno-merge-functions**
- Attempts to merge functions that are equivalent, or differ by only a
few instructions ([Section 5.5](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#merge-functions)). The default
setting is disabled.
This option attempts to improve code size by merging similar
functions. It uses a number of heuristics to determine whether it is
worthwhile to merge a pair of functions. For instance, very small
functions or functions with significant differences are usually not
merged.
Note
Because this option might have a negative impact on program
performance, it is disabled by default. It becomes enabled only when
it is specified explicitly.
- **-fno-exceptions**
- Does not generate code for propagating exceptions.
- **-fpic**
- Generates position-independent code (PIC) for use in a shared library.
- **-fPIC**
- Generates position-independent code for dynamic linking, avoiding any
limits on the size of the global offset table.
- **-fpie** | **-fPIE**
- Generates position-independent code (PIC) for linking into executables.
- **-fsanitize=address** | **-fno-sanitize=address**
- Generates instrumentation for the address sanitizer ([Section 8.2](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#address-sanitizer)).
- **-fsanitize=memory** | **-fno-sanitize=memory**
- Generates instrumentation for the memory sanitizer ([Section 8.5](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#memory-sanitizer)).
- **-fsanitize=<event>[<,event>…]** | **-fno-sanitize=<event>[<,event>…]**
- Generates instrumentation for the undefined behavior sanitizer. You
can specify one or more events.
This option accepts the following event values:
- **alignment**
- Misaligned pointers or creating a misaligned reference.
- **bool**
- Loading boolean values that are neither true nor false.
- **bounds**
- Out-of-bounds array indexes (when the bounds can be statically determined).
- **enum**
- Loading enumeration values that are out-of-range for an enumeration type.
- **float-cast-overflow**
- Floating-point conversion that would overflow the destination.
- **float-divide-by-zero**
- Floating-point division by zero.
- **function**
- Indirect function calls through a pointer of the wrong type (Linux and C++ only).
- **integer-divide-by-zero**
- Divide an integer by zero.
- **nonnull-attribute**
- Return a NULL pointer from a function declared to never return NULL.
- **null**
- Use a NULL pointer or creating a NULL reference.
- **object-size**
- Attempts to use bytes that the optimizer can determine are not part
of the object being accessed. (Object sizes are determined with
builtin\_object\_size, so it might be possible to detect more problems
at higher optimization levels.)
- **return**
- In C++, reaching the end of a value-returning function without returning a value.
- **returns-nonnull-attribute**
- Return a NULL pointer from a function declared to never return NULL.
- **shift**
- Shift operators where the amount shifted is less than zero, or
greater than or equal to the promoted bit width of the left-hand
side, or where the left-hand side is negative. For a signed left
shift, it also checks for signed overflow in C and for unsigned
overflow in C++.
- **signed-integer-overflow**
- Signed integer overflow, including all the checks added by -ftrapv,
and checking for overflow in signed division (INT\_MIN / -1).
- **unreachable**
- Program control flow reaches builtin\_unreachable.
- **unsigned-integer-overflow**
- Unsigned integer overflows.
- **vla-bound**
- Variable-length arrays whose bounds do not evaluate to a positive value.
- **vptr**
- Use of an object whose vptr indicates that it is of the wrong dynamic
type, or that its lifetime has not begun or has ended. Incompatible
with -fno- rtti and -fsanitize-use-embedded-rt.
Note
Using this option requires user-defined diagnostic handler
functions. For more information, see the undefined behavior sanitizer
([Section 8.7](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#undefined-behavior-sanitizer)).
- **-fsanitize=integer**
- Generates instrumentation for the undefined behavior sanitizer for
the following events:
- signed-integer-overflow
- unsigned-integer-overflow
- shift
- integer-divide-by-zero
- **-fsanitize=undefined**
- Generates instrumentation for the undefined behavior sanitizer for
the following events:
- alignment
- bool
- bounds
- enum
- float-cast-overflow
- float-divide-by-zero
- function
- integer-divide-by-zero
- nonnull-attribute
- null
- object-size
- return
- returns-nonnull-attribute
- shift
- signed-integer-overflow
- unreachable
- vla-bound
- vptr
Note
The vptr event is not included when this option is used with
-fsanitize-use-embedded-rt.
- **-fsanitize-blacklist=<file>** | **-fno-sanitize-blacklist**
- Disables the generation of -fsanitize runtime checks in the specified
functions or source code files ([Section 8.1.1](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#special-case-lists)).
The specified option argument is a text file, where each line in the
file specifies the name of a function or source file:
- Function names are prefixed with fun:
- Filenames are prefixed with src:
For example:
# Disable checks in function and source file
fun:my_func
src:my_file
Copy to clipboard
Empty lines and lines starting with # are ignored.
You can specify file and function names using regular expressions,
but # works as it does in shell wildcards.
- **-fsanitize-memory-track-origins[=<level>]**
- Tracks the origin of uninitialized memory in the memory sanitizer
([Section 8.5](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#memory-sanitizer)). This option accepts the
following level values:
- 0 — Disable origin tracking
- 1 — Track and report where uninitialized values were allocated (default).
- 2 — Track and report where uninitialized values were allocated, along
with information on intermediate stores that the uninitialized values
went through.
- **-fsanitize-messages** | **-fno-sanitize-messages**
- Controls the generation of diagnostic messages for undefined behavior
violations when using -fsanitize-use-embedded-rt. Enabled by default.
- **-fsanitize-opt-size** | **-fno-sanitize-opt-size**
- Reduces the code size of undefined behavior runtime checks when using
-fsanitize-use-embedded-rt. Using this option might decrease program
performance. Disabled by default.
- **-fsanitize-source-loc** | **-fno-sanitize-source-loc**
- Controls the generation of file and line number information in
messages for undefined behavior violations when using
-fsanitize-use-embedded-rt.
Enabled by default, except when used with -fsanitize-opt-size, when
it is disabled by default.
- **-fsanitize-use-embedded-rt**
- Uses alternate undefined behavior sanitizer instrumentation and
runtime appropriate for embedded environments.
- **-fshort-enums** | **-fno-short-enums**
- Allocates to an enum type only as many bytes necessary for the
declared range of possible values. The default setting is disabled.
- **-fshort-wchar** | **-fno-short-wchar**
- Forces wchar\_t to be short unsigned int. The default setting is disabled.
- **-ftrap-function=<name>**
- Issues a call to the specified function rather than a trap instruction.
- **-ftrapv**
- Traps on integer overflow.
- **-ftrapv-handler=<name>**
- Specifies the function to be called in the case of an overflow.
- **-funwind-tables**
- Similar to -fexceptions, except that it only generates any necessary
static data, without affecting the generated code in any other way.
- **-fverbose-asm**
- Adds commentary information to the generated assembly code to improve
code readability.
- **-fvisibility=[default|internal|hidden|protected]**
- Sets the default symbol visibility for all global declarations.
- **-fwrapv**
- Treats signed integer overflow as two’s complement.
- **-mhwdiv=(arm|thumb|arm,thumb|none)**
- Controls the generation of hardware divide instructions in Arm or
Thumb mode.
- **arm**
Generate hardware divide instructions in Arm mode only
- **thumb**
Generate hardware divide instructions in Thumb mode only
- **arm, thumb**
Generate hardware divide instructions in Arm and Thumb modes
- **none**
Do not generate hardware divide instructions (default)
This option applies only to Armv7 processors that support hardware divide.
Note
`-mcpu=krait` automatically sets `-mhwdiv=arm,thumb`.
- **-mllvm -aarch64-disable-abs-reloc**
- Eliminates absolute relocation by changing all global variable
references to be PC- relative.
This option is commonly used with -mllvm -emit-cp-at-end.
- **-mllvm -aggressive-jt**
- A jump table is an efficient method to optimize switch statements by
replacing them with unconditional branch instructions and simple
operations to transfer program flow to them.
This option enables switch statements with small ranges to be
automatically converted to jump tables.
The default setting is disabled.
- **-mllvm -arm-expand-memcpy-runtime**
- Sets a threshold of 8 or 16 bytes for expanding (inlining) memcpy calls.
This option enables the generation of runtime checks for copy sizes 8
or 16 bytes, and inlining of memcpy calls that have copy sizes
smaller than or equal to 8 or 16 bytes. For any other copy size the
memcpy function is invoked.
Enabling this option causes an LLVM IR-level transformation. The
resultant code might be vectorized, if NEON is enabled.
This option is effective for optimization level equal or higher than
-O1, Os, and Oz. Otherwise, it is silently ignored.
- **-mllvm -arm-memset-size-threshold**
- Controls the code generation for memset library calls using NEON vector stores.
This option specifies the maximum number of bytes of data in memset
call that should be implemented with NEON vector stores. A memset
call with a data size above the specified threshold will not be
compiled into vector store operations.
The default setting is 128.
- **-mllvm -arm-memset-size-threshold-zeroval**
- Controls the code generation for memset library calls that write 0
value using NEON vector stores.
This option specifies the maximum number of bytes of data in memset
call that writes a 0 value that can be implemented with NEON vector
stores. A memset call that writes a 0 value with a data size above
the specified threshold will not be compiled into vector store
operations.
The default setting is 32.
- **-mllvm -arm-opt-memcpy**
- The optimized libc for Qualcomm® Krait™ CPU targets includes two
specialized memcpy functions for copy sizes greater than 8 and 16
bytes:
>
>
> memcpyGT8(void\*, const void\*, size\_t)
> memcpyGT16(void\*, const void\*, size\_t)
When this option is set with -mllvm -arm-expand-memcpy-runtime, the
compiler transforms the LLVM IR by replacing memcpy calls with the
runtime checks for a copy size less than or equal to 8 or 16 bytes
and these specialized memcpy calls. Their implementation uses vector
instructions and requires NEON to be enabled.
Also, set the option for the copy size threshold:
`-mllvm -arm-expand-memcpy-runtime`
This option has no effect if -mllvm -arm-expand-memcpy-runtime is disabled.
This option is effective for optimization level equal or higher than
-O1, Os and Oz. Otherwise it is silently ignored.
The default setting is disabled.
- **-mllvm -disable-thumb-scale-addressing**
- Controls the code generation of scaled immediate addressing in Thumb
mode. By default, scaled immediate addressing is enabled in Thumb
mode, unless `-mcpu=krait` is set in the command line.
To disable it, set -mllvm -disable-thumb-scale-addressing=true.
- **-mllvm -emit-cp-at-end**
- Place constant pool at the end of a function.
When this option is used in conjunction with -mllvm
-aarch64-disable-abs-reloc (which changes all global variable
references to be PC-relative), the compiler places the constant pool
at the end of a function.
The default setting is disabled.
In the following example, global variable a is loaded using the
default relocation code:
movz x8, #:abs_g3:a
movk x8, #:abs_g2_nc:a
movk x8, #:abs_g1_nc:a
movk x8, #:abs_g0_nc:a
ldr w0, [x8]
Copy to clipboard
Enabling this option with -mllvm -aarch64-disable-abs-reloc changes
the code to the following:
ldr x8, .LCPI0_0
ldr w0, [x8]
ret
.LCPI0_0:
.xword a // address of a
Copy to clipboard
- **-mllvm -enable-android-compat**
- Controls the generation of hardware divide instructions ([Section 4.4](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#use-gcc-cross-compile-environments)).
- **-mllvm -enable-arm-addressing-opt**
- Promotes use of optimized address modes by merging ADD operations
into the associated LOAD instruction.
The default setting is enabled.
- **-mllvm -enable-arm-peephole**
- Enables peephole optimizations to eliminate VMOV instructions, which
can be an expensive operations.
This option controls two peephole optimizations:
- Eliminate VMOVs from D to R to S
Eliminates excess VMOVs that result from copying a value from a D
register to an S register. There is no copy instruction from D to S,
so the code generator inserts a VMOV from D to R and then another
VMOV from R back to S.
This peephole optimization eliminates the VMOVs by using D registers
that alias S registers; registers D0-D15 are aliases as S0-S31. No
copy is necessary to get to an S register from these D registers.
- Eliminate VMOVs from D to R for an ADD operation.
Eliminates excess VMOVs that result from an ADD instruction whose
operands are defined by VMOVs from a D register. The ADD is replaced
with a horizontal ADD using the VPADD instruction and a VMOV to get
the result to the R register.
The default setting is enabled.
- **-mllvm -enable-arm-zext-opt**
- Removes redundant ZERO-EXTEND operations, for example, when preceded
by a LOAD instruction that zero-extends the value to 32 bits as part
of its operation.
The default setting is enabled.
- **-mllvm -enable-print-fp-zero-alias**
- When this option is used with -no-integrate-as, the compiler prints:
- FP compare-with-zero instructions using the alias format, fcmXY …
- #0 instead of the default LLVM format, fcmXY …
- #0.0 specified in the Armv8 documentation
This option ensures assembly code compatibility between LLVM and GNU
tools while the tools are out of sync (for example, the 4.9 GNU
assembler currently uses #0 syntax).
- **-mllvm -enable-round-robin-RA**
- Enables a round-robin register allocation heuristic that selects
registers avoiding back-to-back reuse to minimize false data
dependency. This heuristic works well for targets with limited
register renaming capability, as in Krait targets.
The default setting is disabled, unless -mcpu=krait is specified.
- **-mllvm -enable-select-to-intrinsics**
- Exposes more if statements to be converted to LLVM IR’s SELECT
instruction, which in turn can more easily be mapped to Arm hardware
instructions.
The default setting is disabled, unless -mcpu=krait is specified.
- **-mllvm -favor-r0-7**
- Enables a heuristic in the Greedy Register Allocator that better
guides the assignment of high-order registers (R8-R15) that are
currently avoided aggressively in the allocator. The allocator
exploits the fact that a Thumb-2 instruction that uses one of R8-15
registers must be encoded in 32 bits. So a candidate assigned to
these registers has a very a high cost.
With this option, the allocator avoids this register assignment based
on an additional cost, the candidate frequency in a function. The
benefits are better code size reduction, better performance/power
generated from better code density, and reduced spilling. This change
impacts mostly Thumb code generation, but Arm code generation can
also be affected because it disables R8-15 register avoidance.
The default setting is disabled.
Note
Use `-falign-inner-loops` with `-favor-r0-7` to achieve the
maximum benefit from loop alignment.
- **-mllvm -force-div-attr**
- Controls the generation of hardware divide instructions ([Section 4.4](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#use-gcc-cross-compile-environments)).
- **-mllvm -prefetch-locality-policy=(L1|L2|L3|stream)**
- Configures data prefetch to be temporal or non-temporal.
- L1
Temporal or retained prefetch allocated in L1 cache
- L2
Temporal or retained prefetch allocated in L2 cache
- L3
Temporal or retained prefetch allocated in L3 cache
- stream
Streaming or non-temporal prefetch
The default setting is L1.
Note
This option is available only for AArch64, and only when
`-fprefetch-loop-arrays` is enabled.
- **-mrestrict-it** | **-mno-restrict-it**
- Controls the code generation of IT blocks.
In the Armv8 architecture (AArch32), IT blocks are deprecated in
Thumb mode. They can only be one instruction long, and can only
contain a subset of all 16-bit instructions.
- **-mrestrict-it**
- Disallows the generation of IT blocks that are deprecated in the
Armv8 architecture.
- **-mno-restrict-it**
- Allows generation of legacy IT blocks (that is, deprecated forms in
the Armv7 architecture).
The default option setting is determined by the target Armv8 or Armv7
architecture. For Armv8 (AArch32) Thumb mode, -mrestrict-it is
enabled by default, while for other targets it is disabled by default.
### Vectorization
- **-ftree-vectorize**
- Alias of -fvectorize-loops, provided for GCC compatibility.
- **-fvectorize-loops**
- Performs automatic vectorization of loop code ([Section 5.3](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#automatic-vectorization)). Vectorization is subject to the
following constraints:
- On nested loops, it is performed only on the innermost loop.
- It can be used at any code optimization level higher than -O0.
- It works only with the Armv7 or Armv8 processor architecture with the
NEON extension. NEON is enabled either implicitly (by specifying a
CPU that has this extension with a -mfpu flag), or explicitly with
`-mfpu=neon`.
Note
`-fvectorize-loops` is enabled by default with -O2, -O3, -O4,
and -Ofast.
- **-fvectorize-loops-debug**
- Equivalent to -fvectorize-loops, but also generates a report
indicating that loops in the program were vectorized.
This option works best when used with the -g option to print out the
precise location of the loops that get vectorized.
Note
LLVM does not support the GCC `-ftree-vectorizer-verbose` option.
- **-fprefetch-loop-arrays[=<stride>]** | **-fno-prefetch-loop-arrays**
- Controls the automatic insertion of Arm PLD instructions into loops
that are vectorized.
The *stride* argument specifies the distance that the PLD instruction
attempts to load. If the argument is omitted, the compiler
automatically chooses a value.
The default setting is disabled.
Note
This option must be used with the `-fvectorize-loops` option.
### Parallelization
- **-fparallel**
- Performs automatic parallelization of loop code
([Section 5.4](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#automatic-parallelization)). Parallelization is subject
to the following restrictions:
- It must be specified (on the command line) when compiling each \*.c
or \*.cpp file.
- It must additionally be specified on the command line that directs
linking.
- It can be used only with -O2, -O3, -O4, or -Ofast.
### Optimization
- **-O0**
- Does not optimize. This is the default optimization setting.
- **-O** | **-O1**
- Enables a small set of optimizations. We do not recommend this
optimization level for performance or code size.
- **-O2**
- Enables optimizations for performance, including automatic loop
vectorization ([Section 4.3.20](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#vectorization)). Optimizations
enabled at -O2 improve performance, but they might cause a
small-to-moderate increase in compiled code size.
- **-O3**
- Enables aggressive optimizations for performance. Optimizations enabled
at -O3 improve performance, but they might cause a large increase in compiled
code size.
- **-O4**
- Similar to -Ofast, but also enables advanced loop fusion and data layout
optimizations for performance. Optimizations enabled at -O4 improve
performance, but they might cause a large increase in compiled code
size.
The Qualcomm LLVM compilers define -O4 differently from the standard
LLVM compiler. In particular, the Qualcomm compilers do not enable
[link-time optimization](https://docs.qualcomm.com/doc/80-VB419-99/topic/code_optimization.html#sec-link-time-optimization) in
-O4, while the standard compiler does enable it in -O4,additionally
mapping -O4 to -O3.
- **-Ofast**
- Enables all options at -O3, and increases the aggressiveness of
optimizations such as function inlining and loop unrolling. Also, -Ofast
enables fast math that allows floating-point computation optimizations.
User applications that require IEEE floating-point conforming code must
not use -Ofast because fast math does not preserve IEEE floating-point
requirements.
If -Ofast is combined with any other optimization level (-Os, -O0 to -O4)
in the command line, the last -O option prevails.
- **-Os**
- Enables optimizations for code size. Optimizations enabled at -Os reduce
code size at the cost of a small-to-moderate decrease in compiled code
performance.
- **-Osize**
- Enables -Os level optimizations and some additional options that trade
off performance for best code size. If -Osize is combined with any other
optimization level (-Os, -Ofast, -O0 to -O4) in the command line, the
last -O option prevails.
Note
This option is tuned for Armv7 targets only. It is not tuned
for Armv8 targets (AArch32 and AArch64) and therefore should not be used
with them.
- **-Oz**
- Enable optimizations for code size at the expense of performance.
Optimizations enabled with -Oz reduce code size at the cost of a
potentially significant decrease in compiled code performance.
#### Recommended options for best performance
The LLVM compilers generate the best performing code with the -Ofast
option. Examples:
- **-Ofast -mcpu=cortex-a57**
- Thumb mode and -fvectorize-loops are enabled by default.
- **-Ofast -mcpu=cortex-a57 -marm**
- Arm mode and -fvectorize-loops are enabled by default.
#### Recommended options for best code size
Currently, LLVM generates the smallest code when compiled for Thumb-2
mode. The following options are the recommended options to generate compact
code.
- **-Osize -mthumb**
- For 32-bit mode.
- **-Os**
- For 64-bit mode (AArch64).
### Specific optimizations
- **-faggressive-unroll**
- Use aggressive unroll heuristics to decide on unrolling loops. This
option results in more loops that are unrolled.
- **-fdata-sections**
- Assigns each data item to its own section.
- **-ffp-contract=[off|on|fast]**
- Forms fused floating-point operations such as fused
multiply-accumulates.
- off
Do not fuse operations.
- fast
(Default) Fuse operations whenever possible.
- on
Enable the FP\_CONTRACT default pragma.
- **-ffunction-sections**
- Assigns each function item to its own section in the output file. The
section is named after the function assigned to it.
- **-finline**
- Specifies the inline keyword as active.
- **-finline-functions**
- Performs heuristically-selected inlining of functions.
- **-floop-pragma**
- Enables auto-parallelization and auto-vectorization when using loop
pragmas.
- **-fno-zero-initialized-in-bss**
- Assigns all variables that are initialized to zero to the BSS
section.
- **-fnomerge-all-constants**
- Does not merge constants.
- **-fomit-frame-pointer**
- Does not store the stack frame pointer in a register if it is not
required in a function.
- **-foptimize-sibling-calls**
- Optimizes function sibling calls and tail-recursive calls.
- **-fstack-protector**
- Generates code that checks selected functions for buffer overflows.
- **-fstack-protector-all**
- Generates code that checks all functions for buffer overflows.
- **-fstack-protector-strong**
- Generates code that applies strong heuristic to check additional
selected functions for buffer overflows. Additional functions checked
include those with local array definitions or references to local
frame addresses.
- **-fstrict-aliasing**
- Enforces the strictest possible aliasing rules for the language being
compiled.
- **-funit-at-a-time**
- Parses the entire compilation unit before beginning code generation.
- **-funroll-all-loops**
- Unrolls all loops.
- **-funroll-loops**
- Unrolls selected loops.
- **-maggressive-size-opts**
- Enables additional optimizations that might be useful for bare metal images.
- **–param ssp-buffer-size=***size*
- Specifies the minimum size (in bytes) that a buffer must be if
buffer-overflow checks are to be generated for it by the
-fstack-protector options. The default value is 8.
### Math optimizations
- **-fassociative-math**
- Allows the operands in a sequence of floating-point operations to be
re-associated.
Because this option might reorder floating-point operations, it
should be used with caution when exact results are required (with no
expectation of an error cutoff).
To use this option, both -fno-signed-zeros and -fno-trapping-math
must be enabled, while -frounding-math must *not* be enabled.
The optimization flag, -frounding-math, is not supported:
[-Wignored-optimization-argument].
Note
This option enables additional features of [Automatic parallelization](https://docs.qualcomm.com/doc/80-VB419-99/topic/code_optimization.html#sec-automatic-parallelization).
- **-ffast-math**
- Enables the Fast-math mode in the compiler front end.
This option has no effect on optimizations, but it defines the
preprocessor macro `FAST_MATH`, which is the same as the GCC `-ffast-math`
option.
- **-ffinite-math-only**
- Enables optimizations that assume that floating-point argument and
result values are never NaNs nor +-Infs.
- **-fno-math-errno**
- Does not set errno after using single-instruction math functions.
- **-freciprocal-math**
- Enables optimizations that assume that the reciprocal of a value can
be used instead of dividing by the value.
- **-fno-signed-zeros**
- Enables optimizations that ignore the sign of floating-point zero values.
- **-fno-trapping-math**
- Enables optimizations that assume that floating-point operations
cannot generate user-visible traps.
- **-funsafe-math-optimizations**
- Enables code optimizations that assume the floating-point arguments
and results are valid, and that they might violate IEEE or ANSI standards.
This option enables the following:
- -fno-signed-zeros
- -fno-trapping-math
- -fassociative-math
- -freciprocal-math
### Link-time optimization
- **-flto**
- Performs [link-time optimization](https://docs.qualcomm.com/doc/80-VB419-99/topic/code_optimization.html#sec-link-time-optimization).
Use this option when the files in a program are compiled separately.
In this case, the option must be specified when compiling each source
file, and again when the compiler is used to link the resulting
object files.
When this option is used with -c, it produces a bitcode file that is
used during link- time optimization (LTO).
All compile-time options must be passed to the linker command line so
that LTO can generate code for the specified optimization level. To
ensure that the options are passed correctly, we strongly recommend
using clang/clang++ to perform the linking.
When this option is used, the default system linker changes to the
qcld linker, and either qcld or the gold linker must be used as the
system linker. You can specify the gold linker with the -fuse option
([Section 4.3.10](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#linker)).
Note
The gold linker cannot be used with the Windows version of
the LLVM compilers. In this case, only the qcld linker can be used to
perform LTO.
### Profile-guided optimizations
- **-fprofile-instr-generate[=<filename>]**
- Specifies the name and location of the raw profile data file to be
created. The default name is default.profraw.
The raw profile data file is used in instrumentation-based
profile-guided optimization ([Loop optimization pragmas](https://docs.qualcomm.com/doc/80-VB419-99/topic/code_optimization.html#sec-loop-optimization-pragmas)).
- **-fprofile-instr-use=<filename>**
- Uses the specified instrumentation-generated profile data file to
perform profile-guided optimization.
- **-fprofile-sample-use=<filename>**
- Uses the specified sampling-generated profile data file to perform
profile-guided optimization.
### Optimization reports
- **-fopt-reporter=(vectorizer|parallelizer|all)**
- Requests the specified type of optimization report data ([Optimization reports](https://docs.qualcomm.com/doc/80-VB419-99/topic/code_optimization.html#sec-code-optimization-optimization-reports)).
- **-polly-max-pointer-aliasing-checks**
- Increases the number of runtime checks that are allowed to be
inserted into a loop in order to disambiguate the pointers, thus
enabling the loop to be vectorized.
- **-Rpass=loop-opt**
- Outputs the line numbers of the loops that were auto-parallelized
and/or vectorized.
- **-Rpass-missed=loop-opt**
- Outputs the line number and reason why a loop was not optimized.
### Compiler security
- **–analyze**
- Invokes the static program analyzer ([Static analyzer](https://docs.qualcomm.com/doc/80-VB419-99/topic/compiler_security_tools.html#sec-static-analyzer)) on the specified input files.
- **-analyzer-checker=<checker>**
- Enables the specified checker or checker category in the static
program analyzer. The checker categories are alpha, core, cplusplus,
debug, and security.
Enabling a checker category enables all the checkers in that
category. For a complete list of checker names use -analyzer-checker-help.
Note
`-analyzer-checker` must be prefixed with `-Xclang`.
- **-analyzer-checker-help**
- Lists the complete set of checkers and their categories for use in
`-analyzer-checker` and `-analyzer-checker-disable`.
Note
`-analyzer-checker-help` must be prefixed with `-cc1`.
- **-analyzer-disable-checker=<checker>**
- Disables the specified checker or checker category in the static
program analyzer. The checker categories are alpha, core, cplusplus,
debug, and security.
Disabling a checker category disables all the checkers in that
category.
For a complete list of checker names use -analyzer-checker-help.
Note
`-analyzer-disable-checker` must be prefixed with `-Xclang`.
- **–analyzer-output html**
- Generates the static analyzer output report in HTML format.
Note
`--analyzer-output` and its argument must each be prefixed
with `-Xclang`.
- **–analyzer-Werror**
- Converts all static analyzer warnings into errors.
- **–compile-and-analyze <dir>**
- Invokes the static program analyzer on an entire program. The
analysis report files are written to the specified directory.
To prevent the analyzer from generating HTML files and instead print
a summarized report on the stdout, replace dir with the sub-flag,
`--analyzer-perf`.
- **–compile-and-analyze-high**
- Invokes the static program analyzer on an entire program with only a
small list of high priority checkers.
The analysis report files are written to the specified directory. If
you use the sub-flag, –analyzer-perf, they are printed to the stdout.
- **–compile-and-analyze-medium**
- Invokes the static program analyzer on an entire program with a list
of high+medium priority checkers.
The analysis report files are written to the specified directory. If
you use the sub-flag, `--analyzer-perf`, they are printed to the stdout.
- **-ffcfi**
- Enables control-flow integrity checks ([Control flow integrity](https://docs.qualcomm.com/doc/80-VB419-99/topic/compiler_security_tools.html#sec-control-flow-integrity)).
- **-fno-fcfi**
- Disables control-flow integrity checks.
### LLVM 4.0-specific compiler flags
**Table 4-8 LLVM 4.0 release: New compiler flags**
| **Flag** | **Description** |
| --- | --- |
| -fcoroutines-ts | Enables support for the C++
Coroutines TS |
| -fno-coroutines-ts | Disables support for the C++
Coroutines TS |
| -fdebug-info-for-profiling | Emits extra debug information to
make sample profile more accurate |
| -fno
-debug-info-for-profiling | Does not emit extra debug
information for sample profiler |
| -fbuiltin-module-map | Loads the clang built-in intrinsics
module map file |
| -fdiagnostics-show-hotness | Enables profile hotness information
in a diagnostic line |
| -fno-
sanitize-address-use-after-
scope | Disables use-after-scope detection
in AddressSanitizer |
| -fsa
nitize-thread-memory-access | Enables memory access
instrumentation in ThreadSanitizer
(default) |
| -fno-sa
nitize-thread-memory-access | Disables memory access
instrumentation in ThreadSanitizer |
| -fsani
tize-thread-func-entry-exit | Enables function entry/exit
instrumentation in ThreadSanitizer
(default) |
| -fno-
sanitize-thread-func-entry-
exit | Disables function entry/exit
instrumentation in ThreadSanitizer |
| -fsanitize-thread-atomics | Enables atomic operations
instrumentation in ThreadSanitizer
(default) |
| -fno
-sanitize-thread-atomics | Disables atomic operations
instrumentation in ThreadSanitizer |
| -fno-ex
perimental-new-pass-manager | Disables an experimental new pass
manager in LLVM. |
| -flto-jobs= | Controls the back-end parallelism
of -flto=thin (default of 0 means
the number of threads will be
derived from the number of CPUs
detected) |
| -fprebuilt-module-path= | Specify the prebuilt module path |
| -fmodules
-disable-diagnostic-
validation | Disable validation of the
diagnostic options when loading the
module |
| -fmodules-ts | Enable support for the C++ modules
TS |
| -fno
-diagnostics-show-hotness | Disable profile hotness information
in diagnostic line |
| -fdiagnostics
-absolute-paths | Print absolute paths in diagnostics |
| -frel
axed-template-template-args | Enable C++17 relaxed-template
template argument matching |
| -fno-rel
axed-template-template-args | Disable C++17 relaxed-template
template argument matching |
| -faligned-allocation | Enable C++17-aligned allocation
functions |
| -fno-aligned-allocation | Disable C++17-aligned allocation
functions |
| -faligned-new | Enable C++17-aligned allocation
functions |
| -fno-aligned-new | Enable C++17-aligned allocation
functions |
| -fropi | Enable Arm read-only position
independence relocation model |
| -fno-ropi | Disable Arm read-only position
independence relocation model |
| -frwpi | Enable Arm read-write position
independence relocation model |
| -fno-rwpi | Disable Arm read-write position
independence relocation model |
| -fpreserve-as-comments | Preserve comments in inline
assembly |
| -fno-preserve-as-comments | Do not preserve comments in inline
assembly |
| -fdebug-macro | Emit macro debug information |
| -fno-debug-macro | Do not emit macro debug information |
| -fsave-optimization-record | Generate a YAML optimization record
file |
| -fno
-save-optimization-record | Do not generate a YAML optimization
record file |
| -foptimization-record-file= | Specify the filename of any
generated YAML optimization record |
| -fstrict-return | Always treat control flow paths
that fall off the end of a non-void
function as unreachable |
| -fno-strict-return | Do not treat control flow paths
that fall off the end of a non-void
function as unreachable |
| -fsplit-dwarf-inlining | Place debug types in their own
section (ELF Only) |
| -fno-split-dwarf-inlining | Do not place debug types in their
own sections (ELF only) |
| -mlong-calls | Generate branches with extended
addressability, usually via
indirect jumps. |
| -mno-long-calls | Restore the default behavior of not
generating long calls |
| -mexecute-only | Disallow generation of data access
to code sections (Arm only) |
| -mno-execute-only | Allow generation of data access to
code sections (Arm only) |
| -mpure-code | Alias for mexecute\_only |
| -mno-pure-code | Alias for mno\_execute\_only |
| -mpie-copy-relocations | Use copy relocations support for
PIE builds |
| -mno-pie-copy-relocations | Do not use copy relocations support
for PIE builds |
| -mfentry | Insert calls to fentry at function
entry (x86 only) |
| -save-stats | Save LLVM statistics |
| -precompile | Precompile only the input |
### Control diagnostic messages
LLVM provides a number of ways to control which code constructs cause
the compilers to emit errors and warning messages, and how the
messages are displayed on the console.
#### Control how diagnostics are displayed
When LLVM emits a diagnostic message, it includes rich information in
the output and provides control over which information is printed.
LLVM has the ability to print this information. The following options
are used to control the information:
- A file/line/column indicator that shows exactly where the diagnostic
occurs in the code.
- A categorization of the diagnostic as a note, warning, error, or
fatal error.
- A text string describing the problem.
- An option indicating how to control the diagnostic (for diagnostics
that support it) [-fdiagnostics-show-option].
- A high-level category for the diagnostic for clients that want to
group diagnostics by class (for diagnostics that support it)
[-fdiagnostics-show-category].
- The line of source code that the issue occurs on, along with a caret
and ranges indicating the important locations [-fcaret-diagnostics].
- *FixIt* information, which is a concise explanation of how to fix the
problem (when LLVM is certain it knows) [-fdiagnostics-fixit-info].
- A machine-parseable representation of the ranges involved (disabled
by default) [-fdiagnostics-print-source-range-info].
For more information on these options see [Diagnostic format](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-diagnostic-format).
#### Diagnostic mappings
All diagnostics are mapped into one of the following classes:
- Ignored
- Note
- Warning
- Error
- Fatal
#### Diagnostic categories
Though not shown by default, diagnostics can each be associated with
a high-level category. This category is intended to make it possible
to triage builds that generate a large number of errors or warnings
in a grouped way.
Categories are not shown by default, but you can turn them on with
the `-fdiagnostics-show-category` option (see [Diagnostic format](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-diagnostic-format)).
When this option is set to name, the category is printed textually in
the diagnostic output. When set to id, a category number is printed.
Note
You can get the mapping of category names to category
identifiers by invoking LLVM with the `-print-diagnostic-categories`
option.
#### Control diagnostics with compiler options
LLVM can control which diagnostics are enabled through the use of
options specified on the command line.
The -W options are used to enable warning diagnostics for specific
conditions in a program. For instance, -Wmain will generate a warning
if the compiler detects anything unusual in the declaration of
function main().
-Wall enables all the warnings defined by LLVM. -w disables all of
them.
Disable warnings for a specific condition by specifying the
corresponding -W*cond* option as - Wno-*cond*. For instance,
-Wno-main disables the warning normally enabled by -Wmain.
-Werror=*cond* changes the specified warning to an error
([Warning and error messages](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-warning-and-error-messages)). If -Werror is specified
without a condition, *all* the warnings are changed to errors.
-ferror-warn changes only the warnings that are listed in the
specified text file.
-pedantic and -pedantic-errors enable diagnostics that are required
by the ISO C and ISO C++ standards.
#### Control diagnostics with pragmas
LLVM can also control which diagnostics are enabled through the use
of pragmas in the source code. This is useful for disabling specific
warnings in a section of source code. LLVM supports GCC’s pragma for
compatibility with existing source code, as well as several
extensions.
The pragma can control any warning that can be used from the command
line. Warnings can be set to ignored, warning, error, or fatal. The
following example instructs LLVM or GCC to ignore the -Wall warnings:
>
>
> #pragma GCC diagnostic ignored “-Wall”
In addition to all the functionality provided by GCC’s pragma, LLVM
also enables you to push and pop the current warning state. This is
useful when writing a header file that will be compiled by other
people, because you do not know what warning flags they build with.
In the following example, -Wmultichar is ignored for only a single
line of code, after which the diagnostics return to whatever state
had previously existed:
>
>
> #pragma clang diagnostic push
> #pragma clang diagnostic ignored “-Wmultichar”
>
>
> char b = ‘df’; // no warning.
>
>
> #pragma clang diagnostic pop
The push and pop pragmas save and restore the full diagnostic state
of the compiler, regardless of how it was set. Thus, it is possible
to use push and pop around GCC-compatible diagnostics—LLVM will push
and pop them appropriately, while GCC will ignore the pushes and pops
as unknown pragmas.
Note
While LLVM supports the GCC pragma, LLVM and GCC do not
support the same set of warnings. Thus even when using GCC-compatible
pragmas there is no guarantee that they will have identical behavior
on both compilers.
#### Control diagnostics in system headers
Warnings are suppressed when they occur in system headers. By
default, an included file is treated as a system header if it is
found in an include path specified by -isystem, but you can override
this in several ways.
- Use the system\_header pragma to mark the current file as being a
system header. No warnings will be produced from the location of the
pragma onwards within the same file.
>
>
> char a = ‘xy’; // warning
>
>
> #pragma clang system\_header
>
>
> char b = ‘ab’; // no warning
- Use the -isystem-prefix and -ino-system-prefix options to override
whether subsets of an include path are treated as system headers.
When the name in a #include directive is found within a header search
path and starts with a system prefix, the header is treated as a
system header. The last prefix on the command line that matches the
specified header name takes precedence.
For example:
>
>
> $ clang -Ifoo -isystem bar -isystem-prefix x/
> -ino-system-prefix x/y/
Here, #include “x/a.h” is treated as including a system header, even
if the header is found in foo. And #include “x/y/b.h” is treated as
not including a system header, even if the header is found in bar.
An #include directive that finds a file relative to the current
directory is treated as including a system header if the including
file is treated as a system header.
#### Enable all warnings
In addition to the traditional `-W` flags, you can enable *all*
warnings by specifying the `-Weverything` option.
`-Weverything` works as expected with `-Werror`, and it also includes the
warnings from `-pedantic`.
Note
When this option is used with `-w` (which disables all
warnings), `-w` takes priority.
## Use GCC cross-compile environments
The LLVM compilers are standalone compilers that rely on an existing
system tools root environment—also known as *sysroot*—for accessing
include files and libraries. The compilers are prebuilt to work with
a GCC sysroot environment. To include header files and libraries in
the build, they assume a predefined directory structure anchored by a
GCC system root directory. For example, the GCC sysroot for the Armv8
AArch64 toolchain has the following structure:
/aarch64-linux-gnu/
/bin/
/debug-root/
/include/
/include/c++/4.8.2/
/backward/
/lib/
/libc/
/usr/
/include/
Copy to clipboard
The top level of the GCC tools directory must have a subdirectory
that matches the target triple specified on the compiler command line
([Processor version](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-processor-version)). The target triple
directory typically contains a libc directory that mimics a host
compilation environment by storing the following items:
- The library files in GCC-top/target-triple/libc/lib
- The include files in GCC-top/target-triple/libc/usr/include
Thus the sysroot location is GCC-top/target-triple/libc., which is
specified with the compile option, –sysroot.
The LLVM compilers also require the location of the GNU linker (if
they are not using qcld). This location is specified with the -B or
-gcc-toolchain option, and it must point to the top of the GCC
toolchain directory. For example, the following two LLVM commands
compile a source file and generate code for the Armv8 AArch64 ISA:
>
>
> clang -target aarch64-linux-gnu –sysroot=GCC-top/aarch64-linux-gnu/libc -B GCC-top foo.c
> clang -target aarch64-linux-gnu –sysroot=GCC-top/aarch64-linux-gnu/libc –gcc-toolchain=GCC-top foo.c
With C++, it might be necessary to add a set of C++ include
directories so the LLVM compilers can correctly search for the header
files. This is required only with certain GCC toolchain sysroots. In
such cases, the following directories should be added to the LLVM
compiler command using the -isystem option:
>
>
> -isystem GCC-top/include/c++/GCC-version
> -isystem GCC-top/include/c++/GCC-version/triple
> -isystem GCC-top/include/c++/GCC-version/backward
Where *GCC-version* indicates the version number of the GCC toolchain
(4.6, 4.8.1, and so on).
This target triple might differ from the target triple used on the
compiler command line.
## Use LLVM with GNU Assembler
Snapdragon LLVM includes support for using the GNU Assembler (GAS) as
the system assembler. The -mllvm -enable-android-compat and -mllvm
-force-div-attr options ([Code generation](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-code-generation)) are
used to control the generation of hardware divide instruction so it
is compatible with various versions of GAS.
By default, the LLVM compiler only emits the DIV attribute when the
`-mhwdiv` option is specified. Depending on the GAS version, it might
be necessary to change this default behavior. Use the following
guideline:
- GCC 4.6 and older releases
The DIV attribute is not emitted by GCC/GAS compiler/assembler.
When using LLVM with this GNU version, specify the -mllvm
-enable-android- compat option.
- GCC 4.6 and 4.7 releases
The DIV attribute is emitted whether or not the -mhwdiv option is
specified. It is given a different value depending on the target
architecture specified:
- 0 — Allow hardware division if supported in the target architecture,
or if no information exists.
- 1 — Disallow hardware division.
- 2 — Allows hardware division as an optional extension above the base
target architecture hardware features.
When using LLVM with this GNU version, you must specify the -mllvm
-force-div- attr option.
- Post GCC 4.7 releases
The DIV attribute is emitted only when the -mhwdiv option is
specified.
## Built-in functions
The arm\_memcpy\_bias.h file contains the declaration of a specialized
Arm 32-bit memcpy built-in function for a copy size of 1024.
>
>
> builtin\_neon\_memcpy\_1024(void\*, const void\*, size\_t)
Using this function in the source results in generated code with a
runtime check for a copy size of 1024, and the inlining of memcpy for
a copy size of 1024 using vector instructions.
Note
NEON must be enabled to use this built-in.
## Compilation phases
The LLVM compiler consists of a driver program (named cc1), which in
turn invokes a set of tools that perform the various phases of the
overall compilation process.
### View phases
To view these phases during compilation, invoke the compiler using
the `-ccc-print-phases` option ([Compilation](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-compilation)). For example:
>
>
> clang -ccc-print-phases test.c
This option prints the following information during compilation:
0: input, "test.c", c
1: preprocessor, {0}, cpp-output
2: compiler, {1}, assembler
3: assembler, {2}, object
4: linker, {3}, image
Copy to clipboard
This option is useful when paired with options that control
compilation. For example:
clang -c -ccc-print-phases test.c 0: input, "test.c", c
1: preprocessor, {0}, cpp-output
2: compiler, {1}, assembler
3: assembler, {2}, object
clang --analyze -ccc-print-phases test.c
0: input, "test.c", c
1: preprocessor, {0}, cpp-output
2: analyzer, {1}
Copy to clipboard
### View phase commands
To view the actual tool commands performed by the driver program at
each compilation phase, invoke the compiler using the -### option
([Compilation](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-compilation)). For example:
clang -### test.c --sysroot=
--gcc-toolchain=
--target=aarch64-linux-android
Copy to clipboard
This option prints the following command information:
- Preprocessor and compiler:
"clang" "-cc1" "-triple" "armv4t--linux-androideabi" "-emit-obj"
..
"-o" "/tmp/t-871e8e.o" "-x" "c" "t.c"
Copy to clipboard
- Linker:
"ld" "--sysroot=..."
...
"-o" "a.out"
...
"/tmp/t-2e40e1.o"
Copy to clipboard
### Specify phase options
To pass a command option to the tool that performs a specific
compilation phase, invoke the compiler using the -X option
([Compilation](https://docs.qualcomm.com/doc/80-VB419-99/topic/use_the_compilers.html#sec-compilation)). For example:
clang -Xlinker --print-map test.c
Copy to clipboard
In this example, -X is used to pass the –print-map option to the
linker.
-X specifies the tool that the option will be passed to:
| -Xclang | Compiler |
| --- | --- |
| -Xassembler | Assembler |
| -Xlinker | Linker |
| -Xanalyzer | Static analyzer |
If the option to be passed contains one or more arguments that are
separated from the option name by spaces, you must use -X multiple
times in order to pass the option. For example:
clang --analyze -Xclang -analyzer-output -Xclang html
-o test.c
Copy to clipboard
In this example, -X is used twice to pass the -analyzer-output html
option to the compiler.
Last Published: May 10, 2024
[Previous Topic
Get started](https://docs.qualcomm.com/bundle/publicresource/80-VB419-99/topics/get_started.md) [Next Topic
Code optimization](https://docs.qualcomm.com/bundle/publicresource/80-VB419-99/topics/code_optimization.md)