include: uart: Another pass on improving docstrings
1. Avoid outdated references to registers of a particular hardware
in the generic API.
2. Propagate specifications/clarifications of ISR behavior to
docstrings of more functions which guaranteed to work only in ISR.
This continues work previously done in:
38f78e80cf650133827b80cad1c6abbba13d56b5
0fdc9b5b125c60d80a368360851a50f1f03710aa
etc.
Signed-off-by: Paul Sokolovsky <paul.sokolovsky@linaro.org>
diff --git a/include/uart.h b/include/uart.h
index 36e2c02..9fb91c6 100644
--- a/include/uart.h
+++ b/include/uart.h
@@ -388,7 +388,7 @@
}
/**
- * @brief Enable RX interrupt in IER.
+ * @brief Enable RX interrupt.
*
* @param dev UART device structure.
*
@@ -407,7 +407,7 @@
}
/**
- * @brief Disable RX interrupt in IER.
+ * @brief Disable RX interrupt.
*
* @param dev UART device structure.
*
@@ -441,6 +441,7 @@
*
* @retval 1 If nothing remains to be transmitted.
* @retval 0 Otherwise.
+ * @retval -ENOTSUP if this function is not supported
*/
static inline int uart_irq_tx_complete(struct device *dev)
{
@@ -451,7 +452,7 @@
return api->irq_tx_complete(dev);
}
- return 0;
+ return -ENOTSUP;
}
/**
@@ -471,6 +472,7 @@
*
* @retval 1 If a received char is ready.
* @retval 0 Otherwise.
+ * @retval -ENOTSUP if this function is not supported
*/
static inline int uart_irq_rx_ready(struct device *dev)
{
@@ -484,7 +486,7 @@
return 0;
}
/**
- * @brief Enable error interrupt in IER.
+ * @brief Enable error interrupt.
*
* @param dev UART device structure.
*
@@ -503,7 +505,7 @@
}
/**
- * @brief Disable error interrupt in IER.
+ * @brief Disable error interrupt.
*
* @param dev UART device structure.
*
@@ -545,7 +547,23 @@
}
/**
- * @brief Update cached contents of IIR.
+ * @brief Start processing interrupts in ISR.
+ *
+ * This function should be called the first thing in the ISR. Calling
+ * uart_irq_rx_ready(), uart_irq_tx_ready(), uart_irq_tx_complete()
+ * allowed only after this.
+ *
+ * The purpose of this function is:
+ *
+ * * For devices with auto-acknowledge of interrupt status on register
+ * read to cache the value of this register (rx_ready, etc. then use
+ * this case).
+ * * For devices with explicit acknowledgement of interrupts, to ack
+ * any pending interrupts and likewise to cache the original value.
+ * * For devices with implicit acknowledgement, this function will be
+ * empty. But the ISR must perform the actions needs to ack the
+ * interrupts (usually, call uart_fifo_read() on rx_ready, and
+ * uart_fifo_fill() on tx_ready).
*
* @param dev UART device structure.
*
@@ -570,6 +588,7 @@
*
* This sets up the callback for IRQ. When an IRQ is triggered,
* the specified function will be called with specified user data.
+ * See description of uart_irq_update() for the requirements on ISR.
*
* @param dev UART device structure.
* @param cb Pointer to the callback function.
