Tutorial on creating a bare metal application

docs.json

@@ -47,9 +47,6 @@
             "sources": [{
                     "path": "docs/bare_metal/bare_metal.md"
                 },
-                {
-                    "path": "docs/bare_metal/baremetal_example.md"
-                },
                 {
                     "path": "docs/bare_metal/using_bare_metal.md"
                 },

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). All tests compatible with bare metal are enabled.
 
 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), with exceptions when the target being ported is ultra-constrained (with 32KB of flash memory or less) in which case linking may fail for only _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 for now.
 
 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": {

docs/bare_metal/using_bare_metal.md

@@ -1,3 +1,88 @@
 # Using the bare metal profile
 
-Content still in PR
+This guide shows how to create a bare metal profile application:
+1. By default, when you build an application binary, the build tool uses the full profile. To use the bare metal profile, you need to set up your application to override this default behaviour.
+1. Bare metal has a minimal set of APIs. You can add additional ones [from the list of supported API](bare_metal.md#features).
+
+## Creating a bare metal application
+
+To demonstrate how to create a bare metal application, we use an example that prints text in 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)
+
+The steps are as follows:
+
+1. Create a new Mbed application and enter its directory:
+
+    ```
+    mbed new example_app && cd example_app
+    ```
+
+    This contains an empty application with Mbed OS (`mbed-os/`) fetched.
+
+1. Create a `main.cpp` containing the `EventQueue` example code snippet above.
+
+1. Open `mbed_app.json` and replace it with the following content:
+
+    ```json
+    {
+        "requires": ["bare-metal"],
+        "target_overrides": {
+            "*": {
+                "target.c_lib": "small"
+            }
+        }
+    }
+    ```
+    <span class="tips">**Tip:** `"target.c_lib": "small"` enables an optimised version of the C library with lower memory footprint. For more details, see [Using small C libraries in Mbed OS bare metal](c_small_libs.md)</span>.
+
+    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](bare_metal.md#features).
+
+1. Add dependencies - in this example, we need to add the library that contains the `EventQueue` class:
+
+    1. Locate the API and the library where it is declared in `mbed-os/`.
+    1. In the library folder, find the library's name in `mbed_lib.json`. 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"
+                }
+            }
+        }
+        ```
+
+1. With a supported board connected to your computer, compile and run your application:
+    ```
+    mbed compile -t <TOOLCHAIN> -m <TARGET> --flash --sterm
+    ```
+
+    This opens a serial terminal once the example is compiled and flashed. The following output is expected:
+    ```
+    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 Ctrl + C.