uart: update meaning of uart_irq_tx_ready return code

doc/releases/migration-guide-4.0.rst

@@ -203,6 +203,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
 =========
 

drivers/serial/serial_test.c

@@ -130,10 +130,10 @@ static void irq_tx_disable(const struct device *dev)
 static int irq_tx_ready(const struct device *dev)
 {
 	struct serial_vnd_data *data = dev->data;
-	bool ready = (ring_buf_space_get(data->written) != 0);
+	int available = ring_buf_space_get(data->written);
 
-	LOG_DBG("tx ready: %d", ready);
-	return ready;
+	LOG_DBG("tx ready: %d", available);
+	return available;
 }
 
 static void irq_callback_set(const struct device *dev, uart_irq_callback_user_data_t cb,

drivers/serial/uart_async_to_irq.c

@@ -263,8 +263,10 @@ void z_uart_async_to_irq_irq_tx_disable(const struct device *dev)
 int z_uart_async_to_irq_irq_tx_ready(const struct device *dev)
 {
 	struct uart_async_to_irq_data *data = get_data(dev);
+	bool ready = (data->flags & A2I_TX_IRQ_ENABLED) && !(data->flags & A2I_TX_BUSY);
 
-	return (data->flags & A2I_TX_IRQ_ENABLED) && !(data->flags & A2I_TX_BUSY);
+	/* async API handles arbitrary sizes */
+	return ready ? data->tx.len : 0;
 }
 
 /** Interrupt driven receiver enabling function */

drivers/serial/uart_emul.c

@@ -231,18 +231,18 @@ static int uart_emul_fifo_read(const struct device *dev, uint8_t *rx_data, int s
 
 static int uart_emul_irq_tx_ready(const struct device *dev)
 {
-	bool ready = false;
+	int available = 0;
 	struct uart_emul_data *data = dev->data;
 
 	K_SPINLOCK(&data->tx_lock) {
 		if (!data->tx_irq_en) {
 			K_SPINLOCK_BREAK;
 		}
 
-		ready = ring_buf_space_get(data->tx_rb) > 0;
+		available = ring_buf_space_get(data->tx_rb);
 	}
 
-	return ready;
+	return available;
 }
 
 static int uart_emul_irq_rx_ready(const struct device *dev)

drivers/serial/uart_nrfx_uart.c

@@ -878,10 +878,11 @@
 	 * called after the TX interrupt is requested to be disabled but before
 	 * the disabling is actually performed (in the IRQ handler).
 	 */
-	return nrf_uart_int_enable_check(uart0_addr,
-					 NRF_UART_INT_MASK_TXDRDY) &&
-	       !disable_tx_irq &&
-	       event_txdrdy_check();
+	bool ready = nrf_uart_int_enable_check(uart0_addr,
+					       NRF_UART_INT_MASK_TXDRDY) &&
+		     !disable_tx_irq &&
+		     event_txdrdy_check();
+	return ready ? 1 : 0;
 }
 
 /** Interrupt driven receiver ready function */

drivers/serial/uart_nrfx_uarte.c

@@ -1652,7 +1652,7 @@ static int uarte_nrfx_irq_tx_ready_complete(const struct device *dev)
 		data->int_driven->fifo_fill_lock = 0;
 	}
 
-	return ready;
+	return ready ? data->int_driven->tx_buff_size : 0;
 }
 
 static int uarte_nrfx_irq_rx_ready(const struct device *dev)

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.
  */

subsys/usb/device/class/cdc_acm.c

@@ -622,7 +622,7 @@ static int cdc_acm_irq_tx_ready(const struct device *dev)
 	struct cdc_acm_dev_data_t * const dev_data = dev->data;
 
 	if (dev_data->tx_irq_ena && dev_data->tx_ready) {
-		return 1;
+		return ring_buf_space_get(dev_data->tx_ringbuf);
 	}
 
 	return 0;

subsys/usb/device_next/class/usbd_cdc_acm.c

@@ -707,9 +707,7 @@ static int cdc_acm_irq_tx_ready(const struct device *dev)
 	struct cdc_acm_uart_data *const data = dev->data;
 
 	if (check_wq_ctx(dev)) {
-		if (ring_buf_space_get(data->tx_fifo.rb)) {
-			return 1;
-		}
+		return ring_buf_space_get(data->tx_fifo.rb);
 	} else {
 		LOG_WRN("Invoked by inappropriate context");
 		__ASSERT_NO_MSG(false);