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
 ================
 

Reply via email to