diff --git a/Documentation/platforms/arm/ra8m1/boards/ek-ra8m1/ek-ra8m1-board_0.webp b/Documentation/platforms/arm/ra8m1/boards/ek-ra8m1/ek-ra8m1-board_0.webp new file mode 100644 index 00000000000..6b0eb075a86 Binary files /dev/null and b/Documentation/platforms/arm/ra8m1/boards/ek-ra8m1/ek-ra8m1-board_0.webp differ diff --git a/Documentation/platforms/arm/ra8m1/boards/ek-ra8m1/index.rst b/Documentation/platforms/arm/ra8m1/boards/ek-ra8m1/index.rst new file mode 100644 index 00000000000..1c001c38563 --- /dev/null +++ b/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 +`_ 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). diff --git a/Documentation/platforms/arm/ra8m1/index.rst b/Documentation/platforms/arm/ra8m1/index.rst new file mode 100644 index 00000000000..11437e9b1c9 --- /dev/null +++ b/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/*/*