From 2754f5095f943ef565210d93c10a6dd06a8939f1 Mon Sep 17 00:00:00 2001
From: robert-hh <robert@hammelrath.com>
Date: Mon, 11 Mar 2024 12:31:17 +0100
Subject: [PATCH] docs/library/machine.UART: Extend the documentation for
 UART.irq.

For more ports and trigger options, based on the state of PR #14040.

Signed-off-by: robert-hh <robert@hammelrath.com>
---
 docs/library/machine.UART.rst | 43 +++++++++++++++++++++++++++++++++--
 1 file changed, 41 insertions(+), 2 deletions(-)

diff --git a/docs/library/machine.UART.rst b/docs/library/machine.UART.rst
index 6f47eb9abb..b4123db0da 100644
--- a/docs/library/machine.UART.rst
+++ b/docs/library/machine.UART.rst
@@ -193,6 +193,10 @@ Methods
 
        - ``UART.IRQ_RXIDLE`` interrupt after receiving at least one character
          and then the RX line goes idle.
+       - ``UART.IRQ_RX`` interrupt after each received character.
+       - ``UART.TX_IDLE`` interrupt after or while the last character(s) of
+         a message are of have been sent.
+       - ``UART.BREAK`` interrupt when a break state is detected at RX
 
      - *hard* if true a hardware interrupt is used.  This reduces the delay
        between the pin change and the handler being called.  Hard interrupt
@@ -200,7 +204,39 @@ Methods
 
    Returns an irq object.
 
-   Availability: renesas-ra, stm32.
+   Due to limitations of the hardware not all trigger events are available at all ports.
+
+   .. table:: Availability of triggers
+      :align: center 
+
+      ============== ======= === ====== =====
+      Port / Trigger RX_IDLE RX  TXIDLE BREAK
+      ============== ======= === ====== =====
+      STM32            yes
+      ESP32                  yes         yes
+      RP2040           yes        yes    yes
+      MIMXRT           yes        yes
+      SAMD                   yes  yes
+      RENESAS-RA             yes
+      NRF                    yes  yes
+      CC3200                 yes
+      ============== ======= === ====== =====
+
+
+   .. note::
+     - At the RP2040 port UART.TXIDLE is only triggered when the message
+       is longer than 5 characters and the trigger happens when still 5 characters
+       are to be sent.
+
+     - At the SAMD port UART.TXIDLE is triggered while the last character is sent.
+
+     - At the RP2040 port UART.BREAK needs receiving valid characters for triggering
+       again.
+
+     - The ESP32 port does not support the option hard=True.
+
+
+   Availability: renesas-ra, stm32, esp32, rp2040, mimxrt, samd, nrf, cc3200.
 
 Constants
 ---------
@@ -213,7 +249,10 @@ Constants
     Availability: esp32, mimxrt, renesas-ra, rp2, stm32.
 
 .. data:: UART.IRQ_RXIDLE
+          UART.IRQ_RX
+          UART.IRQ_TXIDLE
+          UART.IRQ_BREAK
 
     IRQ trigger sources.
 
-    Availability: stm32.
+    Availability: renesas-ra, stm32, esp32, rp2040, mimxrt, samd, cc3200.