drivers: uart: clarification of poll_out blocking duration

[hubertmis]

The API docs state that the uart_poll_out is a blocking call, but it does not specify how long a call to this function should block the calling thread. This is described in the UART driver documentation.

This patch clarifies the API docs and aligns it with the driver documentation.

ref

zephyr/doc/hardware/peripherals/uart.rst

Lines 18 to 20 in 1a5ae37

	or ``-1`` when no valid data is available. The writing function,
	:c:func:`uart_poll_out`, is a blocking function and the thread waits until the given
	character is sent.

[gramsay0]

Doesn't it block until the TX FIFO has space for the character, rather than until the character is sent?

[hubertmis]

The doc I linked says "until the give character is sent". My intention is to unify these docs.

[nordic-krch]

What is the benefit of blocking in poll out until byte is sent?

[hubertmis]

I guess information for the API user when the byte is sent. I don't think there is any other function to poll for this information.

[hubertmis]

Maybe let me add a little context.
I can imagine an implementation of a device driver for an RS-485 bus driver. The device driver implementation requires sending a data frame on UART, waiting a defined time after the last character in the frame is sent, and switching GPIO (from TX to RX mode).

So the code would look like:

gpio_set_to_tx();
for (size_t i; i < sizeof(frame); i++) {
  uart_poll_out(&uart_dev, frame[i]);
}
// wait until the last character is transmitted
gpio_set_to_rx();
// start receiving a response

According to the text from uart.rst, no additional waiting after the loop is required, because uart_poll_out() blocks until the character is sent.
However, if uart_poll_out() didn't block until the character was sent, we would need another function like uart_flush() blocking until all queued characters were sent.

[nordic-krch]

Maybe we are missing something like uart_poll_out_flush that would wait until byte is sent? Allowing poll_out to return without waiting for completion speeds up printf-like functions because next byte can be prepared while previous byte is being sent so UART bandwidth is better utilized.

[kartben]

@nordic-krch can you clarify if your comment calls for a request for change or if you want to +1 to move this forward? Thanks!