Merge pull request #1220 from ARMmbed/hk-add-unbuffered-serial-api-doc

Add UnbufferedSerial and BufferedSerial API documentation

Author: Amanda Butler

docs/api/io/BufferedSerial.md

@@ -0,0 +1,73 @@
+# 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. We recommend you use this class for serial data transfers. You can use it to send and receive bytes of data in a sequence using separate transmit (TX) and receive pins (RX). A device can interface with another device (such as sensors, printers or another board) to exchange data or to send text to be displayed on a text-based computer interface.
+
+Serial channels have the following characteristics:
+
+- TX and RX pins - you can specify either pin as Not Connected (NC) for simplex (unidirectional) communication or both as valid pins for full duplex (bidirectional) communication.
+- Baud rate - predefined speed at which data is sent and received on the UART interface. Standard baud rates include 9600, 119200 and 115200.
+
+Data is transmitted using 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 for the actual data being transferred.
+- Parity bit: optional bit, used for data error detection.
+- Stop bits: 1-2 bits to signal the end of a data packet.
+
+The `BufferedSerial` calls the underlying HAL API functions. Please see the [porting guide](../porting/serial-port.html) for target serial support.
+
+When the receive interrupt is triggered when receiving data from a device, 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 the UART interface to be used reliably for input from noninterrupt context while avoiding excess spinning waiting for transmission buffer space.
+
+The RX and TX buffers are circular buffers with preallocated sizes configurable using the configuration parameters `uart-serial-rxbuf-size` and `uart-serial-txbuf-size`. You can find both configuration parameters in `drivers/mbed_lib.json`.
+
+## Configuration
+
+The following parameters can be configured at object instantiation:
+
+  - _TX_.
+  - _RX_.
+  - _Baud rate_.
+
+The default baud rate value is 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 set as _9600-8-N-1_, a common notation for serial port settings. This denotes a baud rate of 9,600 (9600), eight data frame length (8), no parity bit (N) and one stop bit (1).
+
+You can also configure hardware flow control if necessary.
+
+You can view more information about the configurable settings and functions in the class reference.
+
+## BufferedSerial 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. Please see the [Windows serial configuration](../tutorials/serial-communication.html#windows-serial-driver) document for more information.</span>
+
+## BufferedSerial examples
+
+This example toggles an LED and echoes input to a terminal:
+
+[![View code](https://www.mbed.com/embed/?url=https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/APIs_Drivers/BufferedSerial_echo)](https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/APIs_Drivers/BufferedSerial_echo/main.cpp)
+
+### Printing to the console
+
+Mbed OS redefines target-dependent I/O functions in the C library to allow you to use the C standard I/O library functions (`s\v\f\n\printf`, `scanf` and so on) in your application for printing to the console.
+
+You can configure the system I/O retarget code to be buffered or unbuffered, depending on the configuration of the parameter `stdio-buffered-serial` in `platform/mbed_lib.json`. When it is buffered, the retarget code uses an instance of a `BufferedSerial` class to perform the actual printing. This is where `BufferedSerial`'s `Filehandle` inheritance is used.
+
+Alternatively, if you need more configuration of the serial interface, you can pass an instance of the `BufferedSerial` class to the system I/O retarget code at run time for printing to the console:
+
+[![View code](https://www.mbed.com/embed/?url=https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/APIs_Drivers/BufferedSerial_printf)](https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/APIs_Drivers/BufferedSerial_printf/main.cpp)
+
+We recommend you use the standard C I/O library directly to print to the console in Mbed OS.

docs/api/io/UnbufferedSerial.md

@@ -0,0 +1,25 @@
+# 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](../apis/BufferedSerial.html) 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 it is received. The method to read data returns only one byte for every call. Therefore, we recommend you use this class when you need more control and for use in interrupt handlers with the RTOS. You can also use this class to write multiple bytes at once. Because it does not acquire a mutex lock, you must ensure only one instance uses the serial port.
+
+For normal blocking applications that require a serial channel for something other than the console, BufferedSerial performs better than `UnbufferedSerial` and causes less CPU load and fewer latency issues. Only applications that are short of RAM and cannot afford buffering or that need more control of the serial port and use it from IRQ should use UnbufferedSerial.
+
+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://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/APIs_Drivers/UnbufferedSerial)](https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/APIs_Drivers/UnbufferedSerial/main.cpp)
+
+### Mbed OS use
+
+Common use cases for `UnbufferedSerial` are IRQ heavy UART operations, such as [BLE Cordio in the transport driver](https://github.com/ARMmbed/mbed-os/blob/master/features/FEATURE_BLE/targets/TARGET_CORDIO/driver/H4TransportDriver.cpp#L62).