Add content from PR #619 #625

AnotherButler · 2018-07-10T21:45:50Z

Add content to this page, so all porting target content is in one place.

jen3andruska · 2018-07-11T09:37:20Z

@AnotherButler Finished reviewing & copy-editing.

ashok-rao

Thanks @AnotherButler : I've added some comments.

ashok-rao · 2018-07-11T10:05:03Z

docs/reference/contributing/target/target.md

+   1. Implement APIs, HAL, the system clock configuration and any other additional clocks.
+   1. Add toolchain-specific linker descriptions.
+1. Add peripherals and pin names for the target.
+1. Compile with CLI on a supported compiler.


CLI -> Mbed CLI

ashok-rao · 2018-07-11T10:11:06Z

docs/reference/contributing/target/target.md

+- Add a scatter file, with the extension `.sct`, for Arm Compiler 5.
+- Add a linker script, with the extension `.ld`, for GCC Arm Embedded.
+- Add an IAR Linker file, with the extension `.icf`, for IAR EWARM.
+


@AnotherButler : Can you please add: "You will also need to add the startup codes (*.s) in the respective directories as well for ARMCC, GCC and IAR."

@ashok-rao There is no reason that startup code has to be assembly, and that startup code cannot be shared between compilers. Assembly must have a capitol .S suffix.

ashok-rao · 2018-07-11T10:13:15Z

docs/reference/contributing/target/target.md

+### Compiling with a supported compiler
+
+You can verify that the new board port compiles by using an [example application](/docs/development/tutorials/mbed-os-quick-start.html), and checking out the branch containing your port in the `mbed-os` subdirectory.
+


@AnotherButler : Can you please add: "With the Mbed CLI, the command to use in the example's root directory is: mbed compile -t -m <YOUR_NEW_TARGET's_NAME> -c . And if you face any build errors at this point, please add any missing headers, add/remove peripherals as required, ensure the linker scripts & startup code are in place. For simplicity, you can start with only the serial peripheral and add other peripherals once the Mbed OS port builds successfully."

@AnotherButler, @ashok-rao Don't add the -c it's not needed.

bulislaw

Oh, that's a mix of things that don't work together. It's good stuff, but needs a lot of logical changes to make sense. Original cloud porting docs was focusing on something else and it doesn't fit what generic target porting guide should describe. Also I think we have details of some of these things on different pages. Unfortunately i won't be able to look into it soon and the team is fully (and over) committed with deliverables for 5.10 so I can't really pull someone to look at that right now.

theotherjimmy · 2018-07-12T16:03:20Z

docs/reference/contributing/target/target.md


