Tutorial on creating a bare metal application (#1305)

LDong-Arm · iriark01 · web-flow · commit 04bc9426c92a · 2020-05-14T08:03:13.000+01:00
* Add guide for using bare metal profile * Bare metal porting: stress that compatible Greentea tests are all enabled * mbed2_porting: explain Greentea errors due to small memory size * mbed2_porting: JSON syntax highlighting * Remove baremetal_example.md whose purpose duplicates using_bare_metal.md * Bare metal guide improved * Bare metal guide: events library path relative to application root * Apply suggestions from @iriark01 Co-authored-by: Irit Arkin <irit.arkin@arm.com> * Incorporate the latest review comments * Fomatting Co-authored-by: Irit Arkin <irit.arkin@arm.com>
diff --git a/docs.json b/docs.json
@@ -70,9 +70,6 @@
             "sources": [{
                     "path": "docs/bare_metal/bare_metal.md"
                 },
-                {
-                    "path": "docs/bare_metal/baremetal_example.md"
-                },
                 {
                     "path": "docs/bare_metal/using_bare_metal.md"
                 },
diff --git a/docs/bare_metal/baremetal_example.md b/docs/bare_metal/baremetal_example.md
diff --git a/docs/bare_metal/mbed2_porting.md b/docs/bare_metal/mbed2_porting.md
@@ -34,19 +34,19 @@ Configure your target to support Mbed OS 6:
 
 1. Remove the `release_versions` property; it is no longer required:
 
-    ```
+    ```json
     "release_versions": ["2"]
     ```
 
 1. To indicate that the application profile supported by this target is bare metal, add the `supported_application_profiles` property:
 
-    ```
+    ```json
     "supported_application_profiles" : ["bare-metal"]
     ```
 
 1. Override `supported_c_libs` property to link with the smaller C libraries. The default for all targets is defined as follows:
 
-    ```
+    ```json
     "supported_c_libs": {
         "arm":  ["std"],
         "gcc_arm":  ["std", "small"],
@@ -56,7 +56,7 @@ Configure your target to support Mbed OS 6:
 
     Both the ARM and GCC_ARM toolchains support optimized versions of the C standard libraries - microlib and newlib-nano, respectively. We recommend using them with the bare metal profile for lower memory footprints. Ultraconstrained targets should override `supported_c_libs`:
 
-    ```
+    ```json
     "supported_c_libs": {
         "arm":  ["small"],
         "gcc_arm":  ["small"]
@@ -67,7 +67,7 @@ Configure your target to support Mbed OS 6:
 
     For each toolchain, if there is enough memory to link with the standard library, add the corresponding `std` library to the list. For example:
 
-    ```
+    ```json
     "supported_c_libs": {
         "arm":  ["std", "small"],
         "gcc_arm":  ["std", "small"],
@@ -92,7 +92,7 @@ Configure your target to support Mbed OS 6:
 
 1. If your board does not have a low power ticker, ensure that tickless is enabled using the microsecond ticker:
 
-    ```
+    ```json
     "overrides": {
         "tickless-from-us-ticker": true
     }
@@ -102,7 +102,7 @@ Configure your target to support Mbed OS 6:
 
     The stack size is configured by setting a value for the `boot-stack-size` attribute; this value must be a multiple of 8 for alignment purposes. We recommend that you reduce the boot stack size to 0x400 (1,024 bytes) if your target has 8KB of RAM and to 0x300 (768 bytes) if your target has 4KB of RAM.
 
-    ```
+    ```json
     "overrides": {
         "boot-stack-size": "0x400"
     }
@@ -122,7 +122,7 @@ Troubleshoot any issue.
 
 ## Validating the port
 
-To validate the bare metal target configuration, execute the Mbed OS Greentea test suite with the bare metal profile. This profile causes Greentea to skip a subset of the tests, either because the underlying functionality has not been ported to bare metal or because some tests require RTOS features (for examples, more complex tests based on multi-threading).
+To validate the bare metal target configuration, execute the Mbed OS Greentea test suite with the bare metal profile. This profile causes Greentea to skip a subset of the tests, either because the underlying functionality has not been ported to bare metal or because some tests require RTOS features (for examples, more complex tests based on multi-threading). It performs all the tests compatible with bare metal.
 
 If you haven't used Greentea before, [you can learn more in our documentation](../tools/greentea-testing-applications.html).
 
@@ -140,15 +140,27 @@ If you haven't used Greentea before, [you can learn more in our documentation](.
 
     <span class="tips">**Tip:** You can append `--compile` and fix build issues before running tests with `--run`.</span>
 
-1. All tests should pass (or be automatically skipped).
+1. All tests should pass (or be automatically skipped), unless the target being ported is ultraconstrained (with 32KB or less of flash memory) - in which case linking may fail for _a few_ tests. For example:
+
+    ARM toolchain:
+    ```
+    Error: L6407E: Sections of aggregate size 0x318 bytes could not fit into .ANY selector(s).
+    ```
+
+    GCC_ARM toolchain:
+    ```
+    region `FLASH' overflowed by 792 bytes
+    ```
+
+    Please ignore tests with similar errors.
 
 Further optimisations for targets with small flash memories:
 - Append `--profile release` to the command above. Use of the release profile helps keep some tests within the size limit.
 - Save additional memory by using a [minimal console](https://github.com/ARMmbed/mbed-os-example-blinky-baremetal#using-a-minimal-console) to remove file handling functionality from the system I/O retarget code.
 
     Modify `TESTS/configs/baremetal.json` for your target:
 
-    ```
+    ```json
     {
         "target_overrides": {
             "YOUR_TARGET": {
diff --git a/docs/bare_metal/using_bare_metal.md b/docs/bare_metal/using_bare_metal.md
@@ -1,3 +1,100 @@
 # Using the bare metal profile
 
-Content still in PR
+This guide shows how to create a bare metal profile application:
+
+1. Set the profile: By default, the build tool uses the full profile for all application builds. To use the bare metal profile, set up your application to override this default behaviour.
+1. By default, the bare metal profile uses a minimal set of APIs. You can add additional ones [from the list of supported APIs](../bare-metal/index.html#features) if your application needs them.
+
+To demonstrate how to create a bare metal application, here is an example that prints text at regular intervals using the `EventQueue` class:
+
+[![View code](https://www.mbed.com/embed/?url=https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/APIs_RTOS/EventQueue_ex_2/)](https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/APIs_RTOS/EventQueue_ex_2/main.cpp)
+
+## Creating a bare metal application
+
+To create the application:
+
+1. Create a new Mbed OS application and navigate to its directory:
+
+    ```
+    mbed new example_app && cd example_app
+    ```
+
+    The directory contains the full Mbed OS library (`mbed-os/`) and no application files.
+
+1. Create a `main.cpp` file containing the `EventQueue` code snippet above.
+
+1. Open `mbed_app.json` (in the root of the application) and replace it with the following content:
+
+    ```json
+    {
+        "requires": ["bare-metal"],
+        "target_overrides": {
+            "*": {
+                "target.c_lib": "small"
+            }
+        }
+    }
+    ```
+
+    The file specifies which profile to use (`"requires": ["bare-metal"]`) and which C library to use (`"target.c_lib": "small"`).
+    
+    In this example, we're using `"target.c_lib": "small"` (small C library). This means your application will use an optimised version of the C library with lower memory footprint. For more details, see [Using small C libraries in Mbed OS bare metal](../bare-metal/using-small-c-libraries.html).
+
+You now have application code and a bare metal profile with the default APIs. However, this example uses APIs that are not part of the default bare metal profile - you need to manually add support for those APIs to the application.
+
+## Adding APIs
+
+Bare metal has a minimal set of default APIs - those that are always available to a bare metal application. You can add other supported APIs if you need the features they enable.
+
+For a list of default and supported APIs, [please see our full API list](../apis/index.html).
+
+This example depends on the `EventQueue` class, so you need to add the library that contains that class:
+
+1. In `mbed-os/`, locate the API and the library in which it is declared.
+1. In the library folder, open `mbed_lib.json` and find the library's name. You will need it for the next step.
+
+    For example: `mbed-os/events/mbed_lib.json`:
+    ```json
+    {
+        "name": "events",
+        "config": {
+            "present": 1,
+            ...
+        }
+    }
+    ```
+    To continue, go back to the application's root directory.
+
+1. Open `mbed_app.json` again, and add the library to the `"requires"` field:
+
+    ```json
+    {
+        "requires": ["bare-metal", "events"],
+        "target_overrides": {
+            "*": {
+                "target.c_lib": "small"
+            }
+        }
+    }
+    ```
+
+## Compiling and Running the Application
+
+Connect a supported board to your computer, and compile and run your application:
+
+```
+mbed compile -t <TOOLCHAIN> -m <TARGET> --flash --sterm
+```
+
+When the example is flashed, a serial terminal opens (because of `--sterm`). The outputis:
+
+```
+called immediately
+called every 1 seconds
+called in 2 seconds
+called every 1 seconds
+called every 1 seconds
+called every 1 seconds
+```
+
+To exit the serial terminal, press <kbd>Ctrl</kbd> + <kbd>C</kbd>.
