Documentation/arm/ra8m1: Document DTC, SCI FIFO/DTC/termios support

Marks DTC as supported in the peripheral table (normal mode only, used
by SCI) and documents the SCI driver features: the per-instance
FIFO/DTC mutual exclusion and the measured overrun-margin trade-off
between them, termios TCGETS/TCSETS support (tested up to 2 Mbps), and
TIOCGICOUNT's frame/overrun/parity counters.  Adds SCI0's pinout and
the new serial-test config to the EK-RA8M1 board page.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Assisted-by: Claude:claude-sonnet-5
Signed-off-by: leocafonso <leocafonso@gmail.com>

Documentation/platforms/arm/ra8m1/boards/ek-ra8m1/index.rst

@@ -155,6 +155,18 @@ SCI9:
 
 SCI9 is the serial console in the default configurations, at 115200 8N1.
 
+SCI0 is also wired out on this board, for use as a second UART
+(``CONFIG_RA_SCI0_UART``) independent of the console:
+
+    ==================   ============
+    Signal               R7FA8M1AHECBD
+    ==================   ============
+    TXD0                 P609
+    RXD0                 P610
+    ==================   ============
+
+Tested with an external USB-serial adapter.
+
 Timers
 ======
 
@@ -235,3 +247,29 @@ Same as ``nsh``, but registers GPT0 and GPT9 as ``/dev/timer0`` and
 header (see `Arduino Shield GPIO`_ above), and builds in
 ``apps/examples/gpio`` and ``apps/examples/timer_gpio`` (see `Timers`_
 above).
+
+serial-test
+-----------
+
+Same as ``nsh``, but also enables SCI0 as ``/dev/ttyS1`` (see `Serial
+Console`_ above) with its FIFO (``CONFIG_RA_SCI0_FIFO``, TTRG=15/
+RTRG=0 -- the best overrun-resistant setting measured on hardware) and
+1024-byte RX/TX buffers, ``CONFIG_SERIAL_TERMIOS`` and
+``apps/system/stty``, and builds in ``apps/examples/serialblaster``
+and ``apps/examples/serialrx``, both pointed at ``/dev/ttyS1``, for
+exercising SCI0 at a range of baud rates independent of the console.
+
+To test, with an external loopback wired across SCI0's TX/RX pins
+(see `Serial Console`_ above for the pinout):
+
+.. code-block:: console
+
+    nsh> stty -F /dev/ttyS1 speed 3000000
+    nsh> serialrx /dev/ttyS1 1000 &
+    nsh> serialblaster /dev/ttyS1 1000
+
+Keep the byte count at or below the 1024-byte RX buffer.
+``serialrx`` prints every received byte to the (115200) console as it
+reads, far slower than a multi-Mbps port fills the buffer; a transfer
+longer than the buffer overflows it in software, in the generic
+NuttX serial core, well before SCI0's own FIFO is the limiting factor.

Documentation/platforms/arm/ra8m1/index.rst

@@ -44,14 +44,14 @@ CLOCK       Yes      MOCO, HOCO, MOSC, PLL1, PLL2, SCICLK
 ICU         Yes
 KINT        No
 ELC         No
-DTC         No
+DTC         Yes      Used by SCI (see SCI below); normal mode only
 DMAC        No
 GPT         Yes      Timer only: /dev/timerN (GPT0-7 32-bit, GPT8-13 16-bit)
 AGT         No
 RTC         No
 WDT         No
 IWDT        No
-SCI         Yes      Just UART (SCI_B0-4, SCI_B9)
+SCI         Yes      UART only (SCI_B0-4, SCI_B9); FIFO, DTC, termios
 IIC         No
 SPI         No
 SSIE        No
@@ -88,7 +88,39 @@ The Serial Communications Interface, Type B (SCI_B) is configurable to
 support several serial communication modes: Asynchronous (UART), Clock
 synchronous, Simple SPI, Smart card interface, Simple IIC (master-only).
 NuttX driver support covers UART mode.  RA8M1 has SCI_B0-4 and SCI_B9 (no
-SCI_B5-8); each channel's baud rate generator runs from SCICLK.
+SCI_B5-8); each channel's baud rate generator runs from SCICLK.  Each
+instance is enabled with its own ``CONFIG_RA_SCIn_UART``.
+
+Each instance can independently use its 16-stage hardware FIFO or the
+DTC (see `DTC`_ below) to move data, but not both: ``CONFIG_RA_SCIn_FIFO``
+and ``CONFIG_RA_SCIn_TXDTC``/``RXDTC`` are mutually exclusive.  Measured on
+hardware, a low receive trigger level (``CONFIG_RA_SCIn_FIFO_RXTRG``) gives
+better overrun resistance at high baud rates than RX DTC does, since DTC
+only protects a byte while its single-activation transfer is actually
+armed, not continuously -- see the Kconfig help for each option for the
+detail.
+
+``CONFIG_SERIAL_TERMIOS`` enables ``TCGETS``/``TCSETS`` (baud rate, parity,
+stop bits only -- word length and the FIFO/DTC choice are fixed at build
+time).  ``apps/system/stty`` can change these live, e.g.
+``stty -F /dev/ttyS1 speed 3000000`` (FIFO with TTRG=15/RTRG=0 tested
+clean up to 3 Mbps).
+
+``CONFIG_SERIAL_TIOCGICOUNT`` exposes frame/overrun/parity counters
+through the standard ``TIOCGICOUNT`` ioctl; nothing pushes a
+notification, an application has to poll it.
+
+DTC
+---
+
+The Data Transfer Controller offloads repetitive, register-triggered
+transfers (e.g. UART TX/RX) from the CPU: the ICU event that would
+otherwise interrupt the CPU instead activates the DTC for one transfer,
+and once its count is exhausted it still interrupts the CPU normally.
+Only normal mode (one activation, one transfer) is implemented; repeat
+and block modes are not.  Enabled with ``CONFIG_RA_DTC``; peripheral
+drivers that support it expose their own per-channel options (e.g.
+``CONFIG_RA_SCI9_TXDTC``).
 
 GPIO
 ----