Add application variants and Mbed OS bare metal tutorial

The example project has been re-written to include variants of an application
to blink an LED. The variants include a simple variant that uses a delay within
a loop and a more complex that creates threads and shows inter-thread
communication.
As the simpler variant is single-threaded, it showcases that some of Mbed OS
APIs can be used both with and without rtos (using Mbed OS bare metal profile).
Instructions are also provided to build the simple blinky application with
Mbed OS bare metal profile.

Runtime statistics has been removed and is only mentioned in the README. The
reader is invited to find out more. Runtime statistics is a topic on its own
and should not be implemented here.

The example project also exposes the user to Mbed OS parameter configuration
option.

Author: hugueskamba

README.md

@@ -1,7 +1,7 @@
 # Blinky Mbed OS Example
 
 ## Introduction
-The example shows Mbed OS features suchs as threads, thread delay, and inter-thread communication to blink an LED on supported [Mbed boards](https://os.mbed.com/platforms/). It also comes with configuration files to enable RTOS statistic and to build with [Mbed OS bare metal](https://os.mbed.com/docs/mbed-os/v5.14/reference/mbed-os-bare-metal.html) profile.
+The example project contains variants of an application to blink an LED on supported [Mbed boards](https://os.mbed.com/platforms/).
 
 The project can be built with all supported [Mbed OS build tools](https://os.mbed.com/docs/mbed-os/v5.14/tools/index.html). However, this example project specifically refers to the command line interface tool [Arm Mbed CLI](https://github.com/ARMmbed/mbed-cli#installing-mbed-cli).
 
@@ -13,11 +13,20 @@ $ mbed compile -S
 
 Clone this repository on your system and change the current directory to where the project was cloned.
 
-Select the section for the version of the application you wish to build:
-* [Building and Running the RTOS application](#blinky_rtos)
-* [Building and Running the bare metal application](#blinky_bare_metal)
+Modifying default Mbed OS configuration parameters can be done at application level using an application configuration file. By default ARM Mbed CLI looks for [`mbed_app.json`](https://os.mbed.com/docs/mbed-os/v5.14/reference/configuration.html), however the configuration file can be named anything. It can be passed to ARM Mbed CLI using the optional argument `--app-config` of the `compile` sub-command. This project comes with configuration files for the different variants and configurations of the blinky application.
 
-## <a name="blinky_rtos"></a> Building and Running the RTOS application
+Select the section for the variant of the application you wish to build:
+* [Blinky Wait application](#blinky_wait)
+    * [Bare metal](#blinky_wait_bare_metal)
+* [Blinky multi-threaded application](#blinky_multi_threaded)
+
+## <a name="blinky_wait"></a> Blinky Wait application
+
+### Application functionality
+
+The `main()` function calls `blinky_wait()`, as part of the single thread, which toggles the state of a digital output connected to an LED on the target.
+
+### <a name="build_blinky_wait_rtos"></a> Building and Running
 
 1. Connect a USB cable between the USB port on the target and the host computer.
 2. Run the following command to build the example project and program the microcontroller flash memory:
@@ -26,131 +35,40 @@ Select the section for the version of the application you wish to build:
     ```
 The binary is located at `./BUILD/<TARGET>/<TOOLCHAIN>/mbed-os-example-blinky.bin` and can alternatively be manually copied to the target which gets mounted on the host computer via USB.
 
-### Application functionality
-
-The `main()` function calls `blinky_rtos()`, as part of the main thread, which starts two threads: `thread_producer()` and `thread_consumer`. `thread_producer()` periodically send messages to `thread_consumer()` via an inter-thread queue. `thread_consumer()` verifies the message correctness and toggle the state of a digital output connected to an LED on the target. 
-
-### Optional RTOS runtime statistics
+### <a name="blinky_wait_bare_metal"></a> Bare metal
+The variant of the application [above](#build_blinky_wait_rtos) is built with the full Mbed OS library including its RTOS components. However, for single-threaded applications running on targets with ultraconstrains, it is possible to obtain an application with an even smaller memory footprint using [Mbed OS bare metal](https://os.mbed.com/docs/mbed-os/v5.14/reference/mbed-os-bare-metal.html) profile.
+An application configuration file, [`config_blinky_wait_bare_metal.json`](./blinky_wait/config_blinky_wait_bare_metal.json) is provided to build a binary with Mbed OS bare metal profile.
 
-`blinky_rtos()` can optionally take a snapshot of the device's runtime statistics and display it over serial to your PC. The example project has to be re-built with modified Mbed OS configuration parameters. Modifying default Mbed OS configuration parameters can be done at application level using an application configuration file. By default ARM Mbed CLI looks for `mbed_app.json`, however the configuration file can be named anything. It can be passed to ARM Mbed CLI using the optional argument `--app-config` of the `compile` sub-command. The application configuration file `config_rtos_stats.json` has been provided to enable runtime statistics to be printed.
+1. Connect a USB cable between the USB port on the target and the host computer.
+2. Run the following command to build the example project with runtime statistics output:
+    ```bash
+    $ mbed compile -m <TARGET> -t <TOOLCHAIN> --app-config=./blinky_wait/config_blinky_bare_metal.json --flash
+    ```
+The binary is located at `./BUILD/<TARGET>/<TOOLCHAIN>/mbed-os-example-blinky.bin` and can alternatively be manually copied to the target which gets mounted on the host computer via USB.
 
-Run the following command to build the example project with runtime statistics output:
-```bash
-$ mbed compile -m <TARGET> -t <TOOLCHAIN> --app-config=config_rtos_stats.json --flash
-```
+`"target.default_lib" : "small"` tells the build tool to use a small implementation of the C standard library for the toolchain selected if available. That would be Newlib-nano and MicroLib for GCC_ARM and ARM toolchains respectively.
 
-### View the serial output
 
-To view the serial output you can use any terminal client of your choosing such as [PuTTY](http://www.putty.org/) or [CoolTerm](http://freeware.the-meiers.org/). Unless otherwise specified, printf defaults to a baud rate of 9600 on Mbed OS.
+## <a name="blinky_multi_threaded"></a> Blinky multi-threaded application
 
-You can find more information on the Mbed OS configuration tools and serial communication in Mbed OS in the related [related links section](#related-links).
+This variant shows Mbed OS features suchs as threads, thread delay, and inter-thread communication to blink an LED.
 
-The output should contain the following block transmitted at the blinking LED frequency (actual values may vary depending on your target, build profile, and toolchain):
+### Application functionality
 
-```bash
-=============================== SYSTEM INFO  ================================
-Mbed OS Version: 999999
-CPU ID: 0x410fc241
-Compiler ID: 2
-Compiler Version: 60300
-RAM0: Start 0x20000000 Size: 0x30000
-RAM1: Start 0x1fff0000 Size: 0x10000
-ROM0: Start 0x0 Size: 0x100000
-================= CPU STATS =================
-Idle: 98% Usage: 2%
-================ HEAP STATS =================
-Current heap: 1096
-Max heap size: 1096
-================ THREAD STATS ===============
-ID: 0x20001eac
-Name: main_thread
-State: 2
-Priority: 24
-Stack Size: 4096
-Stack Space: 3296
-
-ID: 0x20000f5c
-Name: idle_thread
-State: 1
-Priority: 1
-Stack Size: 512
-Stack Space: 352
-
-ID: 0x20000f18
-Name: timer_thread
-State: 3
-Priority: 40
-Stack Size: 768
-Stack Space: 664
-```
+The `main()` function calls `blinky_multithreaded()`, as part of the main thread, which starts two threads: `thread_producer()` and `thread_consumer`. `thread_producer()` periodically send messages to `thread_consumer()` via an inter-thread queue. `thread_consumer()` verifies the message correctness and toggles the state of a digital output connected to an LED on the target. 
 
-The snapshot includes:
-* System Information:
-    * Mbed OS Version: Will currently default to 999999
-    * Compiler ID
-        * ARM = 1
-        * GCC_ARM = 2
-        * IAR = 3
-    * [CPUID Register Information](#cpuid-register-information)
-    * [Compiler Version](#compiler-version)
-* CPU Statistics
-    * Percentage of runtime that the device has spent awake versus in sleep
-* Heap Statistics
-    * Current heap size
-    * Max heap size which refers to the largest the heap has grown to
-* Thread Statistics
-    * Provides information on all running threads in the OS including
-        * Thread ID
-        * Thread Name
-        * Thread State
-        * Thread Priority
-        * Thread Stack Size
-        * Thread Stack Space
-
-#### Compiler Version
-
-| Compiler | Version Layout |
-| -------- | -------------- |
-| ARM      | PVVbbbb (P = Major; VV = Minor; bbbb = build number) |
-| GCC      | VVRRPP  (VV = Version; RR = Revision; PP = Patch)    |
-| IAR      | VRRRPPP (V = Version; RRR = Revision; PPP = Patch)   |
-
-#### CPUID Register Information
-
-| Bit Field | Field Description | Values |
-| --------- | ----------------- | ------ |
-|[31:24]    | Implementer       | 0x41 = ARM |
-|[23:20]    | Variant           | Major revision 0x0  =  Revision 0 |
-|[19:16]    | Architecture      | 0xC  = Baseline Architecture |
-|           |                   | 0xF  = Constant (Mainline Architecture) |
-|[15:4]     | Part Number       | 0xC20 =  Cortex-M0 |
-|           |                   | 0xC60 = Cortex-M0+ |
-|           |                   | 0xC23 = Cortex-M3  |
-|           |                   | 0xC24 = Cortex-M4  |
-|           |                   | 0xC27 = Cortex-M7  |
-|           |                   | 0xD20 = Cortex-M23 |
-|           |                   | 0xD21 = Cortex-M33 |
-|[3:0]      | Revision          | Minor revision: 0x1 = Patch 1 |
-
-You can view individual examples and additional API information of the statistics collection tools at the bottom of the page in the [related links section](#related-links).
-
-
-## <a name="blinky_bare_metal"></a> Building and Running the bare metal application
-
-An application configuration file, `config_bare_metal.json` is provided to build a version that uses [Mbed OS bare metal](https://os.mbed.com/docs/mbed-os/v5.14/reference/mbed-os-bare-metal.html) profile to create a single threaded application.
+### Building and Running
 
 1. Connect a USB cable between the USB port on the target and the host computer.
-2. Run the following command to build the example project with runtime statistics output:
+2. Run the following command to build the example project and program the microcontroller flash memory:
     ```bash
-    $ mbed compile -m <TARGET> -t <TOOLCHAIN> --app-config=config_bare_metal.json --flash
+    $ mbed compile -m <TARGET> -t <TOOLCHAIN> --flash --app-config=./blinky_multithreaded/config_blinky_multithreaded.json
     ```
 The binary is located at `./BUILD/<TARGET>/<TOOLCHAIN>/mbed-os-example-blinky.bin` and can alternatively be manually copied to the target which gets mounted on the host computer via USB.
 
-`"target.default_lib" : "small"` tells the build tool to use a small version of the C standard library for the toolchain selected if available. That would be Newlib-nano and MicroLib for GCC_ARM and ARM toolchains respectively.
-
-### Application functionality
+### Optional RTOS runtime statistics
 
-The `main()` function calls `blinky_bare_metal()`, as part of the single thread, which toggles the state of a digital output connected to an LED on the target.
+It is possible to take a snapshot of the device's runtime statistics and display it over serial to your PC. See how [here](https://os.mbed.com/docs/latest/apis/mbed-statistics.html).
 
 
 ## Troubleshooting

blinky_rtos.cpp renamed to blinky_multithreaded/blinky_multithreaded.cpp

@@ -2,36 +2,28 @@
  * Copyright (c) 2019 ARM Limited
  * SPDX-License-Identifier: Apache-2.0
  */
-#ifndef MBED_BARE_METAL
+#ifdef BLINKY_MULTITHREADED
+
 #include "mbed.h"
 #include "platform/mbed_thread.h"
 #include "rtos/Queue.h"
 #include "rtos/Thread.h"
 #include "rtos/MemoryPool.h"
 
 
-#if MBED_SYS_STAT_REPORT
-#include "stats_report.h"
-#endif // MBED_SYS_STAT_REPORT
-
-
 // Maximum number of item in the inter-thread communication queue
 #define MAX_QUEUE_SIZE                                                        1
 
 // Thread priorities
-#define THREAD_PRIORITY_PRODUCER                           osPriorityAboveNormal
-#define THREAD_PRIORITY_CONSUMER                                  osPriorityHigh
+#define THREAD_PRIORITY_PRODUCER                          osPriorityAboveNormal
+#define THREAD_PRIORITY_CONSUMER                                 osPriorityHigh
 
 // Delay between sending messages in milliseconds
-#define THREAD_SLEEP_TIME_MS_PRODUCER                                        500
-
-#if MBED_SYS_STAT_REPORT
-// Main thread delay in milliseconds
-#define THREAD_SLEEP_TIME_MS_MAIN           (THREAD_SLEEP_TIME_MS_PRODUCER * 20)
-#endif // MBED_SYS_STAT_REPORT
+#define THREAD_SLEEP_TIME_MS_PRODUCER                                       500
 
 // Message to be sent from producer thread to consumer thread
-#define THREAD_PRODUCER_MSG                                           0xDEADBEEF
+#define THREAD_PRODUCER_MSG                                          0xDEADBEEF
+
 
 // Fixed size memory pool to hold messages
 MemoryPool<unsigned long, MAX_QUEUE_SIZE> mem_pool;
@@ -55,33 +47,25 @@ Thread thread_consumer_handle(
     "CONSUMER"
 );
 
-// Initialise the digital pin LED1 as an output
-DigitalOut led(LED1);
-
 
 static void thread_consumer();
 static void thread_producer();
 
-// The function `blinky_rtos()` runs in the main thread in the OS
-void blinky_rtos()
+
+// The function `blinky_multithreaded()` runs in the main thread in the OS
+void blinky_multithreaded()
 {
     // Start execution of the functions in the threads
     thread_consumer_handle.start(callback(thread_consumer));
     thread_producer_handle.start(callback(thread_producer));
-
-#if MBED_SYS_STAT_REPORT
-    SystemReport sys_state(THREAD_SLEEP_TIME_MS_MAIN);
-
-    while (true) {
-        thread_sleep_for(THREAD_SLEEP_TIME_MS_MAIN);
-        sys_state.report_state();
-    }
-#endif // MBED_SYS_STAT_REPORT
 }
 
 
 static void thread_consumer()
 {
+    // Initialise the digital pin LED1 as an output
+    DigitalOut led(LED1);
+
     while (true) {
         osEvent evt = queue.get();
 
@@ -108,4 +92,5 @@ static void thread_producer()
         thread_sleep_for(THREAD_SLEEP_TIME_MS_PRODUCER);
     }
 }
-#endif // MBED_BARE_METAL
+
+#endif // BLINKY_MULTITHREADED

blinky_multithreaded/config_blinky_multithreaded.json

@@ -0,0 +1,7 @@
+{
+    "target_overrides": {
+        "*": {
+            "target.macros_add" : ["BLINKY_MULTITHREADED"]
+        }
+    }
+}

blinky_bare_metal.cpp renamed to blinky_wait/blinky_wait.cpp

@@ -2,22 +2,22 @@
  * Copyright (c) 2019 ARM Limited
  * SPDX-License-Identifier: Apache-2.0
  */
-#ifdef MBED_BARE_METAL
+
 #include "mbed.h"
 #include "platform/mbed_thread.h"
 
 
 // Blinking rate in milliseconds
 #define BLINKING_RATE_MS                                                    500
 
-// Initialise the digital pin LED1 as an output
-DigitalOut led(LED1);
 
-void blinky_bare_metal()
+void blinky_wait()
 {
+    // Initialise the digital pin LED1 as an output
+    DigitalOut led(LED1);
+
     while (true) {
         led = !led;
         thread_sleep_for(BLINKING_RATE_MS);
     }
 }
-#endif // MBED_BARE_METAL

blinky_wait/config_blinky_wait_bare_metal.json

@@ -0,0 +1,8 @@
+{
+    "requires": ["bare-metal"],
+    "target_overrides": {
+        "*": {
+            "target.default_lib" : "small"
+        }
+    }
+}

config_bare_metal.json

@@ -3,17 +3,17 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-#if !MBED_BARE_METAL
-extern void blinky_rtos();
+#ifdef BLINKY_MULTITHREADED
+extern void blinky_multithreaded();
 #else
-extern void blinky_bare_metal();
-#endif // !MBED_BARE_METAL
+extern void blinky_wait();
+#endif
 
 int main()
 {
-#ifndef MBED_BARE_METAL
-    blinky_rtos();
+#ifdef BLINKY_MULTITHREADED
+    blinky_multithreaded();
 #else
-    blinky_bare_metal();
-#endif // !MBED_BARE_METAL
+    blinky_wait();
+#endif
 }