Bring platform layer examples (#70)

* Add FileHandle example

* Add FileHandle_sigio example

* Add Poll example

* Add Shared_pointer example

* Add ScopedRamExecutionLock example

* Add ScopedRomWriteLock example

* Fix FileHandle example: use BufferedSerial instead of UARTSerial

* Poll example: add mbed_app.json

* Shared_pointer example: Add missing readme.md

* Add Span examples

* Add uart config to test.json

* Platform examples: Add headers

* Platform examples: Fix after review

Co-authored-by: Qinghao Shi <[email protected]>

Author: mprse

APIs_Platform/FileHandle/README.md

@@ -0,0 +1,10 @@
+## FileHandle example
+
+The example monitors a serial console device, and every time it reads a character, it sends it back to the console and toggles LED2.
+
+1. Flash the board, and ensure the target's USB is plugged into the PC.
+2. Open serial console (select associated COM port, transmission speed: 9600 bps).
+3. Reset the target.
+4. Every time that device reads a character, the character should appear in the console and LED2 should be toggled.
+
+**Note:** You can check the associated serial port using `mbedls` command.

APIs_Platform/FileHandle/main.cpp

@@ -0,0 +1,21 @@
+/*
+ * Copyright (c) 2006-2020 Arm Limited and affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#include "mbed.h"
+
+static DigitalOut led2(LED2);
+
+// BufferedSerial derives from FileHandle
+static BufferedSerial device(STDIO_UART_TX, STDIO_UART_RX);
+
+int main()
+{
+    // Once set up, access through the C library
+    FILE *devin = fdopen(&device, "r");
+
+    while (1) {
+        putchar(fgetc(devin));
+        led2 = !led2;
+    }
+}

APIs_Platform/FileHandle_sigio/README.md

@@ -0,0 +1,10 @@
+## FileHandle sigio example
+
+The example monitors a serial console device, and every time it reads a character, it sends it back to the console and toggles LED2.
+
+1. Flash the board, and ensure the target's USB is plugged into the PC.
+2. Open serial console (select associated COM port, transmission speed: 9600 bps).
+3. Reset the target.
+4. Every time that device reads a character, the character should appear in the console and LED2 should be toggled.
+
+**Note:** You can check the associated serial port using `mbedls` command.

APIs_Platform/FileHandle_sigio/main.cpp

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2006-2020 Arm Limited and affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#include "mbed.h"
+
+static DigitalOut led1(LED1);
+static DigitalOut led2(LED2);
+
+static BufferedSerial device(STDIO_UART_TX, STDIO_UART_RX);
+
+static void callback_ex()
+{
+    // always read until data is exhausted - we may not get another
+    // sigio otherwise
+    while (1) {
+        char c;
+        if (device.read(&c, 1) != 1) {
+            break;
+        }
+        putchar(c);
+        putchar('\n');
+        led2 = !led2;
+    }
+}
+
+int main()
+{
+    // Ensure that device.read() returns -EAGAIN when out of data
+    device.set_blocking(false);
+
+    // sigio callback is deferred to event queue, as we cannot in general
+    // perform read() calls directly from the sigio() callback.
+    device.sigio(mbed_event_queue()->event(callback_ex));
+
+    while (1) {
+        led1 = !led1;
+        ThisThread::sleep_for(500);
+    }
+}

APIs_Platform/Poll/README.md

@@ -0,0 +1,26 @@
+## Poll example
+
+The example transfers bidirectional data between two serial ports, acting as a virtual link.
+
+1. Example `mbed_app.json` file (`K64F`):
+
+```
+{
+    "config": {
+        "UART1_TX": "D1",
+        "UART1_RX": "D0",
+        "UART2_TX": "USBTX",
+        "UART2_RX": "USBRX"
+    }
+}
+```
+
+2. Flash the board, and ensure the target's USB is plugged into the PC (UART2).
+3. Connect second serial port to PC via USB to serial adapter (UART1).
+4. Open two serial consoles (select associated COM ports, transmission speed: 9600 bps).
+5. Reset the target.
+6. Data sent from one console should appear in the other one and vice versa.
+
+**Note:** You can check the associated serial port using `mbedls` command (UART2).  
+**Note:** Note: On Windows you can check the associated COM port in the Device Manager (UART1).  
+**Note:** Please adapt your pins for target different than `K64F`.

APIs_Platform/Poll/main.cpp

@@ -0,0 +1,61 @@
+/*
+ * Copyright (c) 2006-2020 Arm Limited and affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#include "mbed.h"
+
+// Pins for each port are specified using mbed_app.json. Assume no flow control.
+// (If there were flow control, being blocked by it could break the implementation,
+// as you would stop reading input in the opposite direction).
+BufferedSerial device1(MBED_CONF_APP_UART1_TX, MBED_CONF_APP_UART1_RX);
+BufferedSerial device2(MBED_CONF_APP_UART2_TX, MBED_CONF_APP_UART2_RX);
+
+// Precondition: "in" is readable
+static void copy_some(FileHandle *out, FileHandle *in)
+{
+    // To ensure performance, try to read multiple bytes at once,
+    // but don't expect to read many in practice.
+    char buffer[32];
+
+
+
+    // Despite the FileHandle being in its default blocking mode,
+    // read() must return immediately with between 1-32 bytes, as
+    // you've already checked that `in` is ready with poll()
+    ssize_t read = in->read(buffer, sizeof buffer);
+    if (read <= 0) {
+        error("Input error");
+    }
+
+    // Write everything out. Assuming output port is same speed as input,
+    // and no flow control, this may block briefly but not significantly.
+    ssize_t written = out->write(buffer, read);
+    if (written < read) {
+        error("Output error");
+    }
+}
+
+// Transfer bidirectional data between two ports, acting as a virtual link.
+// poll() is used to monitor both ports for input.
+int main()
+{
+    pollfh fds[2];
+
+    fds[0].fh = &device1;
+    fds[0].events = POLLIN;
+    fds[1].fh = &device2;
+    fds[1].events = POLLIN;
+
+    while (1) {
+        // Block indefinitely until either of the 2 ports is readable (or has an error)
+        poll(fds, 2, -1);
+
+        // Transfer some data in either or both directions
+        if (fds[0].revents) {
+            copy_some(fds[1].fh, fds[0].fh);
+        }
+        if (fds[1].revents) {
+            copy_some(fds[0].fh, fds[1].fh);
+        }
+    }
+}

APIs_Platform/Poll/mbed_app.json

@@ -0,0 +1,8 @@
+{
+    "config": {
+        "UART1_TX": "D1",
+        "UART1_RX": "D0",
+        "UART2_TX": "USBTX",
+        "UART2_RX": "USBRX"
+    }
+}

APIs_Platform/ScopedRamExecutionLock/README.md

@@ -0,0 +1,3 @@
+## ScopedRamExecutionLock example
+
+The example shows how to use ScopedRamExecutionLock class for enabling execution from RAM. 

APIs_Platform/ScopedRamExecutionLock/main.cpp

@@ -0,0 +1,13 @@
+/*
+ * Copyright (c) 2006-2020 Arm Limited and affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#include "mbed.h"
+
+int main()
+{
+    // Enable execution from RAM while in main
+    ScopedRamExecutionLock make_ram_executable;
+
+    //some_function_in_ram();
+}

APIs_Platform/ScopedRomWriteLock/README.md

@@ -0,0 +1,3 @@
+## ScopedRomWriteLock example
+
+The example shows how to use ScopedRomWriteLock class for enabling writing to ROM. 

APIs_Platform/ScopedRomWriteLock/main.cpp

@@ -0,0 +1,13 @@
+/*
+ * Copyright (c) 2006-2020 Arm Limited and affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#include "mbed.h"
+
+int main()
+{
+    // Enable writing to ROM while in main
+    ScopedRomWriteLock make_rom_writable;
+
+    //custom_flash_programming();
+}

APIs_Platform/Shared_pointer/README.md

@@ -0,0 +1,3 @@
+## Shared Pointer example
+
+The example shows how to use "smart" pointer.

APIs_Platform/Shared_pointer/main.cpp

@@ -0,0 +1,22 @@
+/*
+ * Copyright (c) 2006-2020 Arm Limited and affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#include "platform/SharedPtr.h"
+
+int main(void)
+{
+    struct MyStruct {
+        int a;
+    };
+
+    // Create shared pointer
+    SharedPtr<MyStruct> ptr(new MyStruct);
+
+    // Increase reference count
+    SharedPtr<MyStruct> ptr2(ptr);
+
+    ptr = nullptr; // Reference to the struct instance is still held by ptr2
+
+    ptr2 = nullptr; // The raw pointer is freed
+}

APIs_Platform/Span_c/README.md

@@ -0,0 +1,5 @@
+## Span example
+
+The example shows how to use Span class to operate on the string buffer.
+
+**Note:** C example code

APIs_Platform/Span_c/main.cpp

@@ -0,0 +1,37 @@
+/*
+ * Copyright (c) 2006-2020 Arm Limited and affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#include "mbed.h"
+#include "platform/Span.h"
+
+template<typename T>
+void split(const T **in_ptr, ptrdiff_t *in_size, const T **token_ptr, ptrdiff_t *token_size, const T &separator)
+{
+    const ptrdiff_t out_of_range = *in_size;
+
+    ptrdiff_t start;
+    for (start = 0; start != out_of_range && (*in_ptr)[start] == separator; ++start) { }
+
+    ptrdiff_t last;
+    for (last = start; last != out_of_range && (*in_ptr)[last] != separator; ++last) { }
+
+    *token_ptr = *in_ptr + start;
+    *token_size = last - start;
+
+    *in_size = *in_size - last;
+    *in_ptr = *in_ptr + last;
+}
+
+int main()
+{
+    const char str[] = "Hello World! Hello mbed-os!";
+    const char *buffer_ptr = str;
+    ptrdiff_t buffer_size = sizeof(str);
+    while (buffer_size) {
+        const char *token_ptr = NULL;
+        ptrdiff_t token_size = 0;
+        split(&buffer_ptr, &buffer_size, &token_ptr, &token_size, ' ');
+        printf("token: %.*s\r\n", token_size, token_ptr);
+    }
+}

APIs_Platform/Span_cpp/README.md

@@ -0,0 +1,5 @@
+## Span example
+
+The example shows how to use Span class to operate on the string buffer.
+
+**Note:** C++ example code

APIs_Platform/Span_cpp/main.cpp

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2006-2020 Arm Limited and affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#include "mbed.h"
+#include "platform/Span.h"
+
+template<typename T>
+Span<const T> split(Span<const T> &range, const T &separator)
+{
+    const ptrdiff_t out_of_range = range.size();
+
+    ptrdiff_t start;
+    for (start = 0; start != out_of_range && range[start] == separator; ++start) { }
+
+    ptrdiff_t last;
+    for (last = start; last != out_of_range && range[last] != separator; ++last) { }
+
+    Span<const T> result = range.subspan(start, last - start);
+    range = range.subspan(last);
+    return result;
+}
+
+
+int main()
+{
+    Span<const char> buffer("Hello World! Hello mbed-os!");
+    while (buffer.empty() == false) {
+        Span<const char> token = split(buffer, ' ');
+        printf("token: %.*s\r\n", token.size(), token.data());
+    }
+}

test.json

@@ -1,5 +1,9 @@
 {
 	"config": {
+		"UART1_TX": "D1",
+		"UART1_RX": "D0",
+		"UART2_TX": "USBTX",
+		"UART2_RX": "USBRX",
 		"wifi-ssid": {
 			"help": "WiFi SSID",
 			"value": "\"SSID\""