Tutorial on creating a bare metal application #1305

LDong-Arm · 2020-04-28T17:08:08Z

This PR adds a new page for creating bare metal applications.

docs/program-setup/bare_metal/baremetal_usage.md

LDong-Arm · 2020-04-29T09:43:29Z

@iriark01 Many thanks for the detailed review, I will take the suggestions on wordings. As for what to include in the guide, the Core team is in progress of discussion.

docs/program-setup/bare_metal/baremetal_usage.md

hugueskamba

Regarding docs/program-setup/bare_metal/baremetal_usage.md

The recommended workflow has always been to use a mbed-os.lib file to get Mbed OS, not to use git clone.
Perhaps mention the relationship between mbed_app.json and platform/bare_metal/mbed_lib.json when the bare metal profile is used. This is so users can have a look at (if they so wish) what is included.
Have the Mbed 2 to Mbed OS 6 porting guide link to this page section on running the Greentea test for baremetal rather than the porting guide repeating these instructions.
List the tests that will not fit in ultra constrained devices. This could go at the end when we talk about using the release profile.

LDong-Arm · 2020-04-30T14:44:14Z

@hugueskamba Thanks for the review, I'll fix everything together once we've clarified the part regarding greentea tests

docs/program-setup/bare_metal/baremetal_example.md

docs/program-setup/bare_metal/baremetal_usage.md

evedon · 2020-05-01T10:37:42Z

List the tests that will not fit in ultra constrained devices. This could go at the end when we talk about using the release profile.

Rather than list (which required maintenance or goes out-of-date), explain that a limited set of tests won't fit and show the compilation error. All other tests that were compiled shoud either pass or be slipped (typically because some HW is not present on the target)

iriark01 · 2020-05-11T06:48:16Z

Is this ready for review?

LDong-Arm · 2020-05-11T09:41:10Z

Is this ready for review?

We're still working on it, will let you know, thanks!

…bled

LDong-Arm · 2020-05-11T13:20:00Z

I’ve made some major changes:

Use the EventQueue example as a step-by-step example
Remove the existing baremetal_example.md - it requires nothing other than ["bare-metal"], bringing even less value than the EventQueue example in the guide in my opinion.
Leave the Greentea section in the porting guide rather than the application guide, because we cannot use the app's mbed_app.json and mbed-os/TESTS/configs/baremetal.json at the same time for now.
Explain that Greentea tests that fail due to memory limit should be ignored for now, as agreed with @evedon

LDong-Arm · 2020-05-11T13:24:54Z

Perhaps mention the relationship between mbed_app.json and platform/bare_metal/mbed_lib.json when the bare metal profile is used. This is so users can have a look at (if they so wish) what is included.

@hugueskamba Well, platform/bare_metal/mbed_lib.json is

{
  "name": "bare-metal",
  "requires": ["platform", "drivers", "rtos-api"]
}

which doesn't provide much detail in my opinion. Now we have APIs with bare metal compatibilities listed here which I've linked in the guide.

docs/bare_metal/baremetal_example.md

docs/bare_metal/using_bare_metal.md

LDong-Arm · 2020-05-12T10:58:28Z

@iriark01 @evedon @hugueskamba I've addressed your comments, please review again.

docs/bare_metal/mbed2_porting.md

iriark01 · 2020-05-12T15:44:31Z

docs/bare_metal/mbed2_porting.md

+    region `FLASH' overflowed by 792 bytes
+    ```
+
+    Please ignore tests with similar errors for now.


What does "for now" mean? Until later in the document? Later in the year?

I'll remove "for now" to avoid confusion.
(If we have worked around those errors sometime in the future, we will then remove this line in my opinion.)

docs/bare_metal/using_bare_metal.md

iriark01 · 2020-05-12T16:00:49Z

docs/bare_metal/using_bare_metal.md

+    called every 1 seconds
+    ```
+
+    To exit the serial terminal, press Ctrl + C.


What if I don't get that output? What does it mean and what should I do?

There can be different causes of not getting the expected output - issues with serial communication, target drivers, the application itself, etc. In my opinion it may not be feasible to have a troubleshooting guide wherever some output is quoted.

In https://os.mbed.com/docs/mbed-os/v5.15/tutorials/the-eventqueue-api.html for example, it just says "This is the output of the above program on an FRDM-K64F board." So I'll replace "You should get the following output" which seems to hint users they may or may not get it.

Co-authored-by: Irit Arkin <[email protected]>

LDong-Arm

@iriark01 Thanks a lot for the detailed review and suggestions, I'll make an update soon.

LDong-Arm · 2020-05-13T10:10:26Z

docs/bare_metal/mbed2_porting.md

+    region `FLASH' overflowed by 792 bytes
+    ```
+
+    Please ignore tests with similar errors for now.


I'll remove "for now" to avoid confusion.
(If we have worked around those errors sometime in the future, we will then remove this line in my opinion.)

docs/bare_metal/using_bare_metal.md

LDong-Arm · 2020-05-13T10:32:37Z

docs/bare_metal/using_bare_metal.md

+    called every 1 seconds
+    ```
+
+    To exit the serial terminal, press Ctrl + C.


