patrick/zephyr
1
0
Fork 0
Code Issues Pull requests Actions 8 Packages Projects Releases Wiki Activity

doc: uart: Make sure uart_poll_in is non-blocking

Browse source 
The documentation has wrongly stated that the function uart_poll_in() is
also a blocking function.  The uart_poll_out() is indeed a blocking
function but uart_poll_in() has never been since day one.

Make it clear that the uart_poll_in() is a NON-blocking function, and
uart_poll_out() IS a blocking.

This fixes #45468.

Signed-off-by: Yasushi SHOJI <yashi@spacecubics.com>
This commit is contained in:
Yasushi SHOJI 2022-05-11 11:37:09 +09:00 committed by Marti Bolivar
parent f089f964fd
commit bc35b1340c
2 changed files with 29 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
doc/hardware/peripherals/uart.rst
View file

@ -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

34
include/zephyr/drivers/uart.h
View file

@ -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.