Add UnbufferedSerial and BufferedSerial API documentation

Author: hugueskamba

docs/api/io/BufferedSerial.md

@@ -0,0 +1,58 @@
+# BufferedSerial
+
+<span class="images">![](https://os.mbed.com/docs/development/mbed-os-api-doxy/classmbed_1_1_buffered_serial.png)<span>`BufferedSerial` class hierarchy</span></span>
+
+The `BufferedSerial` class provides UART functionality, it is the recommended class for serial data transfers. It allows sending and receiving bytes of data in a sequence using separate transmit (TX) and receive pins (RX). Communication can be between two processors or for sending text to a console.
+
+TX and RX pins can be specified as Not Connected (NC) for simplex (unidirectional) communication or as valid pins for full duplex (bi-directional) communication.
+
+Data is sent/received at a pre-defined speed called baud rate. Standard baud rate include 9600, 119200, 115200 or others.
+
+Pieces of data are transmitted using data packets of configurable sizes divided in different sections which include:
+
+* Start bit: Indicates the start of UART data transmission
+* Data frame: Can be 5 to 8 (or 9 if a parity bit is not used) bits long for the actual data being transferred.
+* Parity bit: Optional bit, used for data error detection.
+* Stop bits: Can be 1 to 2 bits long to signal the end of a data packet.
+
+The `BufferedSerial` class maps targets underlying serial communication functions. See the [porting guide](../porting/serial-port.html) for target serial support.
+
+When the RX interrupt is trigged, the `BufferedSerial` class stores the byte(s) available to read from the hardware buffer to an internal intermediary buffer. When a read request is made, the `BufferedSerial` class uses a mutex lock and enters a critical section to read out the number of bytes requested if as many are available in the intermediary buffer.
+To transmit multiple bytes, the class uses an intermediary buffer to store the bytes to send and monitors the serial interface to transfer them to the hardware buffer as soon as it is available. However, all bytes are written unbuffered if in a critical section.
+Using intermediary buffers allows it to be used reliably for input from non-interrupt context whilst avoiding excess spinning waiting for transmission buffer space.
+
+## Configuration
+
+The following parameters can be configured at object instantiation:
+
+  - _TX_
+  - _RX_
+  - _Baud rate_ - defaults to the value configured in `mbed-os/platform/mbed_lib.json`.
+
+The following parameters can be configured after an `BufferedSerial` object instantiation.
+
+  - _Baud rate_
+  - _Data frame length_
+  - _Parity bit_
+  - _Stop bits_
+
+The default settings for a microcontroller are described as _9600-8-N-1_, a common notation for serial port settings.
+
+Additionally, hardware flow control can also be configured if necessary.
+
+You can view more information about the configurable settings and functions in the class reference.
+
+## Class reference
+
+[![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/mbed-os/development/mbed-os-api-doxy/classmbed_1_1_buffered_serial.html)
+
+<span class="notes">**Note**: On a Windows machine, you need to install a USB serial driver. See [Windows serial configuration](../tutorials/serial-communication.html#windows-serial-driver).</span>
+
+## Example
+
+[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed_example/code/BufferedSerial/)](https://os.mbed.com/teams/mbed_example/code/BufferedSerial/file/112a40a5991a/main.cpp)
+
+
+### Mbed OS usage
+
+Common use cases for `BufferedSerial` are IRQ heavy UART operations, such as the [BLE cordio in the transport driver](https://github.com/ARMmbed/mbed-os/blob/master/features/FEATURE_BLE/targets/TARGET_CORDIO/driver/H4TransportDriver.cpp#L62).

docs/api/io/UnbufferedSerial.md

@@ -0,0 +1,24 @@
+# UnbufferedSerial
+
+<span class="images">![](https://os.mbed.com/docs/development/mbed-os-api-doxy/classmbed_1_1_unbuffered_serial.png)<span>`UnbufferedSerial` class hierarchy</span></span>
+
+The `UnbufferedSerial` class provides UART functionality with an API similar to the [`BufferedSerial`](./UnbufferedSerial.md) class. The classes also share the same default configurations.
+
+Unlike the `BufferedSerial` class, the `UnbufferedSerial` class does not use intermediary buffers to store bytes to transmit to or read from the hardware. The user application is responsible for processing each byte as they are received. The method to read data returns only one byte for every call. It is therefore suitable when more control is required and for use in interrupt handlers with the RTOS. The class can however be used to write multiple bytes at once as it locks the API usage in the RTOS to ensure all bytes are written to the hardware.
+
+You can view more information about the configurable settings and functions in the class reference.
+
+## Class reference
+
+[![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/mbed-os/development/mbed-os-api-doxy/classmbed_1_1_unbuffered_serial.html)
+
+<span class="notes">**Note**: On a Windows machine, you need to install a USB serial driver. See [Windows serial configuration](../tutorials/serial-communication.html#windows-serial-driver).</span>
+
+## Example
+
+[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed_example/code/UnbufferedSerial/)](https://os.mbed.com/teams/mbed_example/code/UnbufferedSerial/file/112a40a5991a/main.cpp)
+
+
+### Mbed OS usage
+
+Common use cases for `UnbufferedSerial` are IRQ heavy UART operations, such as the [BLE cordio in the transport driver](https://github.com/ARMmbed/mbed-os/blob/master/features/FEATURE_BLE/targets/TARGET_CORDIO/driver/H4TransportDriver.cpp#L62).