Skip to content

Documentation changes for new tools modifications for ARMC5/ARMC6 usage #1024

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Mar 22, 2019
Merged

Documentation changes for new tools modifications for ARMC5/ARMC6 usage #1024

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
ffbe7ec
Documentation changes for new tools modficiations for ARMC5/ARMC6 usage
SenRamakri Mar 21, 2019
a540c96
Update note in tools_intro.md
Mar 21, 2019
c2d89fd
Changes to CLI compile documentation
SenRamakri Mar 21, 2019
3ae82c1
Edit mbed_targets.md
Mar 21, 2019
b697950
Clarify note in mbed_targets.md
Mar 21, 2019
41c8634
Update docs/reference/configuration/mbed_targets.md
iriark01 Mar 22, 2019
176fd2c
Update docs/tools/tools_intro.md
iriark01 Mar 22, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 12 additions & 4 deletions docs/reference/configuration/mbed_targets.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My mistake, in both notes, there are two (( in the link; there should be only one

.</span>

#### default_toolchain

Expand Down
5 changes: 3 additions & 2 deletions docs/tools/CLI/cli-compile.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
33 changes: 3 additions & 30 deletions docs/tools/tools_intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My mistake, in both notes, there are two (( in the link; there should be only one

.</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>