softperipheral: rev b6bcb2e1b351cdad4c88b2aad4cfc4d739b0dbeb

CHANGELOG.rst contains the list of changes.

Signed-off-by: Luis David Lopez <[email protected]>

Author: lopeztel

softperipheral/CHANGELOG.rst

@@ -16,9 +16,13 @@ This is a release that focuses on improving existing soft peripherals.
 See the following list of changes:
 
 
+* Added:
+
+  * Position Independent Code (PIC) for all Soft Peripheral binaries.
+
 * Bug fixes:
 
-  * Fixed higher frequency transfers for Soft Peripheral sQSPI for the nRF54L15 and nRF54H20 SoCs.
+  * Fixed higher frequency transfers for Soft Peripheral sQSPI for the nRF54L15 SoC.
     For details, see the :ref:`sqspi_changelog` page.
 
 nRF Connect SDK v3.0.0

softperipheral/doc/introduction.rst

@@ -46,5 +46,7 @@ The following table shows which soft peripherals and their versions are supporte
      - - nRF54L15 SoC:
           - v0.1.0 with NCS v3.0.0
           - v1.0.0 with NCS v3.1.0
+          - v1.1.0 with NCS v3.1.0
        - nRF54H20 SoC:
           - v0.1.0 with NCS v3.0.0
+          - v1.1.0 with NCS v3.1.0

softperipheral/doc/sQSPI/CHANGELOG.rst

@@ -9,6 +9,16 @@ sQSPI changelog
 
 All the notable changes to sQSPI are documented on this page.
 
+v1.1.0
+******
+
+See the list of changes for the current release.
+
+* Added:
+
+  * Fixes on API communication layer for nRF54L15 devices.
+  * Fixes for a booting bug and on API communication layer for nRF54H20 devices.
+
 v1.0.0
 ******
 

softperipheral/doc/sQSPI/README.rst

@@ -61,9 +61,10 @@ To better understand the capabilities and limitations of sQSPI, see its comparis
    :caption: Subpages:
 
    features.rst
-   nrf54L15_porting_v1_0_0.rst
-   nrf54H20_porting_v1_0_0.rst
+   nrf54L15_porting_v1_1_0.rst
+   nrf54H20_porting_v1_1_0.rst
+   display.rst
    timing.rst
    CHANGELOG.rst
    limitations.rst
-   api_reference_v1_0_0.rst
+   api_reference.rst

softperipheral/doc/sQSPI/api_reference_v1_0_0.rst renamed to softperipheral/doc/sQSPI/api_reference.rst

@@ -0,0 +1,40 @@
+.. _sqspi_display:
+
+sQSPI and display usage
+#######################
+
+The sQSPI API provides the data format interface for use with external displays.
+See :c:struct:`nrf_sqspi_data_fmt_t`.
+
+The following parameter combinations have been tested and are considered production ready:
+
+.. list-table:: sQSPI data format
+   :widths: auto
+   :header-rows: 1
+
+   * - :c:var:`nrf_sqspi_data_fmt_t.data_padding`
+     - :c:var:`nrf_sqspi_data_fmt_t.data_container`
+     - :c:var:`nrf_sqspi_data_fmt_t.data_swap_unit`
+   * - 0
+     - 8
+     - 8
+   * - 0
+     - 8
+     - 0
+   * - 16
+     - 16
+     - 8
+   * - 0
+     - 32
+     - 16
+
+Using external sync bit (tearing effect)
+****************************************
+
+sQSPI v1.1.0 can be used alongside some application level processing to send a transfer when a pulse (tearing effect) is detected by either:
+
+* Polling a GPIO pin.
+* Setting an interrupt handler to an event linked to a specific GPIO pin (access to peripheral ``GPIOTE`` is required for this).
+* Forwarding a GPIO event through DPPI towards a FLPR task linked to starting a transfer (access to peripheral ``DPPIC`` is required for this, also see :file:`softperipheral/include/softperipheral_regif.h` for the specific task).
+
+You can use the first two options by holding a transfer and starting it when the pulse is detected (using flag ``NRF_SQSPI_FLAG_HOLD_XFER`` in :c:func:`nrf_sqspi_xfer`).

softperipheral/doc/sQSPI/display.rst

@@ -9,20 +9,36 @@ When working with sQSPI, you should be aware of the following limitations.
    :local:
    :depth: 2
 
-v1.0.0
+v1.1.0
 ******
 
 Refer to the following detailed descriptions of current limitations:
 
 * sQSPI does not support slave mode operations; it can only operate as a controller (master).
 * The sQSPI support for SPI half-duplex setup is implemented but not tested.
