diff --git a/doc/hardware/peripherals/uart.rst b/doc/hardware/peripherals/uart.rst index 062821b3a50c9..78274f685059f 100644 --- a/doc/hardware/peripherals/uart.rst +++ b/doc/hardware/peripherals/uart.rst @@ -13,8 +13,11 @@ on the method, different API functions are used according to below sections: 2. :ref:`uart_interrupt_api` 3. :ref:`uart_async_api` using :ref:`dma_api` -Polling is the most basic method to access the UART peripheral. The functions -are blocking and the thread waits until a character is sent or received. +Polling is the most basic method to access the UART peripheral. The reading +function, `uart_poll_in`, is a non-blocking function and returns a character +or `-1` when no valid data is available. The writing function, +`uart_poll_out`, is a blocking function and the thread waits until the given +character is sent. With the Interrupt-driven API, possibly slow communication can happen in the background while the thread continues with other tasks. The Kernel's diff --git a/include/zephyr/drivers/uart.h b/include/zephyr/drivers/uart.h index 3d9268b0dc1bd..231f49cd3ce30 100644 --- a/include/zephyr/drivers/uart.h +++ b/include/zephyr/drivers/uart.h @@ -493,7 +493,13 @@ static inline int z_impl_uart_err_check(const struct device *dev) */ /** - * @brief Poll the device for input. + * @brief Read a character from the device for input. + * + * This routine checks if the receiver has valid data. When the + * receiver has valid data, it reads a character from the device, + * stores to the location pointed to by p_char, and returns 0 to the + * calling thread. It returns -1, otherwise. This function is a + * non-blocking call. * * @param dev UART device instance. * @param p_char Pointer to character. @@ -520,7 +526,13 @@ static inline int z_impl_uart_poll_in(const struct device *dev, } /** - * @brief Poll the device for wide data input. + * @brief Read a 16-bit datum from the device for input. + * + * This routine checks if the receiver has valid data. When the + * receiver has valid data, it reads a 16-bit datum from the device, + * stores to the location pointed to by p_u16, and returns 0 to the + * calling thread. It returns -1, otherwise. This function is a + * non-blocking call. * * @param dev UART device instance. * @param p_u16 Pointer to 16-bit data. @@ -554,11 +566,12 @@ static inline int z_impl_uart_poll_in_u16(const struct device *dev, } /** - * @brief Output a character in polled mode. + * @brief Write a character to the device for output. * - * This routine checks if the transmitter is empty. - * When the transmitter is empty, it writes a character to the data - * register. + * This routine checks if the transmitter is full. When the + * transmitter is not full, it writes a character to the data + * register. It waits and blocks the calling thread, otherwise. This + * function is a blocking call. * * To send a character when hardware flow control is enabled, the handshake * signal CTS must be asserted. @@ -579,11 +592,12 @@ static inline void z_impl_uart_poll_out(const struct device *dev, } /** - * @brief Output wide data in polled mode. + * @brief Write a 16-bit datum to the device for output. * - * This routine checks if the transmitter is empty. - * When the transmitter is empty, it writes a datum to the data - * register. + * This routine checks if the transmitter is full. When the + * transmitter is not full, it writes a 16-bit datum to the data + * register. It waits and blocks the calling thread, otherwise. This + * function is a blocking call. * * To send a datum when hardware flow control is enabled, the handshake * signal CTS must be asserted.