riot-ci/RIOT
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request #16632 from maribu/periph/uart

Browse Source 
periph/uart: Fix doc, use errno for return values
This commit is contained in:
benpicco 2021-07-21 00:12:24 +02:00 committed by GitHub
commit 07b3e19d01
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 21 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
drivers/include/periph/uart.h
View File

@ -21,7 +21,7 @@
* data, as well as writing data to the UART port, which means transmitting * 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 * 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 * `RIOT/boards/ * /include/periph_conf.h`. Furthermore, you need to select the
* baudrate for initialization which is typically {9600, 19200, 38400, 57600, * symbol rate for initialization which is typically {9600, 19200, 38400, 57600,
* 115200} baud. Additionally, you should register a callback function that is * 115200} baud. Additionally, you should register a callback function that is
* executed in interrupt context when data is being received. The driver will * executed in interrupt context when data is being received. The driver will
* then read the received data byte, call the registered callback function and * then read the received data byte, call the registered callback function and
@ -58,9 +58,10 @@
#ifndef PERIPH_UART_H #ifndef PERIPH_UART_H
#define PERIPH_UART_H #define PERIPH_UART_H
#include <errno.h>
#include <limits.h>
#include <stddef.h> #include <stddef.h>
#include <stdint.h> #include <stdint.h>
#include <limits.h>
#include "periph_cpu.h" #include "periph_cpu.h"
#include "periph_conf.h" #include "periph_conf.h"
@ -110,13 +111,15 @@ typedef struct {
/** /**
* @brief Possible UART return values * @brief Possible UART return values
*
* @deprecated Use the errno constants directly instead.
*/ */
enum { enum {
UART_OK = 0, /**< everything in order */ UART_OK = 0, /**< everything in order */
UART_NODEV = -1, /**< invalid UART device given */ UART_NODEV = -ENODEV, /**< invalid UART device given */
UART_NOBAUD = -2, /**< given baudrate is not applicable */ UART_NOBAUD = -ENOTSUP, /**< given symbol rate is not applicable */
UART_INTERR = -3, /**< all other internal errors */ UART_NOMODE = -ENOTSUP, /**< given mode is not applicable */
UART_NOMODE = -4 /**< given mode is not applicable */ UART_INTERR = -EIO, /**< all other internal errors */
}; };
/** /**
@ -161,24 +164,24 @@ typedef enum {
* - 8 data bits * - 8 data bits
* - no parity * - no parity
* - 1 stop bit * - 1 stop bit
* - baudrate as given * - symbol rate as given
* *
* If no callback parameter is given (rx_cb := NULL), the UART will be * If no callback parameter is given (rx_cb := NULL), the UART will be
* initialized in TX only mode. * initialized in TX only mode.
* *
* @param[in] uart UART device to initialize * @param[in] uart UART device to initialize
* @param[in] baudrate desired baudrate in baud/s * @param[in] baud desired symbol rate in baud
* @param[in] rx_cb receive callback, executed in interrupt context once * @param[in] rx_cb receive callback, executed in interrupt context once
* for every byte that is received (RX buffer filled), * for every byte that is received (RX buffer filled),
* set to NULL for TX only mode * set to NULL for TX only mode
* @param[in] arg optional context passed to the callback functions * @param[in] arg optional context passed to the callback functions
* *
* @return UART_OK on success * @retval 0 Success
* @return UART_NODEV on invalid UART device * @retval -ENODEV Invalid UART device
* @return UART_NOBAUD on inapplicable baudrate * @retval -ENOTSUP Unsupported symbol rate
* @return UART_INTERR on other errors * @retval <0 On other errors
*/ */
int uart_init(uart_t uart, uint32_t baudrate, uart_rx_cb_t rx_cb, void *arg); int uart_init(uart_t uart, uint32_t baud, uart_rx_cb_t rx_cb, void *arg);
#if defined(MODULE_PERIPH_UART_RECONFIGURE) || DOXYGEN #if defined(MODULE_PERIPH_UART_RECONFIGURE) || DOXYGEN
/** /**
@ -251,8 +254,9 @@ gpio_t uart_pin_tx(uart_t uart);
* @param[in] parity parity mode * @param[in] parity parity mode
* @param[in] stop_bits number of stop bits in a UART frame * @param[in] stop_bits number of stop bits in a UART frame
* *
* @return UART_OK on success * @retval 0 Success
* @return UART_NOMODE on other errors * @retval -ENOTSUP Given configuration not supported
* @retval <0 Other error
*/ */
int uart_mode(uart_t uart, uart_data_bits_t data_bits, uart_parity_t parity, int uart_mode(uart_t uart, uart_data_bits_t data_bits, uart_parity_t parity,
uart_stop_bits_t stop_bits); uart_stop_bits_t stop_bits);