-First fork the `mbed-os` repository on GitHub into your own user account. We will use the placeholder `USERNAME` to refer to your username in the following documentation, `MCU_NAME` to refer to the new microcontroller you are adding and `BOARD_NAME` to refer to the new board you are adding. Import an Mbed OS example, and add your fork of `mbed-os` using:
+[Mbed Cloud Client](https://cloud.mbed.com/docs/current) provides reference implementation for three Mbed Enabled targets: the K64F, NUCLEO_F429ZI and the UBLOX_EVK_ODIN_W2. You do not need to port Mbed OS or the Cloud Client if you are using one of these three boards.


This is not related to porting for Mbed OS (it's mbed cloud client only) and should be moved elsewhere.

@theotherjimmy :This is coming from the Cloud Client porting. There will be a section in the Cloud docs as well that points to this porting guide (correct?? @jen3andruska ). This is intended for folks who plan to (ultimately) port Cloud Client, but need Mbed OS running on their custom platform in the first place. Once they have Mbed OS running on their custom platform, users will link back to Cloud docs for the "rest" of the MCC porting (@AnotherButler : can you link to the MCC porting doc from here that @jen3andruska is working on?). This doc creates a bridge between Cloud porting and OS porting - which are both required for a custom platform.

@ashok-rao I dont' think that it's worded well if that's the case.

I also think that linking from the mbed-os docs to the cloud docs implies that to get mbed-os support you also need cloud support. I think it has much more potential to do harm in this way than it has the potential to do good by helping those porting cloud.

I have to agree with @theotherjimmy. I'm not sure why we need to mention the fact that MCC implements porting for k64f or other platforms here. This is a document about porting Mbed-OS and I don't think we need to mention MCC ports available for Mbed-OS, it actually confuses me to read that in introduction. What I would suggest is create a section named "Related Links or Other reference" and may be we can capture things like "Also look into... MCC ports, HAL porting guides".

theotherjimmy · 2018-07-12T16:03:49Z

docs/reference/contributing/target/target.md

+1. Add your target port.
+   1. Create the directory structure.
+   1. Add an entry for the target in `mbed_rtx.h`.
+   1. Add startup code, CMSIS headers, NVIC headers and **all** relevant drivers from the CMSIS specifications.


I don't think a bold "all" here does anyone any good.

Agree with @theotherjimmy

theotherjimmy · 2018-07-12T16:06:03Z

docs/reference/contributing/target/target.md

+
+### Adding a new microcontroller and board
+
+First fork the `mbed-os` repository. This example uses the placeholder `USERNAME` to refer to your username in the following documentation, `MCU_NAME` to refer to the new microcontroller you are adding and `BOARD_NAME` to refer to the new board you are adding. Import an Mbed OS example, and add your fork of `mbed-os` using:


"your username" -> "your github username"

Without that we could be refering to os.mbed.com or something else.

theotherjimmy · 2018-07-12T16:11:35Z

docs/reference/contributing/target/target.md

+- Add a scatter file, with the extension `.sct`, for Arm Compiler 5.
+- Add a linker script, with the extension `.ld`, for GCC Arm Embedded.
+- Add an IAR Linker file, with the extension `.icf`, for IAR EWARM.
+


@ashok-rao There is no reason that startup code has to be assembly, and that startup code cannot be shared between compilers. Assembly must have a capitol .S suffix.

theotherjimmy · 2018-07-12T16:15:39Z

@bulislaw The only cloud related stuff is that single paragraph in the opening. Everything else is strictly Mbed OS.

AnotherButler · 2018-07-18T17:40:26Z

@SenRamakri Could you please review this and make the changes requested by @bulislaw in his absence?

SenRamakri · 2018-07-20T03:07:25Z

docs/reference/contributing/target/target.md


-There are many more APIs to implement. You enable the following APIs by adding a `device_has` attribute to the MCU_NAME target definition in `targets.json` and providing an implementation of the API declared in the API header.
+There are many more APIs to implement. You enable the following APIs by adding a `device_has` attribute to the `MCU_NAME` target definition in `targets.json`, and providing an implementation of the API declared in the API header.

 device_has       |   API header
 -----------------|------------------


It would be useful to create a link for each of the below header files to actual files in mbed-os repo. Not a big deal, but would be convenient.

We could at least make them a link to their respective porting pages.

SenRamakri · 2018-07-20T03:10:11Z

docs/reference/contributing/target/target.md

+   1. Add an entry for the target in `mbed_rtx.h`.
+   1. Add startup code, CMSIS headers, NVIC headers and **all** relevant drivers from the CMSIS specifications.
+   1. Implement APIs, HAL, the system clock configuration and any other additional clocks.
+   1. Add toolchain-specific linker descriptions.


It would be good to mention the HAL tests we have under mbed-os\TESTS\mbed_hal which can be used to verify HAL porting.

Yup, a link would be valuable too

SenRamakri · 2018-07-20T03:14:01Z

docs/reference/contributing/target/target.md

+- Target build name `MY_BOARD_1`.
+- Vendor `MY_VENDOR`, device family `MY_FAMILY` and the device on the board `MY_DEVICE`.
+- A Cortex-M4F based core.
+- Porting for Mbed OS v5.x, which requires support for Arm Compiler 5, GCC Arm Embedded and IAR EWARM.


This is changing, as we are adding ARMv8M platforms which only need to support ARMC6 for now. So, depending on Core Archicture we may support all of these compilers or ARMC6 only if its ARMv8M based core.

Agree. Let's add a line here for v8 only requirements.

Is that requirement in the right place? Not sure whether you're documenting terminology or requirements

ashok-rao · 2018-07-31T16:08:20Z

@AnotherButler : Any news on this please? Thanks.

AnotherButler · 2018-08-06T17:48:47Z

@bulislaw Once @ashok-rao addresses the comments from @SenRamakri are you OK with this merging?

0xc0170 · 2018-08-08T12:04:15Z

docs/reference/contributing/target/target.md

+└── targets
+   └── TARGET_MY_VENDOR
+      ├── TARGET_MY_FAMILY
+      │  ├── TARGET_MY_DEVICE_1


I like this tree, I was explaining the structure this week to at least 2 issues regarding not having MCU_ 💯

Can we use TARGET_MCU_DEVICE_1 rather than MY_DEVICE_1 ? Similar to what is mentioned in the directory section above : TARGET_<specific_MCU> . I would keep there MCU word

bulislaw

I left couple of comments, but it's not good. We need to have a proper task on engineering to use useful parts from both docuements rather than merge them. They actually talk about slightly different thing.
@donatieng

bulislaw · 2018-08-08T13:35:37Z

docs/reference/contributing/target/target.md


-Adding a new microcontroller to Arm Mbed OS 5 depends on CMSIS-CORE and CMSIS-Pack. Please make sure that the microcontroller already has these available.
+This document discusses requirements for porting Mbed OS to a derivative target of any one of the Mbed Enabled&trade; targets. To port the MCU to Mbed OS as well, along with a custom board based on the MCU, please follow our [more detailed porting guide](docs/development/reference/porting-targets.html). 


That doesn't make any sense. This document is about porting the MCU... We are trying to merge two pages talking about slightly different thing. Oh and the docs/development/reference/porting-targets.html doesn't exists as far as i can tell.

I think the confusing part is "To port the MCU to Mbed OS as well, along with a custom board based on the MCU, please follow our more detailed porting guide. " ...

@AnotherButler : Would it be clear if we just mention "To port an MCU itself (rather than a derived target of the MCU), please refer to the detailed porting guide here" ?
Maybe we also need to mention clearly somewhere, what "porting an MCU" vs "porting a derived target" means as well.. before the start of this document.

@theotherjimmy .. thoughts??

Where's the "more detailed porting guide"? Also, this page should address porting any new boards/MCU - not just a derivative.

bulislaw · 2018-08-08T13:36:21Z

docs/reference/contributing/target/target.md


-First fork the `mbed-os` repository on GitHub into your own user account. We will use the placeholder `USERNAME` to refer to your username in the following documentation, `MCU_NAME` to refer to the new microcontroller you are adding and `BOARD_NAME` to refer to the new board you are adding. Import an Mbed OS example, and add your fork of `mbed-os` using:
+[Mbed Cloud Client](https://cloud.mbed.com/docs/current) provides reference implementation for three Mbed Enabled targets: the K64F, NUCLEO_F429ZI and the UBLOX_EVK_ODIN_W2. You do not need to port Mbed OS or the Cloud Client if you are using one of these three boards.


Why are we mentioning MCC here, we are talking about porting the OS, after the OS is ported we can start porting the MCC.

@bulislaw : That's the ultimate goal. In order to reach the top floor (Pelion Cloud Client), we need to clear the ground floor (OS port running successfully on whatever board the customer has) .. and no probs if they use K64 / F429 / ODIN as these are already working in the examples.. however, the problem comes when they use an F429 MCU on a custom PCB (not NUCLEO) or a K64 (not FRDM) or ODIN (not EVK / MTB..) .. this guide should help them get Mbed OS running on those custom boards 1st. Then, they can move to PCC..

Not happy with the current wording which is confusing; as said above this page is about porting the OS.
However you could add a note somewhere: "Note: This page describes the porting process of Mbed OS which is a Pelion Cloud Client dependency; to port Cloud Client, go to this page..."

bulislaw · 2018-08-08T13:36:51Z

docs/reference/contributing/target/target.md

+
+### Summary of steps
+
+1. Add your target to `targets.json`.


That assumes cloud porting, not the system.

Doesn't a new target needs to be added here anyways for building from CLI ?

ashok-rao · 2018-08-29T10:33:29Z

@donatieng : I know you are quite occupied with the release, but could you please have a look at this PR? I've addressed previous comments & now that DM is becoming a part of the OS, I feel this doc needs to be absolutely put in place as well.. could you please let me know? Thanks.

donatieng · 2018-08-30T11:07:09Z

docs/reference/contributing/target/target.md


-Adding a new microcontroller to Arm Mbed OS 5 depends on CMSIS-CORE and CMSIS-Pack. Please make sure that the microcontroller already has these available.
+This document discusses requirements for porting Mbed OS to a derivative target of any one of the Mbed Enabled&trade; targets. To port the MCU to Mbed OS as well, along with a custom board based on the MCU, please follow our [more detailed porting guide](docs/development/reference/porting-targets.html). 


Where's the "more detailed porting guide"? Also, this page should address porting any new boards/MCU - not just a derivative.

donatieng · 2018-08-30T11:10:48Z

docs/reference/contributing/target/target.md


-First fork the `mbed-os` repository on GitHub into your own user account. We will use the placeholder `USERNAME` to refer to your username in the following documentation, `MCU_NAME` to refer to the new microcontroller you are adding and `BOARD_NAME` to refer to the new board you are adding. Import an Mbed OS example, and add your fork of `mbed-os` using:
+[Mbed Cloud Client](https://cloud.mbed.com/docs/current) provides reference implementation for three Mbed Enabled targets: the K64F, NUCLEO_F429ZI and the UBLOX_EVK_ODIN_W2. You do not need to port Mbed OS or the Cloud Client if you are using one of these three boards.


Not happy with the current wording which is confusing; as said above this page is about porting the OS.
However you could add a note somewhere: "Note: This page describes the porting process of Mbed OS which is a Pelion Cloud Client dependency; to port Cloud Client, go to this page..."

donatieng · 2018-08-30T11:11:34Z

docs/reference/contributing/target/target.md

+1. Add your target port.
+   1. Create the directory structure.
+   1. Add an entry for the target in `mbed_rtx.h`.
+   1. Add startup code, CMSIS headers, NVIC headers and **all** relevant drivers from the CMSIS specifications.


Agree with @theotherjimmy

donatieng · 2018-08-30T11:12:06Z

docs/reference/contributing/target/target.md

+   1. Add an entry for the target in `mbed_rtx.h`.
+   1. Add startup code, CMSIS headers, NVIC headers and **all** relevant drivers from the CMSIS specifications.
+   1. Implement APIs, HAL, the system clock configuration and any other additional clocks.
+   1. Add toolchain-specific linker descriptions.


Yup, a link would be valuable too

donatieng · 2018-08-30T11:13:46Z

docs/reference/contributing/target/target.md

+- Target build name `MY_BOARD_1`.
+- Vendor `MY_VENDOR`, device family `MY_FAMILY` and the device on the board `MY_DEVICE`.
+- A Cortex-M4F based core.
+- Porting for Mbed OS v5.x, which requires support for Arm Compiler 5, GCC Arm Embedded and IAR EWARM.


Is that requirement in the right place? Not sure whether you're documenting terminology or requirements

donatieng · 2018-08-30T11:16:30Z

docs/reference/contributing/target/target.md

-First fork the `mbed-os` repository on GitHub into your own user account. We will use the placeholder `USERNAME` to refer to your username in the following documentation, `MCU_NAME` to refer to the new microcontroller you are adding and `BOARD_NAME` to refer to the new board you are adding. Import an Mbed OS example, and add your fork of `mbed-os` using:
+[Mbed Cloud Client](https://cloud.mbed.com/docs/current) provides reference implementation for three Mbed Enabled targets: the K64F, NUCLEO_F429ZI and the UBLOX_EVK_ODIN_W2. You do not need to port Mbed OS or the Cloud Client if you are using one of these three boards.
+
+### Summary of steps


Can we have one clear section per step?

donatieng · 2018-08-30T11:17:01Z

docs/reference/contributing/target/target.md

+/mbed-os/targets/TARGET_MY_VENDOR/TARGET_MY_FAMILY/TARGET_MY_DEVICE_1/TARGET_MY_BOARD_1/
+```
+
+### Entry in `mbed_rtx.h`


That looks good but shouldn't it go in rtos.md?

donatieng · 2018-08-30T11:20:35Z

Hi @ashok-rao, I feel this still needs major rework - what is you goal for 5.10 in terms of integrating references to DM? Can we achieve that with a single note such as "this page describes porting a new target to Mbed OS, please find the Cloud Client porting guide here"?

iriark01 · 2018-10-09T15:15:01Z

Closing; we're getting new porting content that will also cover this for 5.11

Add content from PR #619

1393960

Add content to this page, so all porting target content is in one place.

AnotherButler requested review from theotherjimmy, jen3andruska, ashok-rao, iriark01, bulislaw and c1728p9 July 10, 2018 21:46

AnotherButler mentioned this pull request Jul 10, 2018

Migration: New porting guide from Cloud team #619

Closed

jen3andruska added 8 commits July 11, 2018 09:03

Update target.md

ab77cde

Update target.md

7a0bf17

Update target.md

862668c

Update target.md

2576b1a

Update target.md

b9ef3f2

Update target.md

dbee003

Update target.md

24dfa01

Update target.md

8b562e6

jen3andruska approved these changes Jul 11, 2018

View reviewed changes

ashok-rao suggested changes Jul 11, 2018

View reviewed changes

bulislaw requested changes Jul 11, 2018

View reviewed changes

theotherjimmy reviewed Jul 12, 2018

View reviewed changes

AnotherButler requested a review from SenRamakri July 18, 2018 17:39

SenRamakri reviewed Jul 20, 2018

View reviewed changes

ashok-rao mentioned this pull request Aug 8, 2018

Add support for Waveshare BLE400 ARMmbed/mbed-os#5478

Closed

0xc0170 reviewed Aug 8, 2018

View reviewed changes

bulislaw requested changes Aug 8, 2018

View reviewed changes

donatieng suggested changes Aug 30, 2018

View reviewed changes

iriark01 closed this Oct 9, 2018

iriark01 deleted the AnotherButler-patch-3 branch October 15, 2018 19:38

		### Compiling with a supported compiler

		You can verify that the new board port compiles by using an [example application](/docs/development/tutorials/mbed-os-quick-start.html), and checking out the branch containing your port in the `mbed-os` subdirectory.


		First fork the `mbed-os` repository on GitHub into your own user account. We will use the placeholder `USERNAME` to refer to your username in the following documentation, `MCU_NAME` to refer to the new microcontroller you are adding and `BOARD_NAME` to refer to the new board you are adding. Import an Mbed OS example, and add your fork of `mbed-os` using:
		[Mbed Cloud Client](https://cloud.mbed.com/docs/current) provides reference implementation for three Mbed Enabled targets: the K64F, NUCLEO_F429ZI and the UBLOX_EVK_ODIN_W2. You do not need to port Mbed OS or the Cloud Client if you are using one of these three boards.


		### Adding a new microcontroller and board

		First fork the `mbed-os` repository. This example uses the placeholder `USERNAME` to refer to your username in the following documentation, `MCU_NAME` to refer to the new microcontroller you are adding and `BOARD_NAME` to refer to the new board you are adding. Import an Mbed OS example, and add your fork of `mbed-os` using:


		Adding a new microcontroller to Arm Mbed OS 5 depends on CMSIS-CORE and CMSIS-Pack. Please make sure that the microcontroller already has these available.
		This document discusses requirements for porting Mbed OS to a derivative target of any one of the Mbed Enabled™ targets. To port the MCU to Mbed OS as well, along with a custom board based on the MCU, please follow our [more detailed porting guide](docs/development/reference/porting-targets.html).

Add content from PR #619 #625

Add content from PR #619 #625

Uh oh!

Conversation

AnotherButler commented Jul 10, 2018

Uh oh!

jen3andruska commented Jul 11, 2018

Uh oh!

ashok-rao 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!

Choose a reason for hiding this comment

Uh oh!

bulislaw 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!

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!

theotherjimmy commented Jul 12, 2018

Uh oh!

AnotherButler commented Jul 18, 2018

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 Jul 20, 2018 • 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!

ashok-rao commented Jul 31, 2018

Uh oh!

AnotherButler commented Aug 6, 2018

Uh oh!

0xc0170 Aug 8, 2018 • 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!

bulislaw 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!

Choose a reason for hiding this comment

SenRamakri Jul 20, 2018 •

edited

Loading

0xc0170 Aug 8, 2018 •

edited

Loading

iriark01 commented Oct 9, 2018 •

edited

Loading