From 2e3dd2f2c045d86ac7d33d9dae19b2b7dd409f84 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Mon, 22 May 2017 20:00:03 +0300 Subject: [PATCH] drivers: serial: Clarification for uart_fifo_fill()/read() calls As they are part of interrupt-driver API, they must be called from an ISR. That means that calling it outside IST may not have a desired effect, and vice-versa, not calling them from ISR can lead to issues. The patch also eleborates/fixes description of uart_irq_rx_ready(). Jira: ZEP-2016 Signed-off-by: Paul Sokolovsky --- include/uart.h | 30 +++++++++++++++++++++++++++--- 1 file changed, 27 insertions(+), 3 deletions(-) diff --git a/include/uart.h b/include/uart.h index 4f246d750356a..5c29e92e9feff 100644 --- a/include/uart.h +++ b/include/uart.h @@ -241,6 +241,15 @@ static inline unsigned char uart_poll_out(struct device *dev, /** * @brief Fill FIFO with data. * + * @details This function is expected to be called from UART + * interrupt handler (ISR), if uart_irq_tx_ready() returns true. + * Result of calling this function not from an ISR is undefined + * (hardware-dependent). Likewise, *not* calling this function + * from an ISR if uart_irq_tx_ready() returns true may lead to + * undefined behavior, e.g. infinite interrupt loops. It's + * mandatory to test return value of this function, as different + * hardware has different FIFO depth (oftentimes just 1). + * * @param dev UART device structure. * @param tx_data Data to transmit. * @param size Number of bytes to send. @@ -262,6 +271,16 @@ static inline int uart_fifo_fill(struct device *dev, const u8_t *tx_data, /** * @brief Read data from FIFO. * + * @details This function is expected to be called from UART + * interrupt handler (ISR), if uart_irq_rx_ready() returns true. + * Result of calling this function not from an ISR is undefined + * (hardware-dependent). It's unspecified whether "RX ready" + * condition as returned by uart_irq_rx_ready() is level- or + * edge- triggered. That means that once uart_irq_rx_ready() is + * detected, uart_fifo_read() must be called until it reads all + * available data in the FIFO (i.e. until it returns less data + * than was requested). + * * @param dev UART device structure. * @param rx_data Data container. * @param size Container size. @@ -406,16 +425,21 @@ static inline int __deprecated uart_irq_tx_empty(struct device *dev) } /** - * @brief Check if UART RX buffer has a new char + * @brief Check if UART RX buffer has a received char * + * @details Check if UART RX buffer has at least one pending character * (i.e. uart_fifo_read() will succeed and return non-zero). This function * must be called in a UART interrupt handler, or its result is undefined. * Before calling this function in the interrupt handler, uart_irq_update() - * must be called once per the handler invocation. + * must be called once per the handler invocation. It's unspecified whether + * condition as returned by this function is level- or edge- triggered (i.e. + * if this function returns true when RX FIFO is non-empty, or when a new + * char was received since last call to it). See description of + * uart_fifo_read() for implication of this. * * @param dev UART device structure. * - * @retval 1 If a new received char is ready. + * @retval 1 If a received char is ready. * @retval 0 Otherwise. */ static inline int uart_irq_rx_ready(struct device *dev)