Merge pull request #1024 from SenRamakri/sen_ToolchainDocsUpdate

Documentation changes for new tools modifications for ARMC5/ARMC6 usage

Author: iriark01

docs/reference/configuration/mbed_targets.md

@@ -194,12 +194,20 @@ Enabling `is_disk_virtual` adds delay after flashing firmware binary to make sur
 
 The `supported_toolchains` property is the list of toolchains that support a target. The allowed values for `supported_toolchains` are `ARM`, `uARM`, `ARMC5`, `ARMC6`, `GCC_ARM` and `IAR`.
 
-If you specify `ARMC5` in `supported_toolchains`, it means the corresponding target supports `Arm Compiler 5.06 update 6`.
+When using `ARM`, `ARMC5`, `ARMC6` for `supported_toolchains`, please note:
 
-If a target lists both `ARMC5` and `ARM` (or `ARMC6`) in `supported_toolchains`, the Arm Compiler 6.11 will be used when compiling with `ARM` option for `--toolchain`.
+- If the target supports only Arm Compiler 5 (version 5.06 update 6), `supported_toolchains` specifies `ARMC5`. The build system uses Arm Compiler 5 when you use `-t ARM` or `-t ARMC5` with `mbed compile` command. 
 
-<span class="notes">**Note:** Although you can specify `ARMC5` in `supported_toolchains` in `targets.json`, it's not a valid option for `--toolchain` when compiling using [Mbed CLI](../tools/developing-mbed-cli.html). Arm Compiler 6 is the default Arm toolchain for Mbed OS development. Most Mbed OS platforms are already compatible with Arm Compiler 6. Some existing targets still supporting Arm Compiler 5 will be migrated to Arm Compiler 6 in the future. Please be aware that you must use Arm Compiler 6 for future development, and we will validate all code contributions to Mbed OS Arm Compiler 6.
-</span>
+- If the target supports only Arm Compiler 6 (version 6.11), `supported_toolchains` specifies `ARMC6`. The build system uses Arm Compiler 6 when you use `-t ARM` or `-t ARMC6` with `mbed compile` command.
+
+- If the target supports compiling with both Arm Compiler 5 and Arm Compiler 6, `supported_toolchains` specifies `ARM`. Arm Compiler 6 is the default Arm Compiler for Mbed OS. If a target specifies `ARM` in `supported_toolchains`, the system defaults to using Arm Compiler 6 when you use `-t ARM` with the `mbed compile` command. If the build system fails to detect a valid configuration for Arm Compiler 6, it automatically (without any manual intervention) detects if a valid configuration for Arm Compiler 5 exists and continues using Arm Compiler 5 if it successfully detects Arm Compiler 5. You will see a warning message in your standard output from the build system indicating this behavior.
+
+- You can only specify one of `ARM`, `ARMC5` or `ARMC6` for `supported_toolchains` for a target in `targets/targets.json` or `custom_targets.json`.
+
+- It's invalid to use `-t ARMC5` with the `mbed compile` command for a target that specifies `ARMC6` for `supported_toolchains`, and it's invalid to use `-t ARMC6` if `supported_toolchains` specifies `ARMC5`.
+
+<span class="notes">**Note**: Arm Compiler 6 is the default Arm Compiler version for Mbed OS development, and is [free for use with Mbed OS]((https://os.mbed.com/docs/mbed-os/development/tools/index.html#compiler-versions). Most platforms are already compatible with it; platforms still supporting Arm Compiler 5 will be migrated to Arm Compiler 6. Please do not use Arm Compiler 5 in any new development, as its support will be deprecated in September 2019.
+.</span>
 
 #### default_toolchain
 

docs/tools/CLI/cli-compile.md

@@ -37,8 +37,9 @@ Image: BUILD/K64F/GCC_ARM/mbed-os-program.bin
 The arguments for *compile* are:
 
 - `-m <MCU>` selects a target. If `detect` or `auto` parameter is passed to `-m`, then Mbed CLI detects the connected target.
-- `-t <TOOLCHAIN>` selects a toolchain defined in `mbed_settings.py`. The value can be `ARM` (Arm Compiler), `GCC_ARM` (GNU Arm Embedded) or `IAR` (IAR Embedded Workbench for Arm).
-   <span class="notes">**Note**: `mbed compile -t ARM` selects the Arm Compiler major version based on the Arm architecture version of your target. Arm architecture versions 6 and 7 use Arm Compiler 5, and Arm architecture version 8 uses Arm Compiler 6.</span>
+- `-t <TOOLCHAIN>` selects a toolchain defined in `mbed_settings.py`. The value can be `ARM` (Arm Compiler 6 or ARM Compiler 5), `ARMC5` (ARM Compiler 5), `ARMC6` (Arm Compiler 6), `GCC_ARM` (GNU Arm Embedded) or `IAR` (IAR Embedded Workbench for Arm).
+   <span class="notes">**Note**: `mbed compile -t ARM` selects the Arm Compiler major version based on the Arm architecture version of your target and `supported_toolchains` configuration.
+   Please see `supported_toolchains` in [Adding and configuring targets](../reference/adding-and-configuring-targets.html) and `Compiler versions` in [Arm Mbed tools](../tools/tools_intro.html) for more information on toolchain configuration and usage.</span>
 - `--source <SOURCE>` selects the source directory. The default is `.` (the current directory). You can specify multiple source locations, even outside the program tree. Find more details about the `--source` switch in the [build rules documentation](../reference/mbed-os-build-rules.html).
 - `--build <BUILD>` selects the build directory. Default: `BUILD/` inside your program root.
    <span class="notes">**Note**: `mbed compile` ignores the current build directory; creating multiple build directories leads to errors.</span>

docs/tools/tools_intro.md

@@ -43,38 +43,11 @@ The Mbed Online Compiler is our in-house IDE and should be familiar to anyone wh
 | Arm v7A       | `Arm Compiler 6.11` |
 | Arm v8M       | `Arm Compiler 6.11` |
 
-For more information, please see the [Online Compiler page](developing-mbed-online-compiler.html).
+<span class="notes">**Note**: Arm Compiler 6 is the default Arm Compiler version for Mbed OS development, and is [free for use with Mbed OS]((https://os.mbed.com/docs/mbed-os/development/tools/index.html#compiler-versions). Most platforms are already compatible with it; platforms still supporting Arm Compiler 5 will be migrated to Arm Compiler 6. Please do not use Arm Compiler 5 in any new development, as its support will be deprecated in September 2019.
+.</span>
 
-<span class="note"> **Note:** Arm Compiler 6 is the default ARM toolchain for Mbed OS development. Most Mbed OS platforms are already compatible with Arm Compiler 6. Some existing targets still supporting Arm Compiler 5 will also be migrated to ARM Compiler 6 in the future. Please be aware that you must use Arm Compiler 6 for future development, and we will validate all code contributions to Mbed OS with Arm Compiler 6. </span>
+For more information, please see the [Online Compiler page](developing-mbed-online-compiler.html).
 
 ##### Third party development tools
 
 You can export your project from any of our tools to third party tools. For instructions, as well as tool-specific information, see the [Exporting to third party toolchains page](exporting.html).
-
-<div style="background-color:#F3F3F3; text-align:left; vertical-align: middle; padding:15px 30px;"> Note: We encourage you to switch to Arm Compiler 6 soon because we will deprecate Arm Compiler 5 support in the future. However, if you need to update to Mbed OS 5.12 but still require compiling with Arm Compiler 5 until you are in possession of Arm Compiler 6, we provide methods to override the Arm toolchain version. If you do this, your target may not be able to compile with Arm Compiler 5, or you may see undefined behaviors.
-
-To force Arm Compiler 5, you can use the following options:
-
-- Create or update your `mbed_app.json` as below. This is the recommended method for applications to use Arm Compiler 5.
-
-```
-{
-  "target_overrides": {
-      "*": {
-          "target.supported_toolchains": ["ARMC5", "GCC_ARM", "IAR"]
-      }
-  }
-}
-```
-
-- For porting a target that cannot use Arm Compiler 6 at this time, modify the `supported_toolchains` entry in `targets.json` to replace all `ARM` and `ARMC6` entries with `ARMC5`:  
-
-```
-"MY_TARGET_NAME": {
-        "supported_form_factors": [...],
-        "core": "Cortex-M4",
-        "supported_toolchains": ["ARMC5", "GCC_ARM", "IAR"],
-        ...
-}
-```
-</div>