Added documentation for using ARM Compiler 5 with 5.12 release #999

SenRamakri · 2019-03-07T23:46:12Z

This is documentation addition to capture how a developer can force ARM Compiler 5 with targets
already moved to ARM Compiler 6 with 5.12 release.

SenRamakri · 2019-03-07T23:47:39Z

@AnotherButler - Please review this new modifications to tools_intro. Im also not sure if this is in the right document, if not please let me know and I'll move it. Also before merging I would like to get broader acceptance on this content. So, Ill go ahead add more reviewers here.

SenRamakri · 2019-03-07T23:49:11Z

@ChiefBureaucraticOfficer - Please see if the new content addressed the concern with developers updating to 5.12 and not able to use ARMC5.

bridadan

In those cases, you may still be able to use ARM Compiler 5 depending on the target. If your target uses any ARM Compiler 6 specific binaries or code, then it may not be able to compile with ARM Compiler 5 or you may see undefined behaviors.

If a target has a prebuilt binary, we don't currently have a way of identifying the toolchain it was compiled with right?

Are any of the prebuilt managed bootloaders inside of mbed os still built with ARMC5 only?

SenRamakri · 2019-03-08T03:12:23Z

@bridadan - You are right, we dont have a way to tell the toolchain used to build a binary.
And regarding bootloader binaries it could have been GCC_ARM or ARMC5. But I'm assuming that should not be an issue as they are independently built and are not linked together, if that's what you are concerned about.

theotherjimmy · 2019-03-08T15:01:15Z

@SenRamakri Why are we documenting this?

SenRamakri · 2019-03-08T16:01:52Z

@SenRamakri Why are we documenting this?

Good question @theotherjimmy, there has been concerns raised around the fact that developers currently using ARMC5 cannot compile 5.12 with ARMc5 without knowing these options. So, we are trying to document this more explicitly if it helps. But please raise concerns if you think this can only cause more confusion. Maybe its easier for people to move to 5.12 when they have ARMC6 development environment instead of using these options.

bridadan

And regarding bootloader binaries it could have been GCC_ARM or ARMC5

Oops yup good point, it was late in the day and my brain wasn't firing on all cylinders 😄.

I'd really suggest we don't document this unless we are prepared to test 5.12 and later releases with ARMC5 for all targets in CI. Just because it works in 5.12.0 doesn't mean it'll work 5.12.1, 5.12.2, etc.

I really think the appropriate place for this is in the release notes and the release blog.

SenRamakri · 2019-03-08T16:18:36Z

@ChiefBureaucraticOfficer - Should we rather capture this in blog/release notes as @bridadan pointed out above?

ghost · 2019-03-08T16:20:36Z

@ChiefBureaucraticOfficer - Should we rather capture this in blog/release notes as @bridadan pointed out above?

Let me confer with the product guys. It should be clear how to use the system with C5 if needed, but the question is the correct placement of that messaging.

theotherjimmy · 2019-03-08T17:17:54Z

Maybe its easier for people to move to 5.12 when they have ARMC6 development environment instead of using these options.

This is my preference. I don't think we want to offer them a way to enable untested unverified compilers. Otherwise, why do we even have target.supported_toolchains at all?

screamerbg · 2019-03-13T15:00:38Z

As I posted here to another Github thread.

@bridadan I just checked with the Mbed product management and according to them, we are not "switching" to ARM Compiler 6 - we are making "Arm Compiler 6" the default ARM Compiler. We are also keeping support for ARM Compiler 5 as one of the supported compilers until the support for it is officially announced as deprecated by the Product Management. In fact, we have a number of Partners and Customers that will continue to use ARM Compiler 5 with Mbed OS 5.12 as a main vehicle for their Products (check with @ChiefBureaucraticOfficer), including a customer of U-blox.

This documentation is key for these customers.

screamerbg

Looks great! Thank you @SenRamakri. @MarceloSalazar, @ashok-rao, @maclobdell Can you review for your customer cases and OOB?

screamerbg · 2019-03-13T15:09:09Z

docs/tools/tools_intro.md

