add platform utils examples (#97)

Author: maciejbocianski

APIs_Platform/CircularBuffer_ex_1/README.md

@@ -0,0 +1,3 @@
+# CircularBuffer example
+
+This example shows how to use `CircularBuffer` API's. Contents of data stream are pushed till buffer is full, and popped back till buffer is empty.

APIs_Platform/CircularBuffer_ex_1/main.cpp

@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) 2017 - 2020 Arm Limited and affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "mbed.h"
+#include "platform/CircularBuffer.h"
+
+#define BUF_SIZE    10
+
+CircularBuffer<char, BUF_SIZE> buf;
+char data_stream[] = "DataToBeAddedToBuffer";
+
+int main()
+{
+    uint32_t bytes_written = 0;
+
+    while (!buf.full()) {
+        buf.push(data_stream[bytes_written++]);
+    }
+
+    printf("Circular buffer is full: \"%s\" or empty: \"%s\" \n",
+           (buf.full() ? "true" : "false"),
+           (buf.empty() ? "true" : "false"));
+    printf("Bytes written %ld \n", bytes_written);
+
+    // If buffer is full, contents will be over-written
+    buf.push(data_stream[bytes_written++]);
+
+    char data = 0;
+    printf("Buffer contents: ");
+    while (!buf.empty()) {
+        buf.pop(data);
+        printf("%c", data);
+    }
+    printf("\n");
+
+    printf("Circular buffer is full: \"%s\" or empty: \"%s\" \n",
+           (buf.full() ? "true" : "false"),
+           (buf.empty() ? "true" : "false"));
+
+    return 0;
+
+}

APIs_Platform/CriticalSectionLock_ex_1/README.md

@@ -0,0 +1,3 @@
+# CriticalSectionLock example
+
+This example shows how to use `CriticalSection` API to avoid race condition when multiple threads update global shared counter.

APIs_Platform/CriticalSectionLock_ex_1/main.cpp

@@ -0,0 +1,49 @@
+/*
+ * Copyright (c) 2017 - 2020 Arm Limited and affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "mbed.h"
+
+#define  USE_CRITICAL_SECTION_LOCK      1   // Set 0 to see race condition
+// Note: Might require few runs to see race condition
+
+#define THREAD_CNT  8
+
+int32_t value = 100000;
+volatile int32_t counter = 0;
+
+void increment(void)
+{
+    for (int i = 0; i < value; i++) {
+#if (USE_CRITICAL_SECTION_LOCK == 1)
+        CriticalSectionLock  lock;
+#endif
+        counter += 1;
+    }
+}
+
+int get_count(void)
+{
+    if (counter == (value * THREAD_CNT)) {
+        printf("No Race condition\n");
+    } else {
+        printf("Race condition\n");
+    }
+    return counter;
+}
+
+int main()
+{
+    Thread counter_thread[THREAD_CNT];
+
+    for (int i = 0; i < THREAD_CNT; i++) {
+        counter_thread[i].start(callback(increment));
+    }
+
+    // Wait for the threads to finish
+    for (int i = 0; i < THREAD_CNT; i++) {
+        counter_thread[i].join();
+    }
+    printf("Counter = %d\n", get_count());
+}

APIs_Platform/PlatformMutex_ex_1/README.md

@@ -0,0 +1,3 @@
+# PlatformMutex example
+
+This example shows how to use `PlatformMutex` to synchronize the execution of threads.

APIs_Platform/PlatformMutex_ex_1/main.cpp

@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2017 - 2020 Arm Limited and affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "mbed.h"
+
+PlatformMutex stdio_mutex;
+Thread t2;
+Thread t3;
+
+void notify(const char *name, int state)
+{
+    stdio_mutex.lock();
+    printf("%s: %d\n\r", name, state);
+    stdio_mutex.unlock();
+}
+
+void test_thread(void const *args)
+{
+    while (true) {
+        notify((const char *)args, 0);
+        ThisThread::sleep_for(1000);
+        notify((const char *)args, 1);
+        ThisThread::sleep_for(1000);
+    }
+}
+
+int main()
+{
+    t2.start(callback(test_thread, (void *)"Th 2"));
+    t3.start(callback(test_thread, (void *)"Th 3"));
+
+    test_thread((void *)"Th 1");
+}

APIs_Platform/Utils_ex_1/README.md

@@ -0,0 +1,3 @@
+# Platform utils example
+
+This example shows how to use memory statistics API and debug functions.

APIs_Platform/Utils_ex_1/main.cpp

@@ -0,0 +1,47 @@
+/*
+ * Copyright (c) 2017 - 2020 Arm Limited and affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "mbed.h"
+
+#define MAX_THREAD_INFO 10
+
+mbed_stats_heap_t heap_info;
+mbed_stats_stack_t stack_info[ MAX_THREAD_INFO ];
+int main()
+{
+    debug("\nThis message is from debug function");
+    debug_if(1, "\nThis message is from debug_if function");
+    debug_if(0, "\nSOMETHING WRONG!!! This message from debug_if function shouldn't show on bash");
+
+    printf("\nMemoryStats:");
+    mbed_stats_heap_get(&heap_info);
+    printf("\n\tBytes allocated currently: %ld", heap_info.current_size);
+    printf("\n\tMax bytes allocated at a given time: %ld", heap_info.max_size);
+    printf("\n\tCumulative sum of bytes ever allocated: %ld", heap_info.total_size);
+    printf("\n\tCurrent number of bytes allocated for the heap: %ld", heap_info.reserved_size);
+    printf("\n\tCurrent number of allocations: %ld", heap_info.alloc_cnt);
+    printf("\n\tNumber of failed allocations: %ld", heap_info.alloc_fail_cnt);
+
+    mbed_stats_stack_get(&stack_info[0]);
+    printf("\nCumulative Stack Info:");
+    printf("\n\tMaximum number of bytes used on the stack: %ld", stack_info[0].max_size);
+    printf("\n\tCurrent number of bytes allocated for the stack: %ld", stack_info[0].reserved_size);
+    printf("\n\tNumber of stacks stats accumulated in the structure: %ld", stack_info[0].stack_cnt);
+
+    mbed_stats_stack_get_each(stack_info, MAX_THREAD_INFO);
+    printf("\nThread Stack Info:");
+    for (int i = 0; i < MAX_THREAD_INFO; i++) {
+        if (stack_info[i].thread_id != 0) {
+            printf("\n\tThread: %d", i);
+            printf("\n\t\tThread Id: 0x%08lX", stack_info[i].thread_id);
+            printf("\n\t\tMaximum number of bytes used on the stack: %ld", stack_info[i].max_size);
+            printf("\n\t\tCurrent number of bytes allocated for the stack: %ld", stack_info[i].reserved_size);
+            printf("\n\t\tNumber of stacks stats accumulated in the structure: %ld", stack_info[i].stack_cnt);
+        }
+    }
+
+    printf("\nDone...\n\n");
+}
+