mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2024-12-29 04:50:03 +01:00
126 lines
4.3 KiB
C
126 lines
4.3 KiB
C
/*
|
|
* Copyright (C) 2015 Kaspar Schleiser <kaspar@schleiser.de>
|
|
* 2018 Freie Universität Berlin
|
|
*
|
|
* This file is subject to the terms and conditions of the GNU Lesser
|
|
* General Public License v2.1. See the file LICENSE in the top level
|
|
* directory for more details.
|
|
*/
|
|
|
|
/**
|
|
* @defgroup sys_stdio_uart STDIO over UART
|
|
* @ingroup sys_stdio
|
|
*
|
|
* @brief Standard input/output backend using UART
|
|
*
|
|
* To enable stdio over UART, enable the `stdio_uart` module:
|
|
*
|
|
* USEMODULE += stdio_uart
|
|
*
|
|
* @note For many board, `stdio_uart` is already the default stdio backend
|
|
* and therefore already enabled.
|
|
*
|
|
* ## Input
|
|
*
|
|
* @warning Standard input is disabled by default on UART. To enable it, load
|
|
* the `stdin` module in your application:
|
|
* ```
|
|
* USEMODULE += stdin
|
|
* ```
|
|
*
|
|
* ## UART Configuration
|
|
*
|
|
* @note Running `make BOARD=<your_board> term` will launch `pyterm` with the
|
|
* correct parameters, so mostly you do not really need to care about
|
|
* the UART configuration.
|
|
*
|
|
* By convention RIOT boards used 8N1 encoding with a symbol rate of 115200 Bd
|
|
* for the UART used as stdio. However, some boards may have a different
|
|
* configuration due to hardware limitations. Most notably, many AVR boards use
|
|
* 9600 Bd as symbol rate instead, as they otherwise frequently loose an input
|
|
* character due to losing interrupts.
|
|
*
|
|
* By default UNIX style line endings (`\n`) are used. However, some terminal
|
|
* programs default to DOS style line endings (`\r\n`). It usually is better to
|
|
* configure the terminal program on the host to use UNIX style line endings.
|
|
* In scenarios this is not possible/desired, you can enable the (pseudo-)
|
|
* module @ref sys_stdio_uart_onlcr to emit DOS style line endings instead.
|
|
*
|
|
* RIOT's shell happily accepts both DOS and UNIX style line endings in any
|
|
* case, so typically no line ending conversion is needed on the input.
|
|
*
|
|
* ## STDIO from ISR
|
|
*
|
|
* @attention Using STDIO over UART from interrupt context should be avoided,
|
|
* except for debugging purposes
|
|
*
|
|
* For testing purposes and using STDIO within an ISR should mostly work good
|
|
* enough and for some platforms even reliable. Production code however should
|
|
* fully avoid any access to STDIO from interrupt context. Instead, e.g. an
|
|
* event could be posted to an @ref sys_event and the actual STDIO operation
|
|
* being deferred to thread context.
|
|
*
|
|
* Some reasons why STDIO over UART from ISR should be avoided:
|
|
* 1. UART is *slow* and the system easily remains in interrupt context for
|
|
* unacceptable long time.
|
|
* - E.g. sending 100 chars at 9600 baud will block the system for
|
|
* 100 milliseconds.
|
|
* - Missed deadlines, lost interrupts, or watch dog timer resets can easily
|
|
* be caused by this.
|
|
* 2. Even if DMA is used for UART, using STDIO within ISR can cause significant
|
|
* delays: If the buffer is full, an UART implementation will be forced to
|
|
* resort to synchronously send the data, rather than using DMA. This might
|
|
* cause even more headache, as the available memory in the DMA buffer when
|
|
* an ISR is triggered has to be assumed as randomly distributed. Thus,
|
|
* hard to reproduce and indeterministic bugs can be the result.
|
|
* 3. If an ISR is triggered from a power saving mode, some peripherals or
|
|
* clock domains might still be offline during that ISR; including the UART
|
|
* peripheral. This is a valid implementation choice to allow time critical
|
|
* low power scenarios being covered by RIOT. Thus, be prepared to
|
|
* loose output when using STDIO from ISR.
|
|
*
|
|
* @{
|
|
* @file
|
|
*
|
|
* @author Kaspar Schleiser <kaspar@schleiser.de>
|
|
* @author Hauke Petersen <hauke.petersen@fu-berlin.de>
|
|
*/
|
|
|
|
#ifndef STDIO_UART_H
|
|
#define STDIO_UART_H
|
|
|
|
/* Boards may override the default STDIO UART device */
|
|
#include "board.h"
|
|
#include "stdio_base.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
#ifndef STDIO_UART_DEV
|
|
/**
|
|
* @brief UART device to use for STDIO
|
|
*/
|
|
#define STDIO_UART_DEV UART_DEV(0)
|
|
#endif
|
|
|
|
#ifndef STDIO_UART_BAUDRATE
|
|
/**
|
|
* @brief Baudrate for STDIO
|
|
*/
|
|
#define STDIO_UART_BAUDRATE (115200)
|
|
#endif
|
|
|
|
#ifndef STDIO_UART_RX_BUFSIZE
|
|
/**
|
|
* @brief Buffer size for STDIO
|
|
*/
|
|
#define STDIO_UART_RX_BUFSIZE (64)
|
|
#endif
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
/** @} */
|
|
#endif /* STDIO_UART_H */
|