+}
+```
+
+<span class="note"> **Note:** The above methods to override ARM toolchain version is made available only to enable developers migrating from ARM Compiler 5 to ARM Compiler 6. Future releases of Mbed OS may remove


Can this be rephrased to reflect the Product Management direction, e.g. "We encourage you to plan to make use of ARM Compiler 6 soon. We do plan to deprecate ARM Compiler 5 support in the future and this migration would ensure that your software is compatible with it."

Agree with softening of tone, but still pressing the message.

ashok-rao · 2019-03-13T16:33:57Z

docs/tools/tools_intro.md

@@ -44,3 +44,39 @@ For more information, please see the [Online Compiler page](developing-mbed-onli

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

+#### Forcing compilation with ARM Compiler 5 for targets already supporting ARM Compiler 6
+
+It's possible that some developers may need to update to Mbed 5.12 release but still requires compiling with ARM Compiler 5 until they are in possession of ARM Compiler 6.


Could we add a list of currently known targets that cannot be used with ARMC6 yet (IIRC.. PSoC6, KW24D, any others) ?

@ashok-rao - I think we should not capture that list explicitly here as we plan to move the rest of the targets to ARMC6 soon, updating the list as each target gets moved into ARMC6 might be error-prone or we may miss it and docs also need re-publishing. Instead, the mbed_targets.md captures the fact that if the supported_toolchains contains ARMC5 the target uses ARMC5. In addition you can also list the toolchain support for targets using the command "mbed config -S" which is already documented.

ashok-rao

1 minor comment, otherwise LGTM!

MarceloSalazar · 2019-03-13T18:00:47Z

I've just found we're not mentioning Arm Compiler 5 in the list of supported compilers for 5.12.
Please tweak the docs as suggested here:

Mbed OS 5 can be built with various toolchains. The currently supported versions are:

Arm Compiler 6.11 (default)
Arm Compiler 5.06 update 6 (to be deprecated in the future)
...

ghost

My approval is not required, so long as Mohit, @screamerbg and @SenRamakri are aligned.

SenRamakri · 2019-03-13T20:31:51Z

I have made the review comment fixes. There was a question around whether this documentation belongs here as if its going to create more confusion than helping with ARMC6 migration. But based on broader feedback it appears we need this documented and I'm ok with providing this content here, particularly because other ways of documenting this like blogs, release notes can make it harder to find. But note that this will probably be removed in one of the future releases once we have all targets moved to ARMC6/when we deprecate ARMC5 support.

AnotherButler · 2019-03-13T21:23:57Z

docs/tools/tools_intro.md

@@ -44,3 +45,38 @@ For more information, please see the [Online Compiler page](developing-mbed-onli

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

+#### Forcing compilation with ARM Compiler 5 for targets already supporting ARM Compiler 6


Can we make this a note and shorten it?

Maybe something like:

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 with:

{ "target_overrides": { "*": { "target.supported_toolchains": ["ARMC5", "GCC_ARM", "IAR"] } } }

Modify the supported_toolchains entry in targets.json to replace all ARM, ARMC6 entries with ARMC5:

"MY_TARGET_NAME": { "supported_form_factors": [...], "core": "Cortex-M4", "supported_toolchains": ["ARMC5", "GCC_ARM", "IAR"], ... }

See my comment below about targets.json modifications. I think that bit may need to move to target porting.

@ChiefBureaucraticOfficer @screamerbg - Please review if the shortened note of the content provided by @AnotherButler above works.

@theotherjimmy - I don't think this belongs in porting section just because we refer targets.json. Also it makes hard to find if its in porting section as this would be the page most people would land on to find compiler info.

Should a modification above to mbed_app.json be enough? Just testing mbed-os-example-blinky with that on mbed OS master (b80c961da) and it still fails to build on ARMC5.

mbed compile -m K64F -t ARMC5 <..> make.py: error: argument -t/--tool: ARMC5 is not a supported toolchain. Supported toolchains are: ARM, ARMC6, GCC_ARM, IAR, uARM [mbed] ERROR: "/usr/bin/python" returned error.

@TeroJaasko - Yes, please follow the changes as mentioned here to enable ARMC5 and try. By the way "-t ARMC5" is an invalid option. After adding ARMC5 to supported_toolchains you should still do "-t ARM". Please let me know if you need help with making the changes.

I already copied the "target.supported_toolchains": ["ARMC5", "GCC_ARM", "IAR"] to mbed_app.json and the results are no better with "-t ARM".

mbed compile -m K64F -t ARM <..> make.py: error: Could not find executable for ARMC6.

Diff on mbed-os-example-blinky:

mbed-os-example-blinky$ git diff diff --git i/mbed_app.json w/mbed_app.json index 3b191ff..c106c06 100644 --- i/mbed_app.json +++ w/mbed_app.json @@ -1,6 +1,7 @@ { "target_overrides": { "*": { + "target.supported_toolchains": ["ARMC5", "GCC_ARM", "IAR"], "platform.stack-stats-enabled": true, "platform.heap-stats-enabled": true, "platform.cpu-stats-enabled": true,

@TeroJaasko - Although we tested this in past, I tried the same thing again with the exact version you are using(b80c961da) and it appears to be working fine on my machine, and yes, the compilation works with ARMC5. And yet, I don't see anything wrong with what you are trying to do.

I also tried the same on Ubuntu and that worked fine as well. So I wonder whats causing your failure :-(. One thing you can make sure is that you are in mbeb-os-example-blinky dir and not in mbed-os when doing mbed compile.

Have you tried removing ARMC6 from paths? I don't have ARMC6 at my paths by default, there are at least one ticket open where wrong compiler is used: ARMmbed/mbed-os#10069

Ah ok, that makes sense if you dont have ARMC6 configured. I believe the tools would check for ARMC6 as in this PR ARMmbed/mbed-os#10044 , have you tried adding ARMC6 and see if that fixes the problem?

theotherjimmy · 2019-03-13T21:48:20Z

docs/tools/tools_intro.md

@@ -21,7 +21,8 @@ We created the Mbed command-line tool (Mbed CLI), a Python-based tool, specifica

 Mbed OS 5 can be built with various toolchains. The currently supported versions are:

- [Arm compiler 6.11](https://developer.arm.com/products/software-development-tools/compilers/arm-compiler/downloads/version-6).
+- [Arm compiler 6.11 (default ARM toolchain)](https://developer.arm.com/products/software-development-tools/compilers/arm-compiler/downloads/version-6).
+- [Arm compiler 5.06 update 6 (to be deprecated in the future)](https://developer.arm.com/products/software-development-tools/compilers/arm-compiler-5/downloads).


This strikes me as odd: how is "to be deprecated in the future" different from "deprecated"? My understanding of deprecated is that it means: discourage the use of in favor of a newer or better alternative.

@theotherjimmy - My understanding is that its not deprecated yet as we still have targets still compiling with ARMC5, but will be deprecated soon. This provides the warning that developers should actively look into moving to ARMC6 toolchain. Once we have all targets moved to ARMC6 we will probably say its deprecated and remove it completely in the release afterwards.
@MarceloSalazar - Do you have more comments on this?

@SenRamakri
The important point here is that Arm Compiler 5 is still supported in 5.12.
As you've incorporated this already, I don't have more comments. Thanks!

Btw, the correct name of the toolchain is "Arm Compiler" - with "C" upper case - see links.

If we know something will be discouraged in favor of an alternative, how is that not discouraging it's use already? That's my point really: that telling people it'll be discouraged in the future is the same as discouraging it's use now. I'm pretty sure this verbiage is common, so I'm not going to block on such a bike shed.

theotherjimmy

L.et's leave GCC_ARM and IAR out of this.

docs/tools/tools_intro.md

theotherjimmy · 2019-03-13T21:52:42Z

docs/tools/tools_intro.md

+}
+```
+
+##### By local modifications to `targets.json`


