Use threads comms to blink and add baremetal version

hugueskamba · hugueskamba · commit 62c995e5df4b · 2019-10-15T14:18:37.000+01:00
The application has been re-written to use inter-thread
communication in order to blink the LED. It now shows
how threads can be created, started and how they can
communicate with each other.

Runtime statistics are made optional via an application
configuration file. Instructions have been provided to
use the configuration to enable runtime statistics to
be printed on the serial output.

Finally, a configuration file has been provided to build
the application with Mbed OS bare metal profile
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -0,0 +1,25 @@
+{
+    "files.associations": {
+        "*.original": "c",
+        "mbed_printf_implementation.h": "c",
+        "mstd_iterator": "cpp",
+        "array": "cpp",
+        "initializer_list": "cpp",
+        "mstd_utility": "cpp",
+        "string_view": "cpp",
+        "utility": "cpp",
+        "*.tpp": "cpp",
+        "*.tcc": "cpp",
+        "cerrno": "cpp",
+        "mstd_type_traits": "cpp",
+        "mstd_functional": "cpp",
+        "mstd_memory": "cpp",
+        "chrono": "cpp",
+        "functional": "cpp",
+        "istream": "cpp",
+        "ostream": "cpp",
+        "ratio": "cpp",
+        "tuple": "cpp",
+        "type_traits": "cpp"
+    }
+}
diff --git a/README.md b/README.md
@@ -1,42 +1,90 @@
-# Getting started example for Mbed OS
+# Blinky Mbed OS Example
 
-This guide reviews the steps required to get Blinky with the addition of dynamic OS statistics working on an Mbed OS platform. (Note: To see a rendered example you can import into the Arm Online Compiler, please see our [quick start](https://os.mbed.com/docs/mbed-os/latest/quick-start/online-with-the-online-compiler.html#importing-the-code).)
+## 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.
 
-Please install [Mbed CLI](https://github.com/ARMmbed/mbed-cli#installing-mbed-cli).
+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).
 
-## Import the example application
+Depending on the target, the example project can be built with GCC_ARM, ARM or IAR toolchain. Run the command below after installing ARM Mbed CLI to determine which toolchain support your target.
 
-From the command-line, import the example:
-
-```
-mbed import mbed-os-example-blinky
-cd mbed-os-example-blinky
+```bash
+$ mbed compile -S
 ```
 
-### Now compile
+Clone this repository on your system and change the current directory to where the project was cloned.
 
-Invoke `mbed compile`, and specify the name of your platform and your favorite toolchain (`GCC_ARM`, `ARM`, `IAR`). For example, for the Arm Compiler:
+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)
 
-```
-mbed compile -m K64F -t ARM
-```
+## <a name="blinky_rtos"></a> Building and Running the RTOS application
 
-Your PC may take a few minutes to compile your code. At the end, you see the following result:
+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:
+    ```bash
+    $ mbed compile -m <TARGET> -t <TOOLCHAIN> --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.
 
-```
-[snip]
+### 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.
 
-Image: ./BUILD/K64F/GCC_ARM/mbed-os-example-blinky.bin
+### Optional RTOS runtime statistics
+
+`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.
+
+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
 ```
 
-### Program your board
+### 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.
 
-1. Connect your Mbed device to the computer over USB.
-1. Copy the binary file to the Mbed device.
-1. Press the reset button to start the program.
+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).
 
-The LED on your platform turns on and off. The main thread will additionally take a snapshot of the device's runtime statistics and display it over serial to your PC. The snapshot includes:
+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):
 
+```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 snapshot includes:
 * System Information:
     * Mbed OS Version: Will currently default to 999999
     * Compiler ID
@@ -84,66 +132,37 @@ The LED on your platform turns on and off. The main thread will additionally tak
 |           |                   | 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).
 
 
-### Output
+## <a name="blinky_bare_metal"></a> Building and Running the bare metal application
 
-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.
+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.
 
-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).
-
-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):
+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=config_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.
 
-```
-=============================== 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
+`"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.
 
-ID: 0x20000f5c
-Name: idle_thread
-State: 1
-Priority: 1
-Stack Size: 512
-Stack Space: 352
+### Application functionality
 
-ID: 0x20000f18
-Name: timer_thread
-State: 3
-Priority: 40
-Stack Size: 768
-Stack Space: 664
+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.
 
