Documentation: Additional optimization levels for ARM/Linux (#6548)

This instruction is to enable -Ofast or -Oz optimization level of clang on ARM/Linux.
Below is file-size comparison result of major components among -O3, -Ofast,
and -Oz on ARM/Linux-based Raspberry Pi2 board (Ubuntu/ARM 14.04 32bit).

* Linux/ARM: Release Build + O3(default): stripped , commit: 561b64d2c210b4d999de7f1ac55756704eaba784 (Jul-26-2016)
------------------------------------------------------------------------------------------------------------------
-rwxr-xr-x 1 leemgs leemgs     18,472 Jul 27 16:14 corerun
-rwxr-xr-x 1 leemgs leemgs  1,512,828 Jul 27 18:33 libclrjit.so
-rwxr-xr-x 1 leemgs leemgs  4,525,328 Jul 27 18:33 libcoreclr.so
-rwxr--r-- 1 leemgs leemgs     29,696 Jul 27 00:55 ./mscorlib.dll
-rwxr--r-- 1 leemgs leemgs  2,211,840 Jul 27 00:54 ./System.Private.CoreLib.dll
Total:   8,298,164 bytes

* Linux/ARM: Release Build + Ofast: stripped , commit: 561b64d2c210b4d999de7f1ac55756704eaba784 (Jul-26-2016)
-------------------------------------------------------------------------------------------------------------
-rwxr-xr-x 1 leemgs leemgs    18,496 Jul 26 05:00 ./corerun
-rwxr-xr-x 1 leemgs leemgs 1,512,844 Jul 26 04:59 ./libclrjit.so
-rwxr-xr-x 1 leemgs leemgs 4,525,360 Jul 26 04:59 ./libcoreclr.so
-rwxr--r-- 1 leemgs leemgs    29,696 Jul 26 00:49 ./mscorlib.dll
-rwxr--r-- 1 leemgs leemgs 2,211,840 Jul 26 00:48 ./System.Private.CoreLib.dll
Total:   8,298,236 bytes

* Linux/ARM: Release Build + Oz: stripped , commit: 561b64d2c210b4d999de7f1ac55756704eaba784 (Jul-26-2016)
---------------------------------------------------------------------------------------------------------
-rwxr-xr-x 1 leemgs leemgs    14,400 Jul 29 05:02 ./corerun
-rwxr-xr-x 1 leemgs leemgs 1,181,160 Jul 29 04:40 ./libclrjit.so
-rwxr-xr-x 1 leemgs leemgs 3,407,200 Jul 29 04:40 ./libcoreclr.so
-rwxr--r-- 1 leemgs leemgs    29,696 Jul 29 00:49 ./mscorlib.dll
-rwxr--r-- 1 leemgs leemgs 2,211,840 Jul 29 00:48 ./System.Private.CoreLib.dll
Total:  6,844,296 bytes

Signed-off-by: Geunsik Lim <geunsik.lim@samsung.com>

diff --git a/Documentation/building/linux-instructions.md b/Documentation/building/linux-instructions.md
index e79b145..c948ecd 100644 (file)
--- a/Documentation/building/linux-instructions.md
+++ b/Documentation/building/linux-instructions.md
@@ -158,3 +158,63 @@ Finally, let's build coreclr with updated clang/llvm. If you meet a lldb related
 lgs@ubuntu time ROOTFS_DIR=/work/dotnet/rootfs-coreclr/arm ./build.sh arm release clean cross 
 ```
 
+Additional optimization levels for ARM/Linux: -Oz and -Ofast
+============================================================
+
+This instruction is to enable additional optimization levels such as -Oz and -Ofast on ARM/Linux. The below table shows what we have to enable for the code optimization of the CoreCLR run-time either the size or speed on embedded devices. 
+
+| **Content** | **Build Mode** | **Clang/LLVM (Linux)** |
+| --- | --- | --- |
+| -O0 | Debug | Disable optimization to generate the most debuggable code |
+| -O1 | - | Optimize for code size and execution time |
+| -O2 | Checked | Optimize more for code size and execution time |
+| -O3 | Release | Optimize more for code size and execution time to make program run faster |
+| -Oz | - | Optimize more to reduce code size further |
+| -Ofast | - | Enable all the optimizations from O3 along with other aggressive optimizations |
+
+If you want to focus on the size reduction for low-end devices, you have to modify clang-compile-override.txt to enable -Oz flag in the release build as following: 
+
+```
+--- a/src/pal/tools/clang-compiler-override.txt
++++ b/src/pal/tools/clang-compiler-override.txt
+@@ -3,13 +3,13 @@ SET (CMAKE_C_FLAGS_DEBUG_INIT          "-g -O0")
+ SET (CLR_C_FLAGS_CHECKED_INIT          "-g -O2")
+ # Refer to the below instruction to support __thread with -O2/-O3 on Linux/ARM
+ # https://github.com/dotnet/coreclr/blob/master/Documentation/building/linux-instructions.md
+-SET (CMAKE_C_FLAGS_RELEASE_INIT        "-g -O3")
++SET (CMAKE_C_FLAGS_RELEASE_INIT        "-g -Oz")
+ SET (CMAKE_C_FLAGS_RELWITHDEBINFO_INIT "-g -O2")
+
+ SET (CMAKE_CXX_FLAGS_INIT                "-Wall -Wno-null-conversion -std=c++11")
+ SET (CMAKE_CXX_FLAGS_DEBUG_INIT          "-g -O0")
+ SET (CLR_CXX_FLAGS_CHECKED_INIT          "-g -O2")
+-SET (CMAKE_CXX_FLAGS_RELEASE_INIT        "-g -O3")
++SET (CMAKE_CXX_FLAGS_RELEASE_INIT        "-g -Oz")
+ SET (CMAKE_CXX_FLAGS_RELWITHDEBINFO_INIT "-g -O2")
+
+ SET (CLR_DEFINES_DEBUG_INIT              DEBUG _DEBUG _DBG URTBLDENV_FRIENDLY=Checked BUILDENV_
+```
+
+
+If you want to focus on the speed optimization for high-end devices, you have to modify clang-compile-override.txt to enable -Ofast flag in the release build as following: 
+```
+--- a/src/pal/tools/clang-compiler-override.txt
++++ b/src/pal/tools/clang-compiler-override.txt
+@@ -3,13 +3,13 @@ SET (CMAKE_C_FLAGS_DEBUG_INIT          "-g -O0")
+ SET (CLR_C_FLAGS_CHECKED_INIT          "-g -O2")
+ # Refer to the below instruction to support __thread with -O2/-O3 on Linux/ARM
+ # https://github.com/dotnet/coreclr/blob/master/Documentation/building/linux-instructions.md
+-SET (CMAKE_C_FLAGS_RELEASE_INIT        "-g -O3")
++SET (CMAKE_C_FLAGS_RELEASE_INIT        "-g -Ofast")
+ SET (CMAKE_C_FLAGS_RELWITHDEBINFO_INIT "-g -O2")
+
+ SET (CMAKE_CXX_FLAGS_INIT                "-Wall -Wno-null-conversion -std=c++11")
+ SET (CMAKE_CXX_FLAGS_DEBUG_INIT          "-g -O0")
+ SET (CLR_CXX_FLAGS_CHECKED_INIT          "-g -O2")
+-SET (CMAKE_CXX_FLAGS_RELEASE_INIT        "-g -O3")
++SET (CMAKE_CXX_FLAGS_RELEASE_INIT        "-g -Ofast")
+ SET (CMAKE_CXX_FLAGS_RELWITHDEBINFO_INIT "-g -O2")
+
+ SET (CLR_DEFINES_DEBUG_INIT              DEBUG _DEBUG _DBG URTBLDENV_FRIENDLY=Checked BUILDENV_
+```
+