Text edits to address review comments

Author: evedon

docs/program-setup/bare_metal/mbed2_porting.md

@@ -1,38 +1,38 @@
 # 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.
+The Mbed OS bare metal profile removes the RTOS and provides fewer features compared to Mbed OS 6. This profile offers the same functionality as Mbed 2 and allows targets to access features that we've added to Mbed OS 5 and 6. This document describes how to configure an Mbed 2 target to run in Mbed OS 6 bare metal 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.
+You will use the blinky bare metal Mbed OS example and make it run on your target. The configuration will be validated upon successful run 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.
+1. Edit `targets.json`. In this step, you will configure your target to support Mbed OS 6 and add bare metal configuration parameters.
+1. Compile and run 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
+Run the following commands:
+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.
+Find your target in `mbed-os/targets/targets.json` and update its configuration as described below.
 
-Configure your target to run in Mbed OS 6:
+Configure your target to support 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.
+- Add the `supported_application_profiles` property to indicate that the application profile supported by this target is bare metal. This property is currently ignored by the build tools as it is not yet supported.
 ```
-"supported_application_modes" : ["BARE-METAL"]
+"supported_application_profiles" : ["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:
+- 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 the C standard libraries, microlib and newlib-nano respectively. We recommend using them with the bare metal profile to achieve lower memory footprints. 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": {
@@ -49,9 +49,11 @@ Configure your target to run in Mbed OS 6:
 
 <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.
+- If `default_toolchain` is set to `uARM`, then replace it with `ARM` and remove `uARM` from `supported_toolchains`. Support for the uARM toolchain, which is the ARM toolchain with microlib, has been removed. Setting `c_lib` to `small` ensures that microlib is used when the ARM toolchain is selected.
 
-<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>
+<span class="notes">**Note:** As mentioned above, to successfully build with microlib, the target must define a two-region memory model. You might need to replace the content of the TOOLCHAIN_ARM_STD linker file with that of TOOLCHAIN_ARM_MICRO which already includes a two-region memory model linker file.
+
+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:
 ```
@@ -60,28 +62,30 @@ Configure your target to run in Mbed OS 6:
 }
 ```
 
-- 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.
+- 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. 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 (768 bytes) if your target has 4KB of RAM.
 ```
 "overrides": {
     "boot-stack-size": "0x400"
 }
 ```
 
-### Compile mbed-os-example-blinky-baremetal
+### Compile and run mbed-os-example-blinky-baremetal
+
+Build the application and program your target: `mbed compile -m <YOUR_TARGET> -t <TOOLCHAIN> --flash --sterm`.
 
-Compile the example for all three toolchains: `mbed compile -m <YOUR_TARGET> -t <TOOLCHAIN>`.
+The application running on the target should print a text on the console. Repeat for all supported toolchains.
 
 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.
+To validate the bare metal target configuration, you will execute the Mbed OS greentea test suite with the bare metal configuration. A subset of the tests are automatically skipped by the framework 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.
 
 - First, change directory.
 ```
 cd mbed-os
 ```
-- Then execute the greentea test suite in bare metal mode for both GCC_ARM and ARM toolchains.
+- Then execute the greentea test suite with the bare metal configuration for the supported toolchains.
 ```
 mbed test -m <YOUR_TARGET> -t <TOOLCHAIN> --app-config TESTS/configs/baremetal.json
 ```