uart: update meaning of uart_irq_tx_ready return code

Update the documented value range that `uart_irq_tx_ready` returns in
order to provide more information to the callers about the number of
bytes that could be writted with `uart_fifo_fill` without fragmentation.

Signed-off-by: Jordan Yates <jordan@embeint.com>

doc/releases/migration-guide-4.0.rst

@@ -208,6 +208,10 @@ Sensors
 Serial
 ======
 
+ * Users of :c:func:`uart_irq_tx_ready` now need to check for ``ret > 0`` to ensure that the FIFO
+   can accept data bytes, instead of ``ret == 1``. The function now returns a lower bound on the
+   number of bytes that can be provided to :c:func:`uart_fifo_fill` without truncation.
+
 Regulator
 =========
 

include/zephyr/drivers/uart.h

@@ -902,9 +902,9 @@ static inline void z_impl_uart_irq_tx_disable(const struct device *dev)
 }
 
 /**
- * @brief Check if UART TX buffer can accept a new char
+ * @brief Check if UART TX buffer can accept bytes
  *
- * @details Check if UART TX buffer can accept at least one character
+ * @details Check if UART TX buffer can accept more bytes
  * for transmission (i.e. uart_fifo_fill() 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
@@ -913,9 +913,11 @@ static inline void z_impl_uart_irq_tx_disable(const struct device *dev)
  *
  * @param dev UART device instance.
  *
- * @retval 1 If TX interrupt is enabled and at least one char can be
- *           written to UART.
  * @retval 0 If device is not ready to write a new byte.
+ * @retval >0 Minimum number of bytes that can be written in a single call to
+ *            @ref uart_fifo_fill. It may be possible to write more bytes, but
+ *            the actual number written must be checked in the return code from
+ *            @ref uart_fifo_fill.
  * @retval -ENOSYS If this function is not implemented.
  * @retval -ENOTSUP If API is not enabled.
  */