From 4c41f7a994e3fdff0c42d9ccba7f2e678d8111d0 Mon Sep 17 00:00:00 2001
From: PeterKietzmann <peter.kietzmann@haw-hamburg.de>
Date: Fri, 18 Dec 2015 15:38:57 +0100
Subject: [PATCH] periph/uart: extend uart API doc
---
drivers/include/periph/uart.h | 23 +++++++++++++++++++++++
1 file changed, 23 insertions(+)
diff --git a/drivers/include/periph/uart.h b/drivers/include/periph/uart.h
index c29f3b4b26..52af846c65 100644
--- a/drivers/include/periph/uart.h
+++ b/drivers/include/periph/uart.h
@@ -12,6 +12,29 @@
* @brief Low-level UART peripheral driver
* @{
*
+ * This is a basic UART (Universal Asynchronous Receiver Transmitter) interface
+ * to allow platform independent access to the MCU's serial communication abilities.
+ * This interface is intentionally designed to be as simple as possible, to allow
+ * for easy implementation and maximum portability. In RIOT we only use the
+ * common 8-N-1 format of the serial port (8 data bist, no parity bit, one stop bit).
+ *
+ * The simple interface provides capabilities to initialize the serial communication
+ * module, which automatically enables for receiving data, as well as writing data
+ * to the UART port, which means transmitting data. The UART device and the
+ * corresponding pins need to be mapped in `RIOT/boards/ * /include/periph_conf.h`.
+ * Furthermore you need to select the baudrate for initialization which is typically
+ * {9600, 19200, 38400, 57600, 115200} baud. Additionally you should register a
+ * callback function that is executed in interrupt context when data is being received.
+ * The driver will then read the received data byte, call the registered callback
+ * function and pass the received data to it via its argument. The interface enforces
+ * the receiving to be impemented in an interrupt driven mode. Thus, you never now how
+ * many bytes are going to be received and might want to handle that in your specific
+ * callback function. The transmit function can be implemented in any way
+ *
+ * By default the @p UART_DEV(0) device of each board is initialized and mapped to STDIO
+ * in RIOT which is used for standard input/output functions like `printf()` or
+ * `puts()`.
+ *
* @file
* @brief Low-level UART peripheral driver interface definition
*
--
GitLab