LTO documentation

Author: maciejbocianski

docs/api/memory/link_time_optimization.md

@@ -0,0 +1,29 @@
+# Link Time Optimization
+
+Link Time Optimization (LTO) is a program memory usage optimization mechanism performed by compiler at link time. At compile time compiler creates special intermediate represention of all translation units and then optimize them as a single unit at link time resulting in much better optimization comparing to non-LTO builds.
+
+## Using LTO in Mbed OS
+
+In Mbed OS build system LTO is implemented as an optional profile extension placed in `tools\profiles\extensions\lto.json`. When enabled, build profile is amended with LTO flags. LTO perform heavy memory optimizations what breaks debugging, so it's not recommended to enable it in debug/develop profiles.
+
+To enable LTO retype `--profile` option with LTO file path `tools\profiles\extensions\lto.json`
+
+<span class="notes">**Note**: For profile extensions you have to put full path relative to Mbed OS root folder.</span>
+
+To enable LTO together with `release` profile:
+```
+mbed compile -t TOOLCHAIN -m TARGET --profile release --profile tools/profiles/extensions/lto.json
+```
+
+<span class="notes">**Note**: In LTO builds compiler produce bytecode/bitcode instead of regular object code. And it's hard to analyse this output by object code analysis tools.</span>
+
+## Limitations
+
+### IAR
+
+- There is no LTO available for IAR compiler.
+
+### GCC_ARM
+
+- The minimal required version of the `GCC_ARM` is now the GNU Arm Embedded Toolchain Version 9-2019-q4-major. Earlier `GCC_ARM` versions can cause various issues when the `-flto` flag is used.
+- The `noinline` attribute has to be used for every function that must be placed into a specific section (specified with a `section(".section_name")` attribute). In general, when a function is considered for inlining, the `section` attribute is always ignored. However, with the link-time optimizer enabled, the chances for inlining are much higher because the inliner works across multiple translation units. As a result, the output sections' sizes change compared to a non-lto build. `This may lead to a section ".section_name" will not fit in region "region_name"` type errors.