We don't recommend that applications modify Mbed OS elsewhere in the documentation. Perhaps this needs to be in a porting targets section instead.

Co-Authored-By: SenRamakri <[email protected]>

theotherjimmy

My only remaining issue is that the local modifications to targets.json is really for porting targets, not for applications. I don't think that's something that needs to be addressed in this PR.

0xc0170

I would also move porting part out of this intro document and reference it here. The porting detail can be in porting docs.

The rest LGTM

Apply changes from comments.

AnotherButler · 2019-03-15T14:28:41Z

docs/tools/tools_intro.md

+}
+```
+
+- Modify the `supported_toolchains` entry in targets.json to replace all `ARM`, `ARMC6` entries with `ARMC5`: 


Shall I create a new PR moving this to porting?

Or would config be a better location? We do talk about target.json here: https://os.mbed.com/docs/mbed-os/development/reference/adding-and-configuring-targets.html

That's porting documentation. It talks about how to port targets.

Move porting content out, and combine notes.

AnotherButler · 2019-03-15T15:10:47Z

docs/tools/tools_intro.md

+      }
+  }
+}
+```


I moved the porting content out in another PR: #1013

This reverts commit 1a8c222.

bridadan

Changes still look good, the clarification around the porting section in particular looks really good 👍

Make minor copy edit.

Fix capitalization, as requested in comment.

theotherjimmy · 2019-03-15T22:01:15Z

docs/tools/tools_intro.md

+}
+```
+
+- 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`:  


It's not really a modification if you're doing new target porting...

AnotherButler · 2019-03-15T22:11:19Z

Is this ready to merge?

SenRamakri · 2019-03-15T22:22:05Z

@AnotherButler - I think so, as we have it approved by all of our active reviewers.

Added documentation for using ARM Compiler 5 with 5.12 release

3aaac11

SenRamakri requested review from a user, deepikabhavnani, kegilbert, bridadan and theotherjimmy March 7, 2019 23:48

bridadan reviewed Mar 7, 2019

View reviewed changes

