UnbufferedSerial: Introduce the class to replace RawSerial

* Deprecate RawSerial.
* Introduce UnbufferedSerial to provide unbuffered I/O by implementing
  with a FileHandle interface for I/O	streams.
* Add Greentea test for the UnbufferedSerial class.

Author: hugueskamba

TESTS/host_tests/serial_comms.py

@@ -0,0 +1,38 @@
+"""
+Copyright (c) 2019 Arm Limited and affiliates.
+
+SPDX-License-Identifier: Apache-2.0
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+from mbed_host_tests import BaseHostTest
+
+
+MSG_KEY_ECHO_MESSAGE = "echo_message"
+
+
+class SerialComms(BaseHostTest):
+    """Host side test that handles messages sent using serial classes."""
+
+    def __init__(self):
+        """Initialize an object."""
+        super(SerialComms, self).__init__()
+
+    def setup(self):
+        """Register call backs to handle message from the target."""
+        self.register_callback(MSG_KEY_ECHO_MESSAGE, self.cb_echo_message)
+
+    def cb_echo_message(self, key, value, timestamp):
+        """Send back the key and value received."""
+        self.send_kv(key, value)

TESTS/mbed_drivers/unbuffered_serial/main.cpp

@@ -0,0 +1,170 @@
+/*
+ * Copyright (c) 2019 Arm Limited and affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+#if !DEVICE_SERIAL
+#error [NOT_SUPPORTED] serial communication not supported for this target
+#else
+
+#include "mbed.h"
+#include "utest/utest.h"
+#include "unity/unity.h"
+#include "greentea-client/test_env.h"
+
+
+using namespace utest::v1;
+
+
+/**
+ * Macros for setting console flow control.
+ */
+#define CONSOLE_FLOWCONTROL_RTS                                               1
+#define CONSOLE_FLOWCONTROL_CTS                                               2
+#define CONSOLE_FLOWCONTROL_RTSCTS                                            3
+#define mbed_console_concat_(x) CONSOLE_FLOWCONTROL_##x
+#define mbed_console_concat(x) mbed_console_concat_(x)
+#define CONSOLE_FLOWCONTROL mbed_console_concat(MBED_CONF_TARGET_CONSOLE_UART_FLOW_CONTROL)
+
+
+#define MSG_KEY_ECHO_MESSAGE                                     "echo_message"
+#define MSG_VALUE_HELLO_WORLD                                   "Hello, world!"
+
+#define EXPECTED_ECHOED_STRING "{{" MSG_KEY_ECHO_MESSAGE ";" MSG_VALUE_HELLO_WORLD "}}"
+// The target is expected to transmit Greentea messages with \n (or \r\n) or they are not detected by the host
+#define STRING_TO_SEND EXPECTED_ECHOED_STRING "\n"
+
+
+static UnbufferedSerial unbuffered_serial_obj(
+    USBTX, USBRX, MBED_CONF_PLATFORM_STDIO_BAUD_RATE
+);
+
+static ssize_t unbuffered_serial_read(void *buffer, ssize_t length)
+{
+    if (length == 0) {
+        return 0;
+    }
+
+    // Ignore the `\n` character previously sent to the host in the previous
+    // key-value pair that was not removed from the FIFO.
+    unsigned char *buf = static_cast<unsigned char *>(buffer);
+    unbuffered_serial_obj.read(buf, 1);
+
+    // Get the message sent by the host
+    for (ssize_t i = 0; i < length; i++) {
+        TEST_ASSERT_EQUAL_UINT(1, unbuffered_serial_obj.read(buf + i, 1));
+    }
+
+    return length;
+}
+
+
+// Test that data sent using an UnbufferedSerial object is correctly sent.
+// The test case sends a Greentea key-value pair message from the target to the
+// host using an UnbufferedSerial object and expects the message
+// to be echoed back by the host. The host response is received via the Greentea
+// framework usual route using greentea_parse_kv(). Success is determined upon
+// reception of the echoed message which indicates that the message was received
+// by the host as it was sent by the target.
+static void test_serial_write()
+{
+    char tx_msg[] = STRING_TO_SEND;
+
+    TEST_ASSERT_EQUAL_UINT(
+        strlen(tx_msg) + 1,
+        unbuffered_serial_obj.write(tx_msg, strlen(tx_msg) + 1)
+    );
+
+    char rx_key[30] = {0};
+    char rx_value[30] = {0};
+    greentea_parse_kv(rx_key, rx_value, sizeof(rx_key), sizeof(rx_value));
+
+    TEST_ASSERT_EQUAL_STRING(MSG_KEY_ECHO_MESSAGE, rx_key);
+    TEST_ASSERT_EQUAL_STRING(MSG_VALUE_HELLO_WORLD, rx_value);
+}
+
+
+// Test that data received using an UnbufferedSerial object is correctly received.
+// The test case sends a Greentea key-value pair message from the target to the
+// host via the Greentea framework usual route using greentea_send_kv().
+// It expects the message to be echoed back to the target. An UnbufferedSerial
+// object is used to handle the received message. Succes is determined upon
+// reception of a key-value pair matching the key-value pair sent by the target.
+static void test_serial_read()
+{
+    greentea_send_kv(MSG_KEY_ECHO_MESSAGE, MSG_VALUE_HELLO_WORLD);
+
+    char rx_msg[sizeof(EXPECTED_ECHOED_STRING)] = {0};
+    // Exclude the null terminator which is not read
+    ssize_t expected_rx_msg_length = sizeof(EXPECTED_ECHOED_STRING) - 1;
+
+    unbuffered_serial_read(rx_msg, expected_rx_msg_length);
+
+    TEST_ASSERT_EQUAL_STRING(EXPECTED_ECHOED_STRING, rx_msg);
+}
+
+
+utest::v1::status_t greentea_setup(const size_t number_of_cases)
+{
+    GREENTEA_SETUP(12, "serial_comms");
+
+    return greentea_test_setup_handler(number_of_cases);
+}
+
+
+utest::v1::status_t greentea_failure_handler(
+    const Case *const source, const failure_t reason
+)
+{
+    greentea_case_failure_abort_handler(source, reason);
+    return STATUS_CONTINUE;
+}
+
+
+Case cases[] = {
+    Case(
+        "Bytes are correctly sent",
+        test_serial_write, greentea_failure_handler
+    ),
+    Case(
+        "Bytes are correctly received",
+        test_serial_read, greentea_failure_handler
+    ),
+};
+
+
+Specification specification(
+    greentea_setup, cases, greentea_test_teardown_handler
+);
+
+
+int main()
+{
+#if   CONSOLE_FLOWCONTROL == CONSOLE_FLOWCONTROL_RTS
+    unbuffered_serial_obj.set_flow_control(
+        SerialBase::RTS, STDIO_UART_RTS, NC
+    );
+#elif CONSOLE_FLOWCONTROL == CONSOLE_FLOWCONTROL_CTS
+    unbuffered_serial_obj.set_flow_control(
+        SerialBase::CTS, NC, STDIO_UART_CTS
+    );
+#elif CONSOLE_FLOWCONTROL == CONSOLE_FLOWCONTROL_RTSCTS
+    unbuffered_serial_obj.set_flow_control(
+        SerialBase::RTSCTS, STDIO_UART_RTS, STDIO_UART_CTS
+    );
+#endif
+    return !Harness::run(specification);
+}
+
+#endif // !DEVICE_SERIAL

drivers/RawSerial.h

@@ -37,7 +37,8 @@ namespace mbed {
  * @{
  */
 
-/** A serial port (UART) for communication with other serial devices
+/** @deprecated
+ * A serial port (UART) for communication with other serial devices
  * This is a variation of the Serial class that doesn't use streams,
  * thus making it safe to use in interrupt handlers with the RTOS.
  *
@@ -59,10 +60,15 @@ namespace mbed {
  * }
  * @endcode
  */
-class RawSerial: public SerialBase, private NonCopyable<RawSerial> {
+class
+    MBED_DEPRECATED_SINCE(
+        "mbed-os-6.0.0",
+        "Use UnbufferedSerial instead."
+    ) RawSerial: public SerialBase, private NonCopyable<RawSerial> {
 
 public:
-    /** Create a RawSerial port, connected to the specified transmit and receive pins, with the specified baud.
+    /** @deprecated
+     * Create a RawSerial port, connected to the specified transmit and receive pins, with the specified baud.
      *
      *  @param tx Transmit pin
      *  @param rx Receive pin
@@ -71,31 +77,41 @@ class RawSerial: public SerialBase, private NonCopyable<RawSerial> {
      *  @note
      *    Either tx or rx may be specified as NC if unused
      */
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     RawSerial(PinName tx, PinName rx, int baud = MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE);
 
-    /** Write a char to the serial port
+    /** @deprecated
+     * Write a char to the serial port
      *
      * @param c The char to write
      *
      * @returns The written char or -1 if an error occurred
      */
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     int putc(int c);
 
-    /** Read a char from the serial port
+    /** @deprecated
+     * Read a char from the serial port
      *
      * @returns The char read from the serial port
      */
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     int getc();
 
-    /** Write a string to the serial port
+    /** @deprecated
+     * Write a string to the serial port
      *
      * @param str The string to write
      *
      * @returns 0 if the write succeeds, EOF for error
      */
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     int puts(const char *str);
 
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     int printf(const char *format, ...) MBED_PRINTF_METHOD(1, 2);
+
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     int vprintf(const char *format, std::va_list arg);
 
 #if !(DOXYGEN_ONLY)

drivers/SerialBase.h

@@ -39,7 +39,7 @@ namespace mbed {
  */
 
 /** A base class for serial port implementations
- * Can't be instantiated directly (use Serial or RawSerial)
+ * Can't be instantiated directly (use UnbufferedSerial or UARTSerial)
  *
  * @note Synchronization level: Set by subclass
  */