-* sQSPI SPI modes 1,2, and 3 (see the :c:var:`nrf_sqspi_dev_cfg_t.spi_cpolpha` configuration structure) may present artifacts (delays and clock stretching) on the last SCLK cycle during a transfer.
+* sQSPI SPI modes 1,2, and 3 (see the :c:var:`nrf_sqspi_dev_cfg_t.spi_cpolpha` configuration structure) may present artifacts (clock stretching or extra edges) on the last SCLK cycle during a read.
+  This has no effect on data integrity.
 * The nrfx API for sQSPI does not support configuring the use of the positive or negative edge of SCLK delayed read sampling.
 * sQSPI employs the :c:var:`nrf_sqspi_dev_cfg_t.sample_delay_cyc` parameter as an offset to FLPR's base clock counter , not SLCK clock cycles (see the :c:struct:`nrf_sqspi_dev_cfg_t` struct).
-* sQSPI :c:var:`nrf_sqspi_dev_cfg_t.sample_delay_cyc` has a limit:
-
-  .. math::
-     nrf\_sqspi\_dev\_cfg\_t.sample\_delay\_cyc <= \frac{FLPR_{base\_freq}}{2*nrf\_sqspi\_dev\_cfg\_t.sck\_freq\_khz} - 1
-
+* sQSPI :c:var:`nrf_sqspi_dev_cfg_t.sample_delay_cyc` is constrained to either a value of ``0`` if using ``GPIOHSPADCTRL`` for high-speed transfers (see :ref:`nrf54L15_porting_guide_high_speed_transfers`) or a value greater than ``0`` but lower than that of ``FLPR_counter`` if a high-speed transfer is not needed (see :ref:`sqspi_timing`).
 * Implementation of sQSPI quad or dual lane for command transmission (for example, ``2_2_2`` and ``4_4_4`` modes) is implemented but has not been tested.
 * sQSPI does not support a configurable pin for the CSN line; only **PIN 5** is supported (see :c:var:`nrf_sqspi_dev_cfg_t.csn_pin`).
+* :c:var:`nrf_sqspi_xfer_t.p_data` needs to be a pointer with a 32-bit aligned address.
+* sQSPI high-speed reading cannot happen directly when changing from SPI mode 0 to 3.
+  Either do a high-speed write or a slow read (5.8 MHz) in between.
+* :c:var:`nrf_sqspi_xfer_t.addr_length` must be greater than :c:var:`nrf_sqspi_dev_cfg_t.mspi_lines`.
+
+* sQSPI will present undefined behavior in the following cases:
+
+   * 0 byte reads: :c:var:`nrf_sqspi_xfer_t.dir` set to ``NRF_SQSPI_XFER_DIR_RX`` and :c:var:`nrf_sqspi_xfer_t.data_length` set to ``0``.
+   * 0 command bits: :c:var:`nrf_sqspi_xfer_t.cmd_length` set to ``0``.
+   * 0 address bits: :c:var:`nrf_sqspi_xfer_t.addr_length` set to ``0``.
+
+Data format (display use) limitations:
+
+* :c:var:`nrf_sqspi_data_fmt_t.data_bit_reorder_unit` must be set to the same value as :c:var:`nrf_sqspi_data_fmt_t.data_swap_unit`.
+* If :c:var:`nrf_sqspi_data_fmt_t.data_padding` is not set to ``0`` - Sum of :c:var:`nrf_sqspi_data_fmt_t.data_container` and :c:var:`nrf_sqspi_data_fmt_t.data_padding` must be equal to ``32``.
+* Combination of :c:var:`nrf_sqspi_data_fmt_t.data_padding` equal to ``24`` and :c:var:`nrf_sqspi_data_fmt_t.data_swap_unit` equal to ``8``, when ``clkdiv`` is equal to or less than ``6`` (see :ref:`sqspi_timing`) and :c:var:`nrf_sqspi_dev_cfg_t.mspi_lines` is ``NRF_SQSPI_SPI_LINES_DUAL_X_Y_2`` or ``NRF_SQSPI_SPI_LINES_QUAD_X_Y_4``, leads to the wrong frequency on SCLK.
+* The value calculated as: ``32`` - :c:var:`nrf_sqspi_data_fmt_t.data_padding` must be a multiple of :c:var:`nrf_sqspi_data_fmt_t.data_swap_unit`.
+* :c:var:`nrf_sqspi_data_fmt_t.data_swap_unit` values ``0`` and ``4`` are not supported.
+* :c:var:`nrf_sqspi_data_fmt_t.data_bit_order` and :c:var:`nrf_sqspi_data_fmt_t.addr_bit_order` do not support the value: ``NRF_SQSPI_DATA_FMT_BIT_ORDER_LSB_FIRST``.

softperipheral/doc/sQSPI/limitations.rst

@@ -31,13 +31,13 @@ This structure shows the relevant files and directories in the `sdk-nrfxlib`_ re
           │   │   └── nrf_qspi2.h
           │   ├── nrf54h20
           │   │   ├── sqspi_firmware.h
