Added Mbed 2 to Mbed OS bare metal porting guide

Author: evedon

docs/program-setup/bare_metal/mbed2_porting.md

@@ -0,0 +1,105 @@
+# Porting an Mbed 2 target to Mbed OS 6 bare metal
+
+Mbed OS bare metal provides fewer features compared to a full RTOS platform which makes it suitable for constrained microcontrollers. This document describes how to configure an Mbed 2 target to run in bare metal mode and how to validate the port.
+
+## Configuring your target
+
+You will use the blinky bare metal Mbed OS example and make it run on your target. The configuration will be validated upon successful compilation of the example.
+
+The main steps are:
+1. Clone [mbed-os-example-blinky-baremetal](https://github.com/ARMmbed/mbed-os-example-blinky-baremetal).
+1. Edit `targets.json`. In this step, you will configure your target to run in Mbed OS 6 and then add configuration parameters for the bare metal mode. 
+1. Compile mbed-os-example-blinky-baremetal. In this step, you will validate the configuration and troubleshoot any issue.
+
+### Clone mbed-os-example-blinky-baremetal
+
+Follow these steps:
+1. git clone https://github.com/ARMmbed/mbed-os-example-blinky-baremetal
+1. cd mbed-os-example-blinky-baremetal
+
+### Edit targets.json
+
+Find your target in `targets.json` and update its configuration as described below.
+
+Configure your target to run in Mbed OS 6:
+- Remove the `release_versions` property as it is no longer necessary to specify the list of major versions of Mbed OS that the target supports.
+```
+"release_versions": ["2"]
+```
+
+- Add a new property (this property is not supported by the tools yet therefore it is ignored) `supported_application_modes` to indicate that the application mode supported by this target is bare metal. 
+```
+"supported_application_modes" : ["BARE-METAL"]
+```
+
+- Override the default `supported_c_libs` property to link with the smaller C libraries. Both the ARM and GCC_ARM toolchains support optimized versions of their C standard libraries, microlib and newlib-nano. We recommend using them with the bare metal profile. For each toolchain, if there is enough memory to link with the standard library, then add the corresponding "std" library to the list. For example:
+
+```
+"supported_c_libs": {
+    "arm":  ["std"], ["small"],
+    "gcc_arm":  ["std"], ["small"],
+    "iar": ["std"]
+}
+```
+<span class="notes">**Note:** For ARM, your target scatter file needs to have a two-region memory model. If the build system throws an error when compiling with microlib, you can find more information [here](https://os.mbed.com/docs/mbed-os/v6.0-preview/reference/using-small-c-libraries.html).</span>
+
+<span class="notes">**Note:** The IAR toolchain does not have a small C library.</span>
+
+- Set the `c_lib` property to indicate which C library should be linked by the build tools. If your target has `"default_lib": "small"` defined, then replace with `"c_lib" : "small"`. Otherwise add `"c_lib" : "small"`. We recommend that ultra constrained devices running bare metal applications link with the small C libraries by default.
+
+<span class="notes">**Note:** If a toolchain does not support a small C library and `c_lib` is set to `small`, the build tools will revert to linking with the standard C library, provided that it is listed in `supported_c_libs` for the given toolchain.</span>
+
+- If `default_toolchain` is set to `uARM`, then replace with `ARM` and remove `uARM` from `supported_toolchains`. The uARM toolchain, which is the ARMC6 toolchain with the micro C library has been deprecated and it is no longer possible to use it. In the previous step, `c_lib` was set to `small` to ensure that the micro C library will be linked by the tools when using the ARM toolchain.
+
+<span class="notes">**Note:** As mentionned above, to successfully build with the ARM micro C library, you might need to replace the content of the TOOLCHAIN_ARM_STD scatter file with that of TOOLCHAIN_ARM_MICRO. This is because the TOOLCHAIN_ARM_MICRO linker file defines a two-region memory model which is necessary to build with microlib.</span>
+
+- If your board does not have a low power ticker, ensure that tickless is enabled using the microsecond ticker as follows:
+```
+"overrides": {
+    "tickless-from-us-ticker": true
+}
+```
+
+- It might be necessary to reduce the stack size allocated for your target if it does not have enough RAM. 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.By default all targets are configured to have a boot stack size of 0x1000 (4096 bytes) in bare metal mode, however, this must be overridden if inadequate for your target. We recommend to reduce the boot stack size to 0x400 (1096 bytes) if your target has 8KB of RAM and to 0x300 if your target has 4KB of RAM.
+```
+"overrides": {
+    "boot-stack-size": "0x400"
+}
+```
+
+### Compile mbed-os-example-blinky-baremetal
+
+Compile the example for all three toolchains: `mbed compile -m <YOUR_TARGET> -t <TOOLCHAIN>`.
+
+Troubleshoot any issue.
+
+## Validating the port
+
+To validate the bare metal target configuration, you will execute the Mbed OS greentea test suite in bare metal mode. A subset of the tests are automatically skipped by the framework because they are not supported in bare metal mode, either because the underlying functionality has not been ported to bare metal or some tests require RTOS features, for examples tests based on multi-threading.
+
+- First, change directory.
+```
+cd mbed-os
+```
+- Then execute the greentea test suite in bare metal mode for both GCC_ARM and ARM toolchains.
+```
+mbed test -m <YOUR_TARGET> -t <TOOLCHAIN> --app-config TESTS/configs/baremetal.json
+```
+It can be useful to append `--compile` and fix build issues first before running tests with `--run`.
+
+All tests should pass (or be automatically skipped).
+
+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:
+```
+{
+    "target_overrides": {
+        "YOUR_TARGET": {
+            "platform.stdio-minimal-console-only": true
+        }
+    }
+}
+```