SenRamakri requested a review from bulislaw March 8, 2019 16:02

bridadan suggested changes Mar 8, 2019

View reviewed changes

screamerbg self-requested a review March 13, 2019 15:00

screamerbg approved these changes Mar 13, 2019

View reviewed changes

screamerbg reviewed Mar 13, 2019

View reviewed changes

ashok-rao reviewed Mar 13, 2019

View reviewed changes

ghost approved these changes Mar 13, 2019

View reviewed changes

Review comments fixes for compiler override docs

98edb64

AnotherButler reviewed Mar 13, 2019

View reviewed changes

theotherjimmy reviewed Mar 13, 2019

View reviewed changes

theotherjimmy suggested changes Mar 13, 2019

View reviewed changes

theotherjimmy and others added 2 commits March 13, 2019 17:21

Remove the mention of GCC_ARM, IAR as its not very relevant here.

dadc7db

Co-Authored-By: SenRamakri <[email protected]>

Remove the mention of GCC_ARM, IAR as its not very relevant here.

33ea6b3

Co-Authored-By: SenRamakri <[email protected]>

theotherjimmy approved these changes Mar 13, 2019

View reviewed changes

bridadan approved these changes Mar 14, 2019

View reviewed changes

0xc0170 approved these changes Mar 15, 2019

View reviewed changes

bulislaw approved these changes Mar 15, 2019

View reviewed changes

Update tools_intro.md

58b852d

Apply changes from comments.

AnotherButler reviewed Mar 15, 2019

View reviewed changes

Move porting content out of tools_intro.md

1a8c222

Move porting content out, and combine notes.

AnotherButler reviewed Mar 15, 2019

View reviewed changes

docs/tools/tools_intro.md

}

}

}

```

Copy link

Contributor

AnotherButler Mar 15, 2019

Choose a reason for hiding this comment

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

I moved the porting content out in another PR: #1013

SenRamakri added 2 commits March 15, 2019 14:10

Revert "Move porting content out of tools_intro.md"

aad083e

This reverts commit 1a8c222.

Modifications to emphasize the options available to apps vs porting

b706d08

bridadan approved these changes Mar 15, 2019

View reviewed changes

Amanda Butler added 3 commits March 15, 2019 15:45

Edit tools_intro.md

f5ecf4f

Make minor copy edit.

Update tools_intro.md

39acf7b

Make minor copy edit.

Fix capitalization in tools_intro.md

abe394a

Fix capitalization, as requested in comment.

theotherjimmy reviewed Mar 15, 2019

View reviewed changes

theotherjimmy approved these changes Mar 15, 2019

View reviewed changes

AnotherButler approved these changes Mar 15, 2019

View reviewed changes

AnotherButler merged commit 252840b into ARMmbed:development Mar 15, 2019

		@@ -44,3 +45,38 @@ For more information, please see the [Online Compiler page](developing-mbed-onli

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

		#### Forcing compilation with ARM Compiler 5 for targets already supporting ARM Compiler 6

Added documentation for using ARM Compiler 5 with 5.12 release #999

Added documentation for using ARM Compiler 5 with 5.12 release #999

Uh oh!

Conversation

SenRamakri commented Mar 7, 2019

Uh oh!

SenRamakri commented Mar 7, 2019

Uh oh!

SenRamakri commented Mar 7, 2019

Uh oh!

bridadan left a comment

Choose a reason for hiding this comment

Uh oh!

SenRamakri commented Mar 8, 2019

Uh oh!

theotherjimmy commented Mar 8, 2019

Uh oh!

SenRamakri commented Mar 8, 2019

Uh oh!

bridadan left a comment

Choose a reason for hiding this comment

Uh oh!

SenRamakri commented Mar 8, 2019

Uh oh!

ghost commented Mar 8, 2019

Uh oh!

theotherjimmy commented Mar 8, 2019

Uh oh!

screamerbg commented Mar 13, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

screamerbg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ashok-rao left a comment

Choose a reason for hiding this comment

Uh oh!

MarceloSalazar commented Mar 13, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ghost left a comment

Choose a reason for hiding this comment

Uh oh!

SenRamakri commented Mar 13, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TeroJaasko Mar 14, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SenRamakri Mar 14, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

theotherjimmy Mar 13, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

screamerbg commented Mar 13, 2019 •

edited

Loading

MarceloSalazar commented Mar 13, 2019 •

edited

Loading

SenRamakri commented Mar 13, 2019 •

edited

Loading

TeroJaasko Mar 14, 2019 •

edited

Loading

SenRamakri Mar 14, 2019 •

edited

Loading

theotherjimmy Mar 13, 2019 •

edited

Loading

theotherjimmy left a comment •

edited

Loading