This is an automated email from the ASF dual-hosted git repository. xiaoxiang781216 pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit ba9c2143dc1b57310a0aac9e7c0a306b4d28c957 Author: Hoa Bui <[email protected]> AuthorDate: Fri Nov 20 10:38:25 2026 +0000 Documentation/arm/rzv2h: Document QSPI support Document the xSPI QSPI driver, the QSPI flash support and the nsh-xspi configuration for the Renesas RZV2H-EVK and RZV2H-RDK. Signed-off-by: Hoa Bui <[email protected]> --- .../platforms/arm/rzv2h/boards/rzv2h-evk/index.rst | 98 ++++++++++++++++++++++ .../platforms/arm/rzv2h/boards/rzv2h-rdk/index.rst | 98 ++++++++++++++++++++++ Documentation/platforms/arm/rzv2h/index.rst | 88 +++++++++++++++++++ 3 files changed, 284 insertions(+) diff --git a/Documentation/platforms/arm/rzv2h/boards/rzv2h-evk/index.rst b/Documentation/platforms/arm/rzv2h/boards/rzv2h-evk/index.rst index 49c55bc9993..2ac7e596ffc 100644 --- a/Documentation/platforms/arm/rzv2h/boards/rzv2h-evk/index.rst +++ b/Documentation/platforms/arm/rzv2h/boards/rzv2h-evk/index.rst @@ -373,6 +373,92 @@ devices in ascending hardware-channel order. Their TX and RX pin choices are board-specific and are defined by ``BOARD_SCIn_TXD_GPIO`` and ``BOARD_SCIn_RXD_GPIO`` in ``boards/arm/rzv2h/rzv2h-evk/include/board.h``. +QSPI Flash +========== + +The board port drives the xSPI controller in QSPI mode (see +:doc:`the RZV2H peripheral overview <../../index>`) to talk to a SPI NOR +flash device. There is no flash part wired into the NuttX tree for this +board; select the matching ``CONFIG_MTD_*`` driver for the part actually +fitted on the EVK before enabling ``CONFIG_RZV2H_QSPI``. + +``rzv2h_qspi_initialize()`` +(``boards/arm/rzv2h/rzv2h-evk/src/rzv2h_qspi.c``) brings up the bus, +initializes the selected MTD flash driver, and then either: + +- mounts the whole chip as a single flat LittleFS volume at ``/mnt/qspi`` + (default), or +- if ``CONFIG_MTD_PARTITION`` is enabled, splits the chip into three MTD + partitions first (see Partitioning below), and mounts LittleFS on the + remaining space only. + +Read protocol +------------- + +The default read protocol is ``1S-4S-4S``. ``1S-1S-1S``, ``1S-2S-2S``, +and ``4S-4S-4S`` also work on this board. They are selected with the +``CONFIG_RZV2H_EVK_QSPI_N25QXXX_PROTOCOL_*`` choice (see +:doc:`the RZV2H peripheral overview <../../index>`). + +This board ties ``XSPI0_DS`` to GND through a 10K resistor (R47). It +also leaves ``XSPI0_IO4``-``XSPI0_IO7`` unconnected to the flash. As a +result, the DDR protocols cannot work here: + +- Selecting ``CONFIG_RZV2H_EVK_QSPI_N25QXXX_PROTOCOL_4S4D4D`` stops the build + with an ``#error``. +- ``8D-8D-8D`` is not supported. + +Partitioning +------------ + +Enabling ``CONFIG_MTD_PARTITION`` (plus ``CONFIG_MTD_CONFIG`` or +``CONFIG_MTD_CONFIG_NVS``) makes ``rzv2h_qspi_partition()`` divide +the flash chip into three independent regions, so that firmware, +parameters, and logging cannot corrupt one another on the same chip: + +.. list-table:: + :header-rows: 1 + + * - Partition + - Size (Kconfig) + - Exposed as + - Purpose + * - Firmware image + - ``CONFIG_RZV2H_EVK_QSPI_FW_PART_SIZE`` (KiB, default 4096) + - ``/dev/mtdfw0`` (raw MTD, no filesystem) + - Fixed-offset region for a flight-stack (e.g. PX4) firmware image, + read/written directly by a bootloader/loader + * - Parameter/configuration + - ``CONFIG_RZV2H_EVK_QSPI_PARAM_PART_SIZE`` (KiB, default 256) + - ``/dev/config`` (via ``mtdconfig_register()``) + - Key/value parameter and configuration store, isolated from + filesystem I/O + * - Mission data / flight logs + - remainder of the chip + - ``/mnt/qspi`` (LittleFS) + - Ordinary files: mission data, flight logs, and (optionally) the + redirected syslog file described below + +Both partition sizes are rounded down to a multiple of the flash erase +size. If the requested firmware and parameter partitions do not fit +within the chip's erase-block count, ``rzv2h_qspi_initialize()`` +fails with an error logged via ``syslog()``. + +When ``CONFIG_MTD_PARTITION`` is disabled, none of the above applies and +the chip is used as a single flat LittleFS volume, as before. + +Persistent syslog +------------------ + +``CONFIG_RZV2H_EVK_QSPI_SYSLOG_FILE`` redirects kernel ``syslog()`` output to +a file on the mounted QSPI LittleFS volume (default path +``/mnt/qspi/syslog.txt``, set via ``CONFIG_RZV2H_EVK_QSPI_SYSLOG_FILE_PATH``) +once it is mounted, so log messages persist across resets. This requires +``CONFIG_FS_LITTLEFS`` and ``CONFIG_SYSLOG_FILE``. When +``CONFIG_MTD_PARTITION`` is enabled, this file lives in the mission-data +/ flight-log partition described above, not in the firmware or parameter +partitions. + Bring-up ======== @@ -457,3 +543,15 @@ active-low ``P0_0`` and ``P0_1`` LED outputs. The generic ``/dev/gpio1`` and ``/dev/gpio2`` interfaces are also available for individual read/write testing. Automatic OS-status LED control through ``CONFIG_ARCH_LEDS`` is not yet implemented. + +nsh-xspi +-------- + +Exercises the xSPI controller in QSPI mode (see QSPI Flash above). +Enables ``CONFIG_RZV2H_QSPI`` with an ``N25QXXX`` MTD flash driver, +mounted as a single flat LittleFS volume at ``/mnt/qspi``. Partitioning +(``CONFIG_MTD_PARTITION``) and syslog redirection +(``CONFIG_RZV2H_EVK_QSPI_SYSLOG_FILE``) are optional features (see above) not +enabled by this defconfig. As with the other configurations, there is no +working console driver yet, so this is intended for bring-up validation +with a debugger. diff --git a/Documentation/platforms/arm/rzv2h/boards/rzv2h-rdk/index.rst b/Documentation/platforms/arm/rzv2h/boards/rzv2h-rdk/index.rst index ae44216091a..42c042b33b1 100644 --- a/Documentation/platforms/arm/rzv2h/boards/rzv2h-rdk/index.rst +++ b/Documentation/platforms/arm/rzv2h/boards/rzv2h-rdk/index.rst @@ -259,6 +259,92 @@ devices in ascending hardware-channel order. Their TX and RX pin choices are board-specific and are defined by ``BOARD_SCIn_TXD_GPIO`` and ``BOARD_SCIn_RXD_GPIO`` in ``boards/arm/rzv2h/rzv2h-rdk/include/board.h``. +QSPI Flash +========== + +The board port drives the xSPI controller in QSPI mode (see +:doc:`the RZV2H peripheral overview <../../index>`) to talk to a SPI NOR +flash device. There is no flash part wired into the NuttX tree for this +board; select the matching ``CONFIG_MTD_*`` driver for the part actually +fitted on the RDK before enabling ``CONFIG_RZV2H_QSPI``. + +``rzv2h_qspi_initialize()`` +(``boards/arm/rzv2h/rzv2h-rdk/src/rzv2h_qspi.c``) brings up the bus, +initializes the selected MTD flash driver, and then either: + +- mounts the whole chip as a single flat LittleFS volume at ``/mnt/qspi`` + (default), or +- if ``CONFIG_MTD_PARTITION`` is enabled, splits the chip into three MTD + partitions first (see Partitioning below), and mounts LittleFS on the + remaining space only. + +Read protocol +------------- + +The default read protocol is ``1S-4S-4S``. ``1S-1S-1S``, ``1S-2S-2S``, +and ``4S-4S-4S`` also work on this board. They are selected with the +``CONFIG_RZV2H_RDK_QSPI_N25QXXX_PROTOCOL_*`` choice (see +:doc:`the RZV2H peripheral overview <../../index>`). + +This board ties ``XSPI0_DS`` to GND through a 10K resistor (R47). It +also leaves ``XSPI0_IO4``-``XSPI0_IO7`` unconnected to the flash. As a +result, the DDR protocols cannot work here: + +- Selecting ``CONFIG_RZV2H_RDK_QSPI_N25QXXX_PROTOCOL_4S4D4D`` stops the build + with an ``#error``. +- ``8D-8D-8D`` is not supported. + +Partitioning +------------ + +Enabling ``CONFIG_MTD_PARTITION`` (plus ``CONFIG_MTD_CONFIG`` or +``CONFIG_MTD_CONFIG_NVS``) makes ``rzv2h_qspi_partition()`` divide +the flash chip into three independent regions, so that firmware, +parameters, and logging cannot corrupt one another on the same chip: + +.. list-table:: + :header-rows: 1 + + * - Partition + - Size (Kconfig) + - Exposed as + - Purpose + * - Firmware image + - ``CONFIG_RZV2H_RDK_QSPI_FW_PART_SIZE`` (KiB, default 4096) + - ``/dev/mtdfw0`` (raw MTD, no filesystem) + - Fixed-offset region for a flight-stack (e.g. PX4) firmware image, + read/written directly by a bootloader/loader + * - Parameter/configuration + - ``CONFIG_RZV2H_RDK_QSPI_PARAM_PART_SIZE`` (KiB, default 256) + - ``/dev/config`` (via ``mtdconfig_register()``) + - Key/value parameter and configuration store, isolated from + filesystem I/O + * - Mission data / flight logs + - remainder of the chip + - ``/mnt/qspi`` (LittleFS) + - Ordinary files: mission data, flight logs, and (optionally) the + redirected syslog file described below + +Both partition sizes are rounded down to a multiple of the flash erase +size. If the requested firmware and parameter partitions do not fit +within the chip's erase-block count, ``rzv2h_qspi_initialize()`` +fails with an error logged via ``syslog()``. + +When ``CONFIG_MTD_PARTITION`` is disabled, none of the above applies and +the chip is used as a single flat LittleFS volume, as before. + +Persistent syslog +------------------ + +``CONFIG_RZV2H_RDK_QSPI_SYSLOG_FILE`` redirects kernel ``syslog()`` output to +a file on the mounted QSPI LittleFS volume (default path +``/mnt/qspi/syslog.txt``, set via ``CONFIG_RZV2H_RDK_QSPI_SYSLOG_FILE_PATH``) +once it is mounted, so log messages persist across resets. This requires +``CONFIG_FS_LITTLEFS`` and ``CONFIG_SYSLOG_FILE``. When +``CONFIG_MTD_PARTITION`` is enabled, this file lives in the mission-data +/ flight-log partition described above, not in the firmware or parameter +partitions. + Configurations ============== @@ -278,3 +364,15 @@ and includes the standard NuttX ``leds`` example. Run ``leds`` to cycle the active-low ``P11_4`` and ``P11_5`` LED outputs. The generic ``/dev/gpio0``, ``/dev/gpio1``, and ``/dev/gpio2`` interfaces are also available for individual read/write testing. + +nsh-xspi +-------- + +Exercises the xSPI controller in QSPI mode (see QSPI Flash above). +Enables ``CONFIG_RZV2H_QSPI`` with an ``N25QXXX`` MTD flash driver, +mounted as a single flat LittleFS volume at ``/mnt/qspi``. Partitioning +(``CONFIG_MTD_PARTITION``) and syslog redirection +(``CONFIG_RZV2H_RDK_QSPI_SYSLOG_FILE``) are optional features (see above) not +enabled by this defconfig. As with the other configurations, there is no +working console driver yet, so this is intended for bring-up validation +with a debugger. diff --git a/Documentation/platforms/arm/rzv2h/index.rst b/Documentation/platforms/arm/rzv2h/index.rst index 5de97bcb496..8e00be0b0c7 100644 --- a/Documentation/platforms/arm/rzv2h/index.rst +++ b/Documentation/platforms/arm/rzv2h/index.rst @@ -39,6 +39,7 @@ MPU Yes Static PMSAv7 region table (ITCM/DTCM/SRAM/code) TIMER Yes MPCore Private Timer used as the system tick source SCI Yes Interrupt-driven SCI-B asynchronous UART on channels 0-9 GPIO Yes Basic operations (config/read/write), no interrupt support +QSPI Yes xSPI controller in QSPI mode, manual-command transfers only ========== ======= ============================================================ CLOCK @@ -115,6 +116,93 @@ Module Count IRQ range (>= 353) TINT 32 (tint0-tint31) 479-448 ====== ================== ================================ +QSPI +---- + +``rzv2h_qspi.c`` implements the standard NuttX ``struct qspi_dev_s`` +interface (``arch/arm/src/rzv2h/rzv2h_qspi.c``) on top of the Renesas FSP +xSPI-QSPI HAL (``r_xspi_qspi``). It is intended to drive a SPI NOR flash +device wired to the xSPI controller, using the NuttX QSPI-based MTD flash +drivers (``n25qxxx``, ``mx25rxx``, ``w25qxxxjv``, ``gd25``, ``gd55``, +``s25fl1``). + +Commands and memory reads/writes are issued through +``R_XSPI_QSPI_DirectTransfer()`` (manual-command mode); each transaction +moves at most 8 bytes, so larger transfers are split into a sequence of +transactions by the driver. There is no XIP (execute-in-place, +memory-mapped) support and no DMA: all data moves through the CPU, so +throughput is limited compared to a memory-mapped or DMA-driven transfer. + +Protocol support +^^^^^^^^^^^^^^^^ + +The ``n25qxxx`` MTD driver always requests Quad I/O Fast Read (``0xEB``). +``rzv2h_qspi_memory()`` sends that read on the wire in whichever protocol +is selected by the ``CONFIG_RZV2H_<BOARD>_QSPI_N25QXXX_PROTOCOL_*`` choice +(``<BOARD>`` is ``EVK`` or ``RDK``). +Program, erase, and status/configuration-register commands always use +``1S-1S-1S``, whatever read protocol is selected. + +.. list-table:: + :header-rows: 1 + + * - Protocol + - Kconfig option + - Read command + - Status + * - ``1S-1S-1S`` + - ``CONFIG_RZV2H_<BOARD>_QSPI_N25QXXX_PROTOCOL_1S1S1S`` + - READ (``0x03``) + - Supported + * - ``1S-2S-2S`` + - ``CONFIG_RZV2H_<BOARD>_QSPI_N25QXXX_PROTOCOL_1S2S2S`` + - Dual I/O Fast Read (``0xBB``) + - Supported + * - ``1S-4S-4S`` + - ``CONFIG_RZV2H_<BOARD>_QSPI_N25QXXX_PROTOCOL_1S4S4S`` + - Quad I/O Fast Read (``0xEB``) + - Supported (**default**) + * - ``4S-4S-4S`` + - ``CONFIG_RZV2H_<BOARD>_QSPI_N25QXXX_PROTOCOL_4S4S4S`` + - FAST READ (``0x0B``) in persistent Quad SPI mode (``0x35``/``0xF5``) + - Supported + * - ``4S-4D-4D`` + - ``CONFIG_RZV2H_<BOARD>_QSPI_N25QXXX_PROTOCOL_4S4D4D`` + - DTR FAST READ (``0x0D``) in persistent Quad SPI mode + - Needs a board that connects ``XSPI0_DS`` to the flash (see below) + * - ``8D-8D-8D`` + - none + - none + - Not supported + +``2S-2S-2S`` has no Kconfig read option. The driver still sends it for +commands that set the dual-instruction flags (``QSPICMD_IDUAL`` or +``QSPIMEM_IDUAL``). + +DDR protocols (``4S-4D-4D`` and ``8D-8D-8D``) sample read data with the +``XSPI0_DS`` strobe. The hardware manual states: "DDR access without +XSPI0_DS is not supported". A board must connect ``XSPI0_DS`` to a flash +that drives it before ``4S-4D-4D`` can work. + +``8D-8D-8D`` is not supported for four reasons: + +- The FSP xSPI-QSPI HAL rejects it: ``R_XSPI_QSPI_SpiProtocolSet()`` + returns ``FSP_ERR_INVALID_ARGUMENT``. The ``SOPI`` and ``DOPI`` modes + are rejected the same way. +- It needs ``XSPI0_IO4``-``XSPI0_IO7`` and ``XSPI0_DS`` connected to an + octal flash. +- The Quad SPI NOR flash on the RZV2H boards has only 4 data lines. +- The generic NuttX QSPI interface (``include/nuttx/spi/qspi.h``) has no + flags for octal or DDR transfers. + +The xSPI serial clock is derived from a dedicated CPG divider that only +feeds this peripheral (four ratios: source clock divided by 2, 4, 8, or +16); ``rzv2h_qspi_setfrequency()`` picks the closest ratio that does not +exceed the requested frequency. + +See :doc:`the RZV2H-EVK board documentation <boards/rzv2h-evk/index>` for +board-level bring-up, partitioning, and configuration details. + Supported Boards ================
