Serial design draft

docs/design-documents/drivers/serial/diagrams/buffered-serial.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<mxfile host="www.draw.io" modified="2019-10-03T12:49:49.888Z" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.0.1 Safari/605.1.15" etag="qa96CZ4Cujasx1f-117k" version="12.0.2" type="onedrive" pages="1"><diagram id="IPPSj4dfQhI11Ljdv34q" name="Page-1">7ZjbctowEIafhst0jIUduCwkkGF6HFoSeqdYC9ZUWFSIYPL0lWsJbImUw3DwdHrjkVbySv7+XetQQ51p2hN4Fn/kBFjN90haQ3c13w+CW/XMDCttQF5umAhKclN9YxjQV9BG021BCcxLHSXnTNJZ2RjxJIFIlmxYCL4sdxtzVh51hifgGAYRZq71kRIZa2s9bG0aHoBOYj100w/zhik2nfWXzGNM+LJgQvc11BGcy7w0TTvAMnaGS/5e943W9cQEJHKfF5KvYvjN+/Xj84ebUfMRRz3c/3mjvbxgttAfPABBMWvjOehpy5VhIfgiIZC582qovYyphMEMR1nrUomvbLGcMlWrq6I7PTMWCAlpwaSn2wM+BSlWqotpDTU6HTu+iZ1lQQmDNy6IYPphLf5k7XrDRxU0ogNwIQdXlzJ4wAlh18eF/Krhaji4PvGkw2cr/JzxUsOGeJqBYGom7fZiPAYBJI/AddtErvFcEW6jWTW4gQPXBlixeETensga50IWHhSPxdSuVCzaYOu3147FpgPWgQQJeZ+tx6oWMTyf06jMReEQq6eM4bvAVEfFtrtUA85rK117k6fEYgJy99oHpLQDcKkXqAZboBqbAIYlfSnvG7aR1iN84VTNeC2qb/+9m5ZYc74QEei3iuu87ahupZ3tKAfjOPoj/Pqzj4+FVgVjoSIaI3sRaR2pseMovKzGJsT+i+xqEzROlMiOo0uL7B4ODhc5pbKgsaqNjKiqvFE4q+wUOAe3e3tekUCwk7R+smz3LhwI/kGBkPAE9tzzVESpk629O3P/3Eq5B9R/Syk7FZCdCkfn1PmU+p6+9nuoPfSeuvHQIyElz/0tFy9/O4oUL2VOfRRxzh1b9N/7iuaiR5GtYA/7V5140bKyZC+SV/rF2QLsfbywHZ1sMVLVzW1o3n1zpYzufwM=</diagram></mxfile>

docs/design-documents/drivers/serial/diagrams/retarget.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<mxfile host="www.draw.io" modified="2019-10-17T16:20:51.525Z" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.0.1 Safari/605.1.15" etag="r95EQ6_d1ASIV7ZjWYtd" version="12.1.3" type="onedrive" pages="1"><diagram id="VeAL7sxWgT67HavtY4N0" name="Page-1">zVbbjpswEP0apPahFYGQTR43t908rDZVKnV33wxMwJXB1DiB9OtrBxswJHuJKm0kJOzjmbF9zsyA5c6S8o6hLH6gIRDLscPScueW4wwGE0+8JHJQiH0zrpCI4VBhDbDBf0EbKnSHQ8gNQ04p4TgzwYCmKQTcwBBjtDDNtpSYu2Yogh6wCRDpo79wyOMKHTs3DX4POIr1zoPRpFpJkDZWN8ljFNKiBbkLy50xSnk1SsoZEMme5qXyW55ZrQ/GIOXvcRj+/DMrfmM/Wu2nP/Zb72XEFt9UlD0iO3VhyxkREW/qi0EkBzN5dh5iKt4E+wyxg7YRm9VmtR/TyJZmkFryVEvJPAMUNrOA0BwUMfyg2WZ0l4YgDzwQAYoYc9hkKJCrhUgwgcU8IWq5T4C+DTAOZQtShNwBTYDL49tq1RkqcXR6arGKRuvaJm7p7CkMqfSK6tCNAmKgRPiAIE5PkAcfJG+PG7mdn3OGRJo7tgg/PT52n/mehktM4B6loeD5pHT27XplOSLkCCWS5dTPs3NxNoecQ3ImBQz3LyoBRPCvVye1a3+21MMTtdchSfSMTA63BMpb2c0EF5CGajgPCMpzHJhcQYn5kxjb3z01e26tzCUdtp4c9CQVF2o5yelze61xO86031ldcrpjAbzdeDhiEfBX7NT3A0KjTfdVbqnovSIiA4I43pvN/ZSyaoc1xSlvJdHETKI6YXSI6t7Kq92MO4HcbuOZdAJVxPQCHROtvvbluee93ffXj5vVU9VoPtb3jbZvdP2CiSq/uk5Q/2t8WicYXU8nuLyivXdWtHNVFT10O5+FSyt6OO4Ecv5XRYtp85dYmTc/2+7iHw==</diagram></mxfile>

