RELEASE_NOTES

This is the Snapdragon LLVM ARM C/C++ compiler toolchain 4.0.2 release. This
is a cross toolchain built to run on x86 64-bit Ubuntu Linux (versions 12.04
and later). The Snapdragon LLVM ARM Compiler will only generate code for ARM
targets and will not generate code for any of the other targets supported by
the AOSP LLVM compiler.

Version 4.0 of the Snapdragon LLVM ARM Compiler includes all changes in the 
llvm.org 4.0 release, and additionally includes patches that are post-4.0 
llvm.org release. This version of the Snapdragon LLVM ARM toolchain includes 
proprietary features and optimizations that are not available in the llvm.org
release or the AOSP LLVM compiler.

The Snapdragon LLVM ARM Compiler uses the integrated assembler for assembling
and includes a full featured proprietary linker (QC Linker) for linking. For 
Android, the QC Linker is primarily used for Link Time Optimization (LTO).

The link below contains all the new features in the llvm.org 4.0 release.
http://releases.llvm.org/4.0.0/docs/ReleaseNotes.html

The Snapdragon LLVM ARM 4.0 toolchain contains all the above features, and 
additionally contains the following key features compared to the Snapdragon
LLVM ARM 3.9 release:

1. Compiler Features
  - Improvements to armv7/aarch32 vector code generation
  - Code size optimizations
2. Security/Code Hygiene
  - Support for whitelisting directories for static analyzer
  - Allow blacklisting of bugs using an external file in static analyzer
  - New options for specifying priority of static analyzer checkers 
  - Availability of post processing script for Windows host platform
  - New options for running the Static Analyzer on performance mode
  - New checkers added to static analyzer

This version of the Snapdragon LLVM ARM toolchain may generate additional 
front-end warnings compared to the SDLLVM 3.9 version.  However, we expect
it to be better performing than the 3.9 release.  We recommend using this 
version for performance critical components (where possible).

The complete Compiler User Guide for this release of the Snapdragon LLVM ARM
Compiler is avaialble as part of your download package under
llvm-Snapdragon_LLVM_for_Android_4.0/prebuilt/<platform>/Snapdragon
_LLVM_ARM_40_Compiler_User_Guide.pdf.

Please post all questions about this release to
http://developer.qualcomm.com/llvm-forum.

Basic Usage & Examples:

clang and clang++ are the C and C++ drivers respectively of Snapdragon
LLVM ARM Compiler. They require users to specify the assembler and linker
explicitly.

For Windows:

In order to use the drivers you need to specify a Windows version of the GCC
cross toolchain as the sysroot.

To invoke the compiler from a Windows command prompt:

set PATH=<path-to-compiler-bin>;<path-to-sysroot-bin>;%PATH%

clang.exe -mfloat-abi=softfp --sysroot=<path/to/sysroot> foo.c

NOTE:
On Windows, the LTO feature can only be used with the QC linker (ld.qcld).
It cannot be used with the gold linker plugin since the plugin is not
available for Windows platform.

For Linux:

Note that the Linux version of clang is built with support for using GCC 4.9.0
sysroot by default. Users can use a different sysroot (such as GCC-4.8 
sysroot) by using the --sysroot option as described in section 4.5 of the 
Snapdragon LLVM ARM Compiler User Guide.

Examples of clang driver usage on Linux:
clang -march=armv7-a -mfloat-abi=softfp -mfpu=neon -O3 -o foo foo.c
clang++ -mcpu=krait -mfloat-abi=softfp -mfpu=neon -Os -mthumb -o bar bar.cpp
clang++ -mcpu=krait -mfloat-abi=softfp -mfpu=neon \
--sysroot=</path/to/another-gcc-sysroot> -Ofast -c test.cpp

For Android:

For generating executables that can be executed on ARM Linux and Android
environment, we recommend using -static linker flag to enable generation of
static executables which do not have dependence on runtime OS libraries.

Options:

To find out the most common options, please pass the -help flag to the clang
driver. This will report the Snapdragon LLVM ARM specific options and
general ARM options first, before listing target independent options
available in the Snapdragon LLVM ARM Compiler.

Compiler options for best performance:

For 64-bit applications, we recommend using "-Ofast -mcpu=cortex-a57" options
for best performance on Kryo and Cortex-a57 cores, and "-Ofast
-mcpu=cortex-a53" for best performance on Cortex-a53 cores.

For 32-bit, we recommend using the "-Ofast -mcpu=krait" options for best
performance of your application on Krait cores. For non-Krait 32-bit cores, we
recommend using the "-Ofast" option. If you would like to avoid the generation
of Krait specific instructions (hardware divide, fused-mac) to enable running
on a variety of ARMv7 cores, but still optimize for best performance on Krait
cores, we recommend the "-Ofast -march=armv7-a -mfpu=neon" options.

The -Ofast option enables several high performance optimizations such as
Auto-vectorizer. Please refer to section 4.3.19 of the Snapdragon LLVM ARM
Compiler User Guide for more details.

Compiler options for smallest code-size:

We recommending using the "-Osize -mthumb" options to generate the most
compact code with the Snapdragon LLVM ARM 4.0 compiler. Please refer to
section 3.4.19 of the Snapdragon LLVM ARM Compiler User Guide for more details
on the -Osize optimization level.

Compiling for AArch64:
To compile for AArch64 (ARMv8 64-bit mode), please pass the following option
to clang:
 -target aarch64-linux-gnu

Compiling for AArch32:
To compile for AArch32, please pass the following option to clang:
 -target armv8-linux-gnueabi

Note that even though AArch32 ISA is fully backward compatible with ARMv7 ISA,
there are newer instructions in AArch32 ISA compared to ARMv7 ISA.
This means that AArch32 executables cannot be executed on ARMv7 cores such
as Krait.

Please refer to section 3.4.19 of the Snapdragon LLVM ARM Compiler User Guide
to learn about various optimization flags.

LLVM's Support for GCC command line options:

Most of the commonly used GCC options are supported by LLVM as well. A
detailed list of options supported is listed in chapter 3 of the Snapdragon
LLVM ARM Compiler User Guide.