-```
 
 ## Troubleshooting
-
 If you have problems, you can review the [documentation](https://os.mbed.com/docs/latest/tutorials/debugging.html) for suggestions on what could be wrong and how to fix it.
 
 ## Related Links
 
 * [Mbed OS Stats API](https://os.mbed.com/docs/latest/apis/mbed-statistics.html)
 * [Mbed OS Configuration](https://os.mbed.com/docs/latest/reference/configuration.html)
 * [Mbed OS Serial Communication](https://os.mbed.com/docs/latest/tutorials/serial-communication.html)
+* [Mbed OS bare metal](https://os.mbed.com/docs/mbed-os/v5.14/reference/mbed-os-bare-metal.html)
+* [Mbed boards](https://os.mbed.com/platforms/)
 
 ### License and contributions
 
diff --git a/blinky_bare_metal.cpp b/blinky_bare_metal.cpp
@@ -0,0 +1,23 @@
+/* mbed Microcontroller Library
+ * 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()
+{
+    while (true) {
+        led = !led;
+        thread_sleep_for(BLINKING_RATE_MS);
+    }
+}
+#endif // MBED_BARE_METAL
diff --git a/blinky_rtos.cpp b/blinky_rtos.cpp
@@ -0,0 +1,111 @@
+/* mbed Microcontroller Library
+ * Copyright (c) 2019 ARM Limited
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#ifndef MBED_BARE_METAL
+#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
+
+// 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
+
+// Message to be sent from producer thread to consumer thread
+#define THREAD_PRODUCER_MSG                                           0xDEADBEEF
+
+// Fixed size memory pool to hold messages
+MemoryPool<unsigned long, MAX_QUEUE_SIZE> mem_pool;
+
+// Queue used for inter-thread communications
+Queue<unsigned long, MAX_QUEUE_SIZE> queue;
+
+// Producer thread handle
+Thread thread_producer_handle(
+    THREAD_PRIORITY_PRODUCER,
+    OS_STACK_SIZE,
+    nullptr,
+    "PRODUCER"
+);
+
+// Consumer thread handle
+Thread thread_consumer_handle(
+    THREAD_PRIORITY_CONSUMER,
+    OS_STACK_SIZE,
+    nullptr,
+    "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()
+{
+    // 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()
+{
+    while (true) {
+        osEvent evt = queue.get();
+
+        if (evt.status == osEventMessage) {
+            unsigned long *msg = (unsigned long *)evt.value.p;
+
+            if (*msg == THREAD_PRODUCER_MSG) {
+                led = !led;
+            }
+
+            mem_pool.free(msg);
+        }
+    }
+}
+
+static void thread_producer()
+{
+    while (true) {
+        unsigned long *msg = mem_pool.alloc();
+        *msg = THREAD_PRODUCER_MSG;
+
+        queue.put(msg);
+
+        thread_sleep_for(THREAD_SLEEP_TIME_MS_PRODUCER);
+    }
+}
+#endif // MBED_BARE_METAL
diff --git a/config_bare_metal.json b/config_bare_metal.json
@@ -0,0 +1,9 @@
+{
+    "requires": ["bare-metal"],
+    "target_overrides": {
+        "*": {
+            "target.default_lib" : "small",
+            "target.macros_add" : ["MBED_BARE_METAL"]
+        }
+    }
+}
diff --git a/config_rtos_stats.json b/config_rtos_stats.json
@@ -1,6 +1,8 @@
 {
+
     "target_overrides": {
         "*": {
+            "target.macros_add" : ["MBED_SYS_STAT_REPORT"],
             "platform.stack-stats-enabled": true,
             "platform.heap-stats-enabled": true,
             "platform.cpu-stats-enabled": true,
diff --git a/main.cpp b/main.cpp
@@ -1,18 +1,12 @@
 /* mbed Microcontroller Library
- * Copyright (c) 2018 ARM Limited
+ * Copyright (c) 2018-2019 ARM Limited
  * SPDX-License-Identifier: Apache-2.0
  */
 
 #include "mbed.h"
 #include "platform/mbed_thread.h"
 #include "stats_report.h"
 
-DigitalOut led1(LED1);
-
-#define SLEEP_TIME                  500 // (msec)
-#define PRINT_AFTER_N_LOOPS         20
-
-// main() runs in its own thread in the OS
 int main()
 {
     SystemReport sys_state( SLEEP_TIME * PRINT_AFTER_N_LOOPS /* Loop delay time in ms */);

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,8 @@`
`1`	`1`	`{`
	`2`	`+`
`2`	`3`	`"target_overrides": {`
`3`	`4`	`"*": {`
	`5`	`+ "target.macros_add" : ["MBED_SYS_STAT_REPORT"],`
`4`	`6`	`"platform.stack-stats-enabled": true,`
`5`	`7`	`"platform.heap-stats-enabled": true,`
`6`	`8`	`"platform.cpu-stats-enabled": true,`