docs/design-documents/drivers/serial/diagrams/serial-classes.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<mxfile host="www.draw.io" modified="2019-10-30T15:23:45.459Z" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.0.2 Safari/605.1.15" etag="Cbni6TBbBp9rgvvEG1H-" version="12.1.8" type="onedrive" pages="1"><diagram id="IPPSj4dfQhI11Ljdv34q" name="Page-1">5Vhtk9IwEP41/XhOSQDho3DAqXejDiriFyc2S5sxNJimR7lff6lN6UtweDnhOuenZjebTfI8u9mdOni4TCaSrII7QYE7yKWJg68dhFqtnqs/qWaTafqokyl8yagxKhRT9gBGadb5MaMQVQyVEFyxVVXpiTAET1V0REqxrpotBK/uuiI+WIqpR7itnTGqgvxe3X4xcQPMD8zWPdTNJpYkNzY3iQJCxbqkwiMHD6UQKhstkyHwFLwcl2zd+C+z24NJCNUhC8JP8utn9/f3D7dX896MeBPy7teV8XJPeGwuPAXJCB+QCMyx1SbHQoo4pJC6cx08WAdMwXRFvHR2rdnXukAtuZZaemgfL98LpIKkpDLHnYBYgpIbbWJmkWugM7GDsJHXJSZyeIMSCbkdMeT7W9cFPnpgIDoCLmzBNWYcbkhI+fPDhbtNg6tjwTWIFwuQQLMoaxxkGB0IWftckPUsyCyQIKRv0pdNSx4nUcS8A3EBWnnrbFRKt+7suHSuk8CJYvfVF3IXEmaHj4LpkxRpXY/TXg3MSMTSA7Oq/KLtc9StOVJE+qAsR3+I2V77dK76T+dKUyQ339J4f9XJxXl57joxyZBJGyM1neM2+kccW44uzHELHUVyKEL4T7NxL+XnZsouzi+LKdyuFSv3RKbqjs7I1N0wnr3veG8fWovBj1vwRiM03tF0fgl/NqsxqLeeF20MdoJm91LHRTckTJUKjZbmeWXR46LMpMLeKpNF2n6KG5I5dTbb9Y731I7DSsEzZ063SUHQEHLrdWebqk8tYJcm9/ULr197k+f5idJi8UMmMy9+a+HRIw==</diagram></mxfile>

