Serial: Deprecate the class and promote UnbufferedSerial instead

Author: hugueskamba

drivers/Serial.h

@@ -33,7 +33,8 @@ namespace mbed {
  * @{
  */
 
-/** A serial port (UART) for communication with other serial devices
+/** @deprecated
+ * A serial port (UART) for communication with other serial devices
  *
  * Can be used for Full Duplex communication, or Simplex by specifying
  * one pin as NC (Not Connected)
@@ -53,7 +54,11 @@ namespace mbed {
  * }
  * @endcode
  */
-class Serial : public SerialBase, public Stream, private NonCopyable<Serial> {
+class
+    MBED_DEPRECATED_SINCE(
+        "mbed-os-6.0.0",
+        "Use printf and puts instead to access the console, BufferedSerial for blocking applications or UnbufferedSerial if bypassing locks in IRQ or short of RAM."
+    ) Serial : public SerialBase, public Stream, private NonCopyable<Serial> {
 
 public:
 #if DEVICE_SERIAL_ASYNCH
@@ -67,7 +72,8 @@ class Serial : public SerialBase, public Stream, private NonCopyable<Serial> {
     using SerialBase::enable_input;
     using SerialBase::enable_output;
 
-    /** Create a Serial port, connected to the specified transmit and receive pins
+    /** @deprecated
+     * Create a Serial port, connected to the specified transmit and receive pins
      *
      *  @param tx Transmit pin
      *  @param rx Receive pin
@@ -77,9 +83,11 @@ class Serial : public SerialBase, public Stream, private NonCopyable<Serial> {
      *  @note
      *    Either tx or rx may be specified as NC (Not Connected) if unused
      */
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     Serial(PinName tx, PinName rx, const char *name = NULL, int baud = MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE);
 
-    /** Create a Serial port, connected to the specified transmit and receive pins
+    /** @deprecated
+     * Create a Serial port, connected to the specified transmit and receive pins
      *
      *  @param static_pinmap reference to structure which holds static pinmap.
      *  @param name The name of the stream associated with this serial port (optional)
@@ -88,10 +96,13 @@ class Serial : public SerialBase, public Stream, private NonCopyable<Serial> {
      *  @note
      *    Either tx or rx may be specified as NC (Not Connected) if unused
      */
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     Serial(const serial_pinmap_t &static_pinmap, const char *name = NULL, int baud = MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE);
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     Serial(const serial_pinmap_t &&, const char * = NULL, int = MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE) = delete; // prevent passing of temporary objects
 
-    /** Create a Serial port, connected to the specified transmit and receive pins, with the specified baud
+    /** @deprecated
+     * Create a Serial port, connected to the specified transmit and receive pins, with the specified baud
      *
      *  @param tx Transmit pin
      *  @param rx Receive pin
@@ -100,31 +111,38 @@ class Serial : public SerialBase, public Stream, private NonCopyable<Serial> {
      *  @note
      *    Either tx or rx may be specified as NC (Not Connected) if unused
      */
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     Serial(PinName tx, PinName rx, int baud);
 
-    /** Create a Serial port, connected to the specified transmit and receive pins, with the specified baud
+    /** @deprecated
+     * Create a Serial port, connected to the specified transmit and receive pins, with the specified baud
      *
      *  @param static_pinmap reference to structure which holds static pinmap.
      *  @param baud The baud rate of the serial port
      *
      *  @note
      *    Either tx or rx may be specified as NC (Not Connected) if unused
      */
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     Serial(const serial_pinmap_t &static_pinmap, int baud);
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     Serial(const serial_pinmap_t &&, int) = delete; // prevent passing of temporary objects
 
     /* Stream gives us a FileHandle with non-functional poll()/readable()/writable. Pass through
      * the calls from the SerialBase instead for backwards compatibility. This problem is
      * part of why Stream and Serial should be deprecated.
      */
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     bool readable()
     {
         return SerialBase::readable();
     }
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     bool writable()
     {
         return SerialBase::writeable();
     }
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     bool writeable()
     {
         return SerialBase::writeable();

drivers/UnbufferedSerial.h

@@ -155,6 +155,15 @@ class UnbufferedSerial:
      */
     virtual short poll(short events) const;
 
+    /* Resolve ambiguities versus our private SerialBase
+     * (for writable, spelling differs, but just in case)
+     */
+    using SerialBase::readable;
+    using SerialBase::writeable;
+    using SerialBase::format;
+    using SerialBase::attach;
+    using SerialBase::baud;
+
 #if DEVICE_SERIAL_FC
     // For now use the base enum - but in future we may have extra options
     // such as XON/XOFF or manual GPIO RTSCTS.

features/FEATURE_BLE/targets/TARGET_CORDIO/driver/H4TransportDriver.cpp

@@ -53,7 +53,7 @@ uint16_t H4TransportDriver::write(uint8_t type, uint16_t len, uint8_t *pData)
     while (i < len + 1) {
         uint8_t to_write = i == 0 ? type : pData[i - 1];
         while (uart.writeable() == 0);
-        uart.putc(to_write);
+        uart.write(&to_write, 1);
         ++i;
     }
     return len;
@@ -62,7 +62,8 @@ uint16_t H4TransportDriver::write(uint8_t type, uint16_t len, uint8_t *pData)
 void H4TransportDriver::on_controller_irq()
 {
     while (uart.readable()) {
-        uint8_t char_received = uart.getc();
+        uint8_t char_received;
+        uart.read(&char_received, 1);
         on_data_received(&char_received, 1);
     }
 }

features/FEATURE_BLE/targets/TARGET_Cypress/COMPONENT_CYW43XXX/CyH4TransportDriver.cpp

@@ -151,7 +151,7 @@ uint16_t CyH4TransportDriver::write(uint8_t type, uint16_t len, uint8_t *pData)
     while (i < len + 1) {
         uint8_t to_write = i == 0 ? type : pData[i - 1];
         while (uart.writeable() == 0);
-        uart.putc(to_write);
+        uart.write(&to_write, 1);
         ++i;
     }
 
@@ -165,8 +165,10 @@ void CyH4TransportDriver::on_controller_irq()
     sleep_manager_lock_deep_sleep();
 
     while (uart.readable()) {
-        uint8_t char_received = uart.getc();
-        on_data_received(&char_received, 1);
+        uint8_t char_received;
+        if (uart.read(&char_received, 1)) {
+            on_data_received(&char_received, 1);
+        }
     }
 
     sleep_manager_unlock_deep_sleep();