-          │   │   ├── sqspi_firmware_v1.0.0.h
+          │   │   ├── sqspi_firmware_v1.1.0.h
           │   │   └── ...
           │   ├── nrf_config_sqspi.h
           │   ├── nrf_sp_qspi.h
           │   ├── nrf_sqspi.h
           └── src
-              └── nrfx_qspi2.c
+              └── nrf_sqspi.c
 
 .. note::
    The main interface for sQSPI is the :file:`nrf_sqspi.h` file.

softperipheral/doc/sQSPI/nrf54H20_porting_v1_0_0.rst renamed to softperipheral/doc/sQSPI/nrf54H20_porting_v1_1_0.rst

@@ -31,7 +31,7 @@ This structure shows the relevant files and directories in the `sdk-nrfxlib`_ re
           │   │   └── nrf_qspi2.h
           │   ├── nrf54l15
           │   │   ├── sqspi_firmware.h
-          │   │   └── sqspi_firmware_v1.0.0.h
+          │   │   └── sqspi_firmware_v1.1.0.h
           │   │   └── ...
           │   ├── nrf_config_sqspi.h
           │   ├── nrf_sp_qspi.h
@@ -228,11 +228,13 @@ The following code snippet shows how the application code can allocate the requi
        }
    }
 
+.. _nrf54L15_porting_guide_high_speed_transfers:
+
 High speed transfers
 ====================
 
 .. warning::
-   High speed transfers (above 32MHz) on NRF54L15 DK are only supported in sQSPI 1.0.0.
+   High speed transfers (above 32 MHz) on the NRF54L15 DK are only supported starting from sQSPI v1.0.0.
 
 A high speed transfer sQSPI application requires both extra high drive strength and access to the peripheral ``GPIOHSPADCTRL`` (GPIO High Speed Pad Control).
 The following settings must be changed for ``GPIOHSPADCTRL.BIAS`` and ``GPIOHSPADCTRL.CTRL``:
@@ -412,23 +414,22 @@ The following code snippet shows how the application code can enable and disable
    }
 
 .. warning::
-   High speed transfers are closely tied to API parameter :c:var:`nrf_sqspi_dev_cfg_t.sample_delay_cyc`, which is constrained by the following conditions:
-   **TODO**
+   High speed transfers are closely tied to API the parameter :c:var:`nrf_sqspi_dev_cfg_t.sample_delay_cyc`, which needs to be set to ``0`` (see :ref:`sqspi_limitations`).
 
 Memory retention configuration
 ******************************
 
-The sQSPI soft peripheral requires RAM retention in order to go into the lowest power consumption mode, which can be called through the :c:func:`nrfx_qspi2_deactivate` API.
+The sQSPI soft peripheral requires RAM retention in order to go into the lowest power consumption mode, which can be called through the :c:func:`nrf_sqspi_deactivate` function.
 
 Assuming there is an access to the peripheral `MEMCONF`, the following code snippet illustrates how to enable FLPR RAM retention, followed by deactivation and reactivation, and finally how to disable RAM retention:
 
  .. code-block:: c
 
     //Deactivate sequence
     nrf_memconf_ramblock_ret_enable_set(NRF_MEMCONF, 1, MEMCONF_POWER_RET_MEM0_Pos, true);
-    nrfx_qspi2_deactivate(&m_qspi);
+    nrf_sqspi_deactivate(&m_qspi);
     //activate sequence
-    nrfx_qspi2_activate(&m_qspi);
+    nrf_qspi_activate(&m_qspi);
     nrf_memconf_ramblock_ret_enable_set(NRF_MEMCONF, 1, MEMCONF_POWER_RET_MEM0_Pos, false);
 
 .. _nrf54L15_porting_guide_ram_configuration:

softperipheral/doc/sQSPI/nrf54L15_porting_v1_0_0.rst renamed to softperipheral/doc/sQSPI/nrf54L15_porting_v1_1_0.rst

@@ -1,5 +1,28 @@
 .. _sqspi_timing:
 
+sQSPI and FLPR counters
+#######################
+
+The sQSPI API translates the parameter :c:var:`nrf_sqspi_dev_cfg_t.sck_freq_khz` into a value that can be used by FLPR's internal counters.
+The translation has the following constraints (assuming the SoC is running at highest base clock frequency):
+
+.. tabs::
+
+   .. tab:: **nRF54L15**
+      .. math::
+         clkdiv=\frac{128000000}{1000 * nrf\_sqspi\_dev\_cfg\_t.sck\_freq\_khz}
+
+   .. tab:: **nRF54H20**
+      .. math::
+         clkdiv=\frac{320000000}{1000 * nrf\_sqspi\_dev\_cfg\_t.sck\_freq\_khz}
+
+.. math::
+  FLPR\_counter=
+  \begin{cases}
+      \frac{clkdiv}{2}-1,& \text{if } clkdiv > 2\\
+      0,              & \text{otherwise}
+  \end{cases}
+
 Timing parameters
 #################