docs/design-documents/drivers/serial/diagrams/unbuffered-serial.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<mxfile host="www.draw.io" modified="2019-10-03T12:48:29.038Z" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.0.1 Safari/605.1.15" etag="6hyYaZYwuBLnZXb-3igu" version="12.0.2" type="onedrive" pages="1"><diagram id="IPPSj4dfQhI11Ljdv34q" name="Page-1">7ZjbcpswEIafhkt3DBhiXzZO4kymrdtx29S+U2BtlArkyHIMffqKImGQnPowPjCd3jDSSqzE9++ig+X243TA0Dz6SEMgltMOU8u9sRzH867EMzdk0uC2C8OM4bAw2WvDCP8CaVTdljiERa0jp5RwPK8bA5okEPCaDTFGV/VuU0rqo87RDAzDKEDEtD7ikEfSavu9dcM94Fkkh+46ftEQI9VZfskiQiFdVUzureX2GaW8KMVpH0jOTnEp3rt7o7WcGIOE7/JC8oV9/9p+mQw/tMbdRxQM0MPPlvTyishSfvAIGEbkGi1ATptnigWjyySE3F3bcq9XEeYwmqMgb10J8YUt4jERNVsUzempsYBxSCsmOd0B0Bg4y0QX1epLdDJ2HBU7q4oSCm9UEUH1Q1L8Wel6zUcUJKI9cLkGrjtM4B4lIbk8LtdpGq6OgesTTfp0nqGnnJcY1kdxDoKImVx/S56W0ykwCIsYLFtnvAR0QbydbtPwegZeE2HDYtJt7witcypo/l4xWU3vRkWjDta+unQ0dg2wBiRIwvf5mixqAUGLBQ7qXAQOlv3IGb7zVHVcbbtJJeCilsnamzw5YjPg29c/CGu7AJN6haq3AaqyMSCI49f63mETaTnCZ4rFjEtRHf0P3tXEWtAlC0C+VV3rdUe2lna6owKM4eiP8OVnHx4LvQbGQkM0dvVlpHegxoYj/7waqxD7L7Kpjdc5UiIbjs4tsnlA2F/kFPOKxqI2VqKK8lrhvLJV4ALc9i16QwJBT1L7aNnePnMgOHsFQkIT2HHP0xCljrb2bs39UytlHlL/LaX0VHD1VDg4p06nFOr35g/PrckgHT/3RpOXrD8cbrh8+dtRpHoxc+yjiHHu2KD/ztc0Zz2KbAS737/qyIuWliU7kbzQL04XYOfjhe7oaIuRqK5vRIvu62tl9/Y3</diagram></mxfile>

docs/design-documents/drivers/serial/serial.md