There can be different causes of not getting the expected output - issues with serial communication, target drivers, the application itself, etc. In my opinion it may not be feasible to have a troubleshooting guide wherever some output is quoted.

In https://os.mbed.com/docs/mbed-os/v5.15/tutorials/the-eventqueue-api.html for example, it just says "This is the output of the above program on an FRDM-K64F board." So I'll replace "You should get the following output" which seems to hint users they may or may not get it.

LDong-Arm · 2020-05-13T10:41:59Z

@iriark01 Could you please review again

evedon

Good tutorial. I am fine with the content.

LDong-Arm · 2020-05-13T15:19:41Z

@iriark01 We need a one-liner update to the list of APIs that support bare metal, may I do it in this PR?

iriark01 · 2020-05-14T07:03:09Z

Since this is a fork, I can't preview it on the docs site. I'm therefore going to merge for final checks. Please ping me if you want to change anything.

LDong-Arm requested review from iriark01 and evedon April 28, 2020 17:08

LDong-Arm force-pushed the bare_metal_usage branch from 6797dd7 to b6f9052 Compare April 28, 2020 17:13

iriark01 self-assigned this Apr 29, 2020

iriark01 suggested changes Apr 29, 2020

View reviewed changes

iriark01 mentioned this pull request Apr 29, 2020

Update for bare metal area #1303

Merged

LDong-Arm added the Jira status: IN PROGRESS label Apr 29, 2020

iriark01 reviewed Apr 29, 2020

View reviewed changes

docs/program-setup/bare_metal/baremetal_usage.md Outdated Show resolved Hide resolved

hugueskamba reviewed Apr 29, 2020

View reviewed changes

evedon reviewed Apr 30, 2020

View reviewed changes

LDong-Arm changed the title ~~Bare metal tutorial (application, Greantea)~~ WIP: Bare metal tutorial (application, Greantea) May 7, 2020

LDong-Arm force-pushed the bare_metal_usage branch 2 times, most recently from a8d1668 to 3ae0b66 Compare May 11, 2020 11:34

LDong-Arm added 5 commits May 11, 2020 13:58

Add guide for using bare metal profile

6b8490e

Bare metal porting: stress that compatible Greentea tests are all ena…

6528b3c

…bled

mbed2_porting: explain Greentea errors due to small memory size

6c3372d

mbed2_porting: JSON syntax highlighting

cec980c

Remove baremetal_example.md whose purpose duplicates using_bare_metal.md

910e020

LDong-Arm force-pushed the bare_metal_usage branch from 3ae0b66 to 910e020 Compare May 11, 2020 13:07

evedon reviewed May 11, 2020

View reviewed changes

LDong-Arm added 2 commits May 12, 2020 11:52

Bare metal guide improved

53ac4ba

Bare metal guide: events library path relative to application root

9776dfd

LDong-Arm requested a review from iriark01 May 12, 2020 10:57

LDong-Arm requested review from evedon and hugueskamba May 12, 2020 10:57

LDong-Arm changed the title ~~WIP: Bare metal tutorial (application, Greantea)~~ Tutorial on creating a bare metal application May 12, 2020

iriark01 suggested changes May 12, 2020

View reviewed changes

Apply suggestions from @iriark01

f28a40d

Co-authored-by: Irit Arkin <[email protected]>

LDong-Arm commented May 13, 2020

View reviewed changes

Incorporate the latest review comments

841ebce

LDong-Arm requested a review from iriark01 May 13, 2020 10:40

LDong-Arm removed the Jira status: IN PROGRESS label May 13, 2020

evedon approved these changes May 13, 2020

View reviewed changes

Fomatting

f207742

iriark01 merged commit 04bc942 into ARMmbed:development May 14, 2020

Tutorial on creating a bare metal application #1305

Tutorial on creating a bare metal application #1305

Uh oh!

Conversation

LDong-Arm commented Apr 28, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

LDong-Arm commented Apr 29, 2020

Uh oh!

Uh oh!

hugueskamba left a comment • 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!

LDong-Arm commented Apr 30, 2020

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

evedon commented May 1, 2020

Uh oh!

iriark01 commented May 11, 2020

Uh oh!

LDong-Arm commented May 11, 2020

Uh oh!

LDong-Arm commented May 11, 2020

Uh oh!

LDong-Arm commented May 11, 2020

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

LDong-Arm commented May 12, 2020

Uh oh!

Uh oh!

Uh oh!

iriark01 May 12, 2020

Choose a reason for hiding this comment

Uh oh!

LDong-Arm May 13, 2020

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

iriark01 May 12, 2020

Choose a reason for hiding this comment

Uh oh!

LDong-Arm May 13, 2020

Choose a reason for hiding this comment

Uh oh!

LDong-Arm left a comment

Choose a reason for hiding this comment

Uh oh!

LDong-Arm May 13, 2020

Choose a reason for hiding this comment

Uh oh!

Uh oh!

LDong-Arm May 13, 2020

Choose a reason for hiding this comment

Uh oh!

LDong-Arm commented May 13, 2020

LDong-Arm commented Apr 28, 2020 •

edited

Loading

hugueskamba left a comment •

edited

Loading