Documentation/arm/ra8m1: Add Renesas RA8M1 documentation

Add platform and EK-RA8M1 board documentation.

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

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

@@ -0,0 +1,167 @@
+========
+EK-RA8M1
+========
+
+This is a port of NuttX to the Renesas EK-RA8M1 evaluation kit, featuring
+the R7FA8M1AHECBD (BGA224) MCU: an Arm Cortex-M85 running at up to
+480 MHz, with 2016 KiB of code flash, 896 KiB of SRAM and 12 KiB of data
+flash.
+
+.. figure:: ek-ra8m1-board_0.webp
+   :scale: 50 %
+   :align: center
+
+See the `Renesas website
+<https://www.renesas.com/en/design-resources/boards-kits/ek-ra8m1>`_ for
+information about the EK-RA8M1.
+
+Flat, no-TrustZone image
+=========================
+
+This port does not use TrustZone: it is a flat image that always runs in
+the secure state, and it uses the secure memory and register aliases
+throughout (RA8M1 User's Manual Table 4.1) -- code flash at ``0x0200_0000``,
+SRAM at ``0x2200_0000``, data flash at ``0x2700_0000``.  The non-secure
+aliases (``0x12xx_xxxx``/``0x32xx_xxxx``/``0x37xx_xxxx``) are not used.
+
+The EK-RA8M1 ships with the TrustZone security partition set to the
+Renesas FSP sample project's boundary.  A flat
+NuttX image needs the whole flash marked secure instead, which has to be
+set once with the flash programmer before the first NuttX image is
+written (see `Loading Code`_ below).
+
+Clocking
+========
+
+``include/board.h`` configures this clock tree from the EK-RA8M1's 20 MHz
+resonator (see ``arch/arm/src/ra8m1/ra_clockconfig.h`` for how every
+option is derived and validated):
+
+============  =========================================  ==========
+Clock         Source                                      Frequency
+============  =========================================  ==========
+MOSC          20 MHz resonator on EXTAL/XTAL              20 MHz
+PLL1          MOSC / 2, x96                                960 MHz VCO
+CPUCLK        PLL1 output P / 1                            480 MHz
+ICLK          PLL1 output P / 2                            240 MHz
+PCLKA         PLL1 output P / 4                            120 MHz
+PCLKB         PLL1 output P / 8                             60 MHz
+PCLKC         PLL1 output P / 8                             60 MHz
+PCLKD         PLL1 output P / 4                            120 MHz
+PCLKE         PLL1 output P / 2                            240 MHz
+FCLK          PLL1 output P / 8                             60 MHz
+BCLK          PLL1 output P / 4                            120 MHz
+SCICLK        PLL1 output Q / 4                            120 MHz
+============  =========================================  ==========
+
+SCICLK feeds the baud rate generator of every SCI UART; it is only
+configured (and its PLL only started) when at least one ``CONFIG_RA_SCIn_UART``
+is enabled.  120 MHz was chosen because it gives 115200 baud with 0.16 %
+error (the reset default, the 8 MHz MOCO, gives 3.5 % error).
+
+Buttons and LEDs
+================
+
+Buttons
+-------
+
+No push-buttons are wired into this port.
+
+LEDs
+----
+
+The EK-RA8M1 has three user LEDs:
+
+    ====  ====  ======
+    LED   GPIO  Colour
+    ====  ====  ======
+    LED1  P600  Blue
+    LED2  P414  Green
+    LED3  P107  Red
+    ====  ====  ======
+
+They are driven active-high in this port (``ra8m1_userleds.c``,
+``ra8m1_autoleds.c``); this has not been confirmed on hardware, so if a
+board turns out to be wired the other way, invert the levels there.
+
+These LEDs are not used by the board port unless ``CONFIG_ARCH_LEDS`` is
+defined.  In that case, the usage is defined in ``include/board.h`` and
+``src/ra8m1_autoleds.c``:
+
+    ==================  =========================  ======  ======  ======
+    SYMBOL              MEANING                     LED1    LED2    LED3
+    ==================  =========================  ======  ======  ======
+    LED_STARTED         NuttX has been started      OFF     OFF     OFF
+    LED_HEAPALLOCATE    Heap has been allocated     OFF     OFF     OFF
+    LED_IRQSENABLED     Interrupts enabled          OFF     OFF     OFF
+    LED_STACKCREATED    Idle stack created          ON      OFF     OFF
+    LED_INIRQ           In an interrupt             N/C     ON      N/C
+    LED_SIGNAL          In a signal handler         N/C     ON      N/C
+    LED_ASSERTION       An assertion failed         N/C     ON      N/C
+    LED_PANIC           The system has crashed      N/C     N/C     ON
+    ==================  =========================  ======  ======  ======
+
+Without ``CONFIG_ARCH_LEDS``, the LEDs are available through the
+``userled`` upper half at ``/dev/userleds`` (bit 0 = LED1, bit 1 = LED2,
+bit 2 = LED3), or individually through the ``ULEDIOC_SETLED`` ioctl.
+
+Serial Console
+===============
+
+The EK-RA8M1's on-board debugger (a J-Link) provides a virtual COM port on
+SCI9:
+
+    ==================   ============
+    Signal               R7FA8M1AHECBD
+    ==================   ============
+    TXD9                 PA14
+    RXD9                 PA15
+    ==================   ============
+
+SCI9 is the serial console in the default configurations, at 115200 8N1.
+
+Loading Code
+============
+
+This port produces a flat image (no TrustZone), so it is flashed with
+``rfp-cli`` (the Renesas Flash Programmer CLI), through the on-board
+J-Link, over SWD:
+
+.. code-block:: bash
+
+    rfp-cli -device ra --tool jlink -if swd -p ./build/nuttx.hex
+
+*Note:* the image must be flashed as ELF, HEX or SREC, not as a raw
+binary: the option-setting words (OFS0/OFS1/OFS2, see
+``ra_option_setting.c``) sit in flash option memory well above the code
+flash region, and a raw ``objcopy`` binary would not carry them.
+
+*Note:* a board fresh from the factory, or last flashed with the Renesas
+some project, has the TrustZone boundary set to that project's
+partition, which might too small for this flat
+image and makes ``rfp-cli`` fail to erase/program with an address error.
+Set the whole flash and SRAM to secure once, before the first NuttX
+flash:
+
+.. code-block:: bash
+
+    rfp-cli -d ra -t jlink -if swd -erase-chip
+
+This is a persistent, one-time device setting; it does not need to be
+repeated on later flashes of a NuttX image.
+
+Configurations
+==============
+
+nsh
+---
+
+Configures the NuttX Shell (nsh) with the serial console on SCI9, plus
+the ``ostest`` test suite.
+
+nsh-leds
+--------
+
+Same as ``nsh``, but without ``ostest``, and enables the ``userled``
+driver on ``/dev/userleds`` (``CONFIG_ARCH_LEDS`` is not set, so NuttX
+does not drive the LEDs itself; see `LEDs`_ above).

Documentation/platforms/arm/ra8m1/index.rst

@@ -0,0 +1,113 @@
+=============
+Renesas RA8M1
+=============
+
+The RA8M1 is a Renesas RA family MCU built around an Arm Cortex-M85 core
+(Armv8.1-M, Helium/MVE, running at up to 480 MHz), with TrustZone for
+Armv8-M support in hardware.  This NuttX port is a flat, no-TrustZone
+image: it always runs in the secure state and uses the secure memory and
+register aliases (see the flat/secure model note in the port's board
+documentation).
+
+Supported MCUs
+==============
+
+The following list includes MCUs from the RA8M1 series and indicates
+whether they are supported in NuttX.  Only R7FA8M1AHECBD (BGA224, on the
+EK-RA8M1) has been tested; the others are selectable but untested.
+
+=============  ======= ================
+MCU            Support Note
+=============  ======= ================
+R7FA8M1AFECAM  No      Selectable, untested
+R7FA8M1AFECBD  No      Selectable, untested
+R7FA8M1AFECFB  No      Selectable, untested
+R7FA8M1AFECFC  No      Selectable, untested
+R7FA8M1AFECFP  No      Selectable, untested
+R7FA8M1AHECAM  No      Selectable, untested
+R7FA8M1AHECBD  Yes     Tested on the EK-RA8M1
+R7FA8M1AHECFB  No      Selectable, untested
+R7FA8M1AHECFC  No      Selectable, untested
+R7FA8M1AHECFP  No      Selectable, untested
+=============  ======= ================
+
+Peripheral Support
+==================
+
+The following list indicates peripherals supported in NuttX:
+
+==========  =======  =====================================
+Peripheral  Support  Notes
+==========  =======  =====================================
+FLASH       No
+CLOCK       Yes      MOCO, HOCO, MOSC, PLL1, PLL2, SCICLK
+ICU         Yes
+KINT        No
+ELC         No
+DTC         No
+DMAC        No
+GPT         No
+AGT         No
+RTC         No
+WDT         No
+IWDT        No
+SCI         Yes      Just UART (SCI_B0-4, SCI_B9)
+IIC         No
+SPI         No
+SSIE        No
+QSPI        No
+SDHI        No
+CAN         No
+USBFS       No
+ADC12       No
+DAC12       No
+ACMPLP      No
+OPAMP       No
+CRC         No
+GPIO        Yes
+==========  =======  =====================================
+
+CLOCK
+-----
+
+The board's ``include/board.h`` defines ``BOARD_*`` macros that select the clock
+sources, PLL settings and dividers, and ``arch/arm/src/ra8m1/ra_clockconfig.h``
+derives every clock frequency from them and checks it against the limits in
+the RA8M1 User's Manual (chapter 8) at build time.  See the board's own
+documentation for the specific clock tree it configures.
+
+The RA8M1 has two PLLs.  PLL1 can feed the system clock or a peripheral
+dedicated clock (SCICLK); PLL2 can only feed a dedicated clock.  SCICLK is
+enabled automatically whenever an SCI UART is enabled, since it is the
+clock of the SCI baud rate generator.
+
+SCI
+---
+
+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.
+
+GPIO
+----
+
+Pins can be configured/operated using ``ra_gpio_*`` functions.
+
+ICU
+---
+
+The Interrupt Controller Unit routes peripheral events to NVIC vectors:
+any event can be routed to any of its IELSR slots.  NuttX assigns SCI_B
+events to fixed slots (four per channel) and calls ``ra_attach_icu()`` at
+start-up to route the enabled channels' events into them.
+
+Supported Boards
+=================
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   boards/*/*