@@ -0,0 +1,335 @@
+# Serial design document
+
+# Table of contents
+
+1. [Serial design document](#serial-design-document).
+1. [Table of contents](#table-of-contents).
+    1. [Revision history](#revision-history).
+1. [Introduction](#introduction).
+    1. [Overview and background](#overview-and-background).
+    1. [Requirements and assumptions](#requirements-and-assumptions).
+1. [System architecture and high-level design](#system-architecture-and-high-level-design).
+    1. [System architecture and component interaction](#system-architecture-and-component-interaction).
+1. [Detailed design](#detailed-design).
+1. [Usage scenarios and examples](#usage-scenarios-and-examples).
+1. [Other Work](#other-work).
+    1. [Related work-Simplification of retarget code](#related-work-simplification-of-retarget-code).
+    1. [Future Work-Deprecation of Stream](#future-work-deprecation-of-stream).
+1. [Roll-out Plan](#roll-out-plan).
+1. [Tools and configuration changes](#tools-and-configuration-changes).
+1. [Other information](#other-information).
+    1. [Deprecations](#deprecations).
+    1. [References](#references).
+
+
+### Revision history
+
+1.0 - Initial version - Evelyne Donnaes - 04/10/2019
+
+# Introduction
+
+### Overview and background
+
+Mbed OS contains multiple serial classes and multiple ways of printing information to the console. Serial classes have evolved over the years to add new functionality to existing classes and compensate for limitations. The result is that there are now multiple variants, not always well documented; therefore it is not clear which class should be used for what purpose. Furthermore, some of the classes pull substantial dependencies whose benefits are not very clear, for example standard library like objects and abstractions, and parts of the system I/O function retarget layer.
+
+This document collects proposals made by various contributors (see [references](#references)) and presents a simplified serial class hierarchy. The aim is to offer two public classes, one for unbuffered I/O and the other for buffered I/O, with a clear definition of which one should be used when. All other serial classes are deprecated and should be removed at a later stage. In addition, the serial classes dependencies will be optimised to only include components that provide valuable functionality.
+
+#### Serial classes in Mbed OS 5.14
+
+**Serial**
+
+`Serial` provides unbuffered I/O and is using blocking HAL calls. It only works for simple printing.
+
+Its main limitations are:
+- It uses a mutex lock so it cannot be used from interrupts.
+- It wastes a lot of CPU time spinning waiting for serial output and it cannot be used reliably for input because it needs interrupt-speed response on read calls but its high-level API cannot be used from interrupts.
+- It lacks buffering so it cannot be used reliably for input and output without flow control.
+- It pulls in the C library stdio system because it uses `Stream`.
+- Although it is a `FileHandle`, its implementation is blocking only and has incorrect read semantics.
+
+**UARTSerial**
+
+`UARTSerial` provides buffered I/O. It can be used reliably for input from non-interrupt context and to avoid excess spinning waiting for transmission buffer space. It also does better blocking and correct POSIX-like `FileHandle` semantics.
+
+It does not use `Stream` so it has the advantage of not pulling in the C stdio library. The drawback is that it doesn't include built-in printf methods, see [Usage scenarios and examples](#usage-scenarios-and-examples) for an example on how to print to a serial port.
+
+**RawSerial**
+
+`RawSerial` provides unbuffered I/O. It has no locks so it is safe to use in interrupts provided that it is the only instance that is using that serial port. Unlike `Serial` and `UARTSerial`, it is not a `FileHandle`.
+
+### Requirements and assumptions
+
+None
+
+# System architecture and high-level design
+
+Applications will have a choice between two public serial classes:
+- `BufferedSerial` should be the default choice for an application, except for specialised cases.
+- `UnbufferedSerial` for an interrupt driven application or one that needs to have more control.
+
+### System architecture and component interaction
+
+The below diagram shows the inheritance hierarchy for the serial classes.
+
+![Serial classes](./diagrams/serial-classes.png)
+
+# Detailed design
+
+### Detailed design : BufferedSerial
+
+`BufferedSerial` is `UARTSerial` renamed to convey the original purpose of the class. In addition, the new class will allow configurability of the transmit and receive buffer size so that each instance of the class can configure its buffer size according to its intended usage, for example a modem may need a large input buffer and a console may not need any input buffer.
+
+The below diagram shows the detailed inheritance hierarchy for `BufferedSerial`.
+
+![BufferedSerial class](./diagrams/buffered-serial.png)
+
+```C
+class BufferedSerial : private SerialBase, public FileHandle, private NonCopyable<BufferedSerial>
+```
+
+`BufferedSerial` privately inherits from `SerialBase`. It means that applications are forced to use the transmit and receive buffers since they cannot access `SerialBase` member functions directly.
+
+**API description**
+
+These are the new constructors for `BufferedSerial`. The first constructor creates the buffers dynamically.
+
+```C
+    /** Create a BufferedSerial port, connected to the specified transmit and receive pins, with a particular baud rate.
+     *  @param tx Transmit pin
+     *  @param rx Receive pin
+     *  @param baud The baud rate of the serial port (optional, defaults to MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE)
+     *  @param rx_buffer_size The size of the receive buffer (optional, defaults to MBED_CONF_DRIVERS_UART_SERIAL_RXBUF_SIZE)
+     *  @param tx_buffer_size The size of the transmit buffer (optional, defaults to MBED_CONF_DRIVERS_UART_SERIAL_TXBUF_SIZE)
+     *
+     *  @note
+     *    Either tx or rx may be specified as NC if unused
+     */
+    BufferedSerial(PinName tx,
+                   PinName rx,
+                   int baud = MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE,
+                   size_t rx_buffer_size = MBED_CONF_DRIVERS_UART_SERIAL_RXBUF_SIZE,
+                   size_t tx_buffer_size = MBED_CONF_DRIVERS_UART_SERIAL_TXBUF_SIZE);
+```
+
+The second constructor takes buffer pointers as arguments.
+
+```C
+    /** Create a BufferedSerial port, connected to the specified transmit and receive pins, with a particular baud rate.
+    *  @param tx Transmit pin
+    *  @param rx Receive pin
+    *  @param baud The baud rate of the serial port (optional, defaults to MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE)
+    *  @param rx_buffer The receive buffer
+    *  @param rx_buffer_size The size of the receive buffer
+    *  @param tx_buffer The transmit buffer
+    *  @param tx_buffer_size The size of the transmit buffer
+    *
+    *  @note
+    *    Either tx or rx may be specified as NC if unused
+    */
+    BufferedSerial(PinName tx,
+                   PinName rx,
+                   int baud = MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE,
+                   void *rx_buffer,
+                   size_t rx_buffer_size,
+                   void *tx_buffer,
+                   size_t tx_buffer_size);
+```
+
+ The rest of the class API is that of `UARTSerial` and is described [here](https://os.mbed.com/docs/mbed-os/v5.14/mbed-os-api-doxy/classmbed_1_1_u_a_r_t_serial.html).
+
+
+### Detailed design : UnbufferedSerial
+
+`UnbufferedSerial` is a new class that adds a `FileHandle` interface to `RawSerial`. `RawSerial` is the preferred implementation for unbuffered I/O but it lacks a `FileHandle` interface and so it cannot be used by the retarget code. Instead the retarget code uses a non-public `DirectSerial` class which adds to the complexity of classes and should be removed. `UnbufferedSerial` will not provide any of the printf methods that `RawSerial` has; applications should use _fdopen_ to get a _FILE*_ to use the printf function, see [Usage scenarios and examples](#usage-scenarios-and-examples).
+
+The below diagram shows the detailed inheritance hierarchy for `UnbufferedSerial`.
+
+![UnbufferedSerial class](./diagrams/unbuffered-serial.png)
+
+**API description**
+
+This is the proposed API for the `UnbufferedSerial` class.
+
+```C
+class UnbufferedSerial: public SerialBase, public FileHandle, private NonCopyable<UnbufferedSerial> {
+
+public:
+    /** Create a UnbufferedSerial port, connected to the specified transmit and receive pins, with the specified baud.
+     *
+     *  @param tx Transmit pin
+     *  @param rx Receive pin
+     *  @param baud The baud rate of the serial port (optional, defaults to MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE)
+     *
+     *  @note
+     *    Either tx or rx may be specified as NC if unused
+     */
+    UnbufferedSerial(PinName tx, PinName rx, int baud = MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE);
+
+    virtual ssize_t write(const void *buffer, size_t size);
+    virtual ssize_t read(void *buffer, size_t size);
+    virtual off_t seek(off_t offset, int whence = SEEK_SET);
+    virtual off_t size();
+    virtual int isatty();
+    virtual int close();
+    virtual short poll(short events) const;
+
+#if !(DOXYGEN_ONLY)
+protected:
+
+    /* Acquire exclusive access to this serial port
+     */
+    virtual void lock(void);
+
+    /* Release exclusive access to this serial port
+     */
+    virtual void unlock(void);
+#endif
+};
+```
+
+# Usage scenarios and examples
+
+### Scenario 1 `Printing to a serial port other than stdout`
+
+The below example shows pseudocode for how to print `Hello` to `device` port using the new API.
+
+```C
+UnbufferedSerial device(TX, RX, 115200);
+device.write("Hello", 6);
+```
+
+Unlike in the case of `Serial::printf`, printf cannot be called directly on a `BufferedSerial` or `UnbufferedSerial` object; instead the application first calls _fdopen_ to get a _FILE*_ to use the printf function.
+This allows the usage of more formatting options at the cost of flash memory (about 2300 bytes in a simple blinky application).
+
+```C
+BufferedSerial device(TX, RX, 115200);
+FILE *out = fdopen(&device, "w");
+fprintf(out, "Hello");
+```
+and similarly for `UnbufferedSerial`
+
+```C
+UnbufferedSerial device(TX, RX, 115200);
+FILE *out = fdopen(&device, "w");
+fprintf(out, "Hello");
+```
+
+### Scenario 2 `Printing to stdout`
+
+There is no change in the current APi in regard to printing to stdout.  Applications can call `printf` directly as shown below. The console baud rate can be configured via `platform.stdio-baud-rate` in `mbed_app.json`.
+
+```C
+printf("Hello");
+```
+or
+```C
+fprintf(stdout, "Hello");
+```
+
+Other alternatives to printing to stdout are by calling `puts` or `write`.
+
+```C
+puts("Hello");
+```
+```C
+BufferedSerial pc(USBTX, USBRX);
+pc.write("Hello", 6);
+```
+
+# Other Work
+
+## Related work-Simplification of retarget code
+
+In Mbed, retargeting is implemented by redefining the system I/O functions.
+The `FileHandle` abstract class provides an interface with file-like operations, such as read and write that can be redefined by the retarget code. The high-level library functions perform input/output by calling the low-level functions which use the system I/O functions to interface with hardware.
+
+The relationship of `FileHandle` and other APIs is as follows:
+
+![Retarget](./diagrams/retarget.png)
+
+The POSIX layer, the memory cost associated with the vtable and virtual functions of the `FileHandle` class, and the static array of `FileHandle*` allocated by the retarget code for file handling has a significant impact on memory. A constrained target that only uses a console does not need file handling and should be able to turn this functionality off.
+
+ A new configuration parameter is introduced to compile the file handling code out. The application can override the default configuration in mbed_app.json as follows:
+
+```C
+    "target_overrides": {
+        "*": {
+            "platform.stdio-minimal-console-only": true
+        }
+    }
+```
+
+There are two approaches to achieve a minimal retarget layer. You can:
+1. Redefine the low-level library functions. A detailed description can be found [here](http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0475m/chr1358938931411.html)
+1. Redefine the system I/O functions.
+
+A minimal console only needs to write a single character at a time. So redefining the default fputc() to directly write to the serial port if the output stream is stdout and bypassing the system I/O functions should achieve higher memory savings. If we take this approach, we will have to rework some error handlers that rely on the POSIX form of `write(STDOUT_FILENO, buf, len)` to do emergency printing.
+
+The second solution keeps the POSIX layer with the main saving coming from dropping the use of `FileHandle` and the file handle table itself. In this case, a `MinimalConsole` class will be implemented as an internal class in the retarget code and `write()` will call `MinimalConsole::putc` in a loop.
+
+```C
+class MinimalConsole {
+public:
+    MinimalConsole(int baud = MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE);
+    ~MinimalConsole();
+    int getc();
+    int putc(int c);
+};
+```
+
+List of tasks to simplify the retarget code:
+
+- Use `UnbufferedSerial` instead of `DirectSerial`
+- Remove `DirectSerial`
+- Add a configuration parameter to compile out file handling feature
+    - Alternative uses weak console_putc/getc functions
+
+## Future work-Deprecation of Stream
+
+The `Stream` class pulls in the <stdio.h> library. It should be replaced by drivers implementing `FileHandle` directly and applications using `fdopen(FileHandle *)` to get a `FILE*` to use full C/C++ stream features.
+
+`Stream` is currently used by the following classes:
+- `Serial`
+- `USBKeyboard`
+- `USBMouseKeyboard`
+- `USBSerial`
+
+Deprecation of `Stream` should be planned in a future release.
+
+# Roll-out Plan
+
+This feature will be implemented in different phases as follows:
+
+Phase 1:
+- [Deprecation of APIs](#Deprecations)
+- Implementation of new class `UnbufferedSerial`
+- Implementation of new class `BufferedSerial`
+- Use `UnbufferedSerial` instead of `DirectSerial` in retarget code (as `DirectSerial` is not a public API it can be directly removed)
+
+Phase 2:
+- Removal of deprecated APIs
+
+# Tools and configuration changes
+
+### Tool changes
+
+None
+
+### Configuration changes
+
+None
+
+# Other information
+
+### Deprecations
+
+The following APIs will be deprecated:
+- `Serial` class
+- `RawSerial` class
+- `UARTSerial` class
+
+### References
+
+https://github.com/ARMmbed/mbed-os/pull/5655
+
+[Tailoring input/output functions in the C and C++ libraries](http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0475m/chr1358938931411.html)