doc: review p2

sEMMC nRF54H porting guide
includes sQSPI small changes

Signed-off-by: Anna Wojdylo <[email protected]>

Author: annwoj

softperipheral/doc/sEMMC/semmc_nrf54H_series_porting_v0_1_0.rst

@@ -40,12 +40,13 @@ This structure shows the relevant files and directories in the `sdk-nrfxlib`_ re
               └── nrf_semmc.c
 
 .. note::
-   The main interface for sEMMC is the :file:`nrf_semmc.h` file. It contains a list of supported and tested EMMC commands.
+   The main interface for sEMMC is in the :file:`nrf_semmc.h` file.
+   It contains a list of supported and tested EMMC commands.
 
 Header files
 ============
 
-For an sEMMC application to function correctly, it requires specific header files used by the driver code.
+sEMMC application requires specific header files used by the driver code.
 You must include paths to these files in the build environment's list of include paths.
 The following list is a detailed breakdown of the necessary paths:
 
@@ -55,7 +56,7 @@ The following list is a detailed breakdown of the necessary paths:
   * :file:`softperipheral/sEMMC/include` - sEMMC register interface and driver header
   * :file:`softperipheral/sEMMC/include/nrf54h` - The sEMMC firmware for the Fast Lightweight Perpipheral Processor (FLPR)
 
-To override the configuration enums in :file:`nrf_config_semmc.h`, you can use the ``zephyr_compile_definitions`` macro in your application:
+To override the configuration enums in :file:`nrf_config_semmc.h`, use the ``zephyr_compile_definitions`` macro in your application:
 
 .. code-block:: c
 
@@ -65,18 +66,16 @@ To override the configuration enums in :file:`nrf_config_semmc.h`, you can use t
 Compiling source files
 ======================
 
-For an sEMMC application to function properly, you must compile the driver implementation from the source file :file:`nrf_semmc.c`.
+For a sEMMC application to function properly, you must compile the driver implementation from the source file :file:`nrf_semmc.c`.
 
 Application core and FLPR configuration
 ***************************************
 
 You must adjust the settings for the nRF54H Series SoC to run at highest base clock frequency.
 
-To work with any of the following settings, ensure you have completed the following:
-
-* You have allocated memory for the data pointers used by the sEMMC driver.
-  The memory is independent from the one outlined in the :ref:`semmc_nrf54H_series_porting_guide_ram_configuration` subsection.
-  It is designated to function as shared memory for communication purposes, rather than containing the sEMMC executable code.
+To work with any of the following settings, ensure you have allocated memory for the data pointers used by the sEMMC driver.
+The memory is independent from the one outlined in the :ref:`semmc_nrf54H_series_porting_guide_ram_configuration` subsection.
+It is designated to function as shared memory for communication purposes, rather than containing the sEMMC executable code.
 
 Security configuration
 ======================
@@ -144,21 +143,22 @@ The following options are available, assuming that the FLPR core has access to t
 Configuring pins
 ================
 
-In some cases you might have to modify the sEMMC driver configuration.
-For example, when changing pin drive strength to guarantee signal integrity for a new PCB design.
+In some cases, you might have to modify the sEMMC driver configuration.
+For example, you might need to change the pin drive strength to guarantee signal integrity for a new PCB design.
 You must address these cases on the sEMMC application code.
 
 .. note::
    When using a custom PCB with the nRF54H20 device you might need to match the output impedance on the port you are using.
-   Refer to `this page <https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_custom_pcb.html>`__ for configuring your application for this use case.
+   Refer to the :ref:`ug_nrf54h20_custom_pcb` page for details.
 
 GPIO multiplexing must be handled by setting the correct ``CTRLSEL`` value in UICR.
 
-Any conflicting peripherals and existing memory partitions on the same port as sEMMC must be disabled in the overlay depending on your needs.
-A code snippet of a devicetree overlay to give FLPR access to the pins follows below. First in the snippet, the `pinctrl` block 
-does GPIO configuration, setting up the pins as described in :ref:`semmc_nrf54h_series_porting_guide_gpio_config`.
-The `cpuflpr_vpr` block and the following block will do the memory partitioning of VPR and the RAM used by sEMMC.
+Any conflicting peripherals and existing memory partitions on the same port as sEMMC must be disabled in the devicetree overlay, depending on your requirements.
+See an example code snippet of a devicetree overlay that grants FLPR access to the necessary pins.
+
+The first part of the snippet, the ``pinctrl`` block, configures the relevant GPIOs as described in the :ref:`semmc_nrf54h_series_porting_guide_gpio_config` section.
 
+Next, the ``cpuflpr_vpr`` block and the subsequent block handle the allocation of the VPR memory region and the RAM used by sEMMC.
 
 .. code-block:: dts
 
@@ -234,7 +234,7 @@ The `cpuflpr_vpr` block and the following block will do the memory partitioning
      };
    };
 
-You will need the following lines in your application to apply the pin configuration from your sEMMC board DTS overlay, as well as to initialize the soft peripheral:
+You will need the following lines in your application to apply the pin configuration from your sEMMC board DTS overlay, as well as to initialize the Soft Peripheral:
 
 .. code-block:: c
 
@@ -258,11 +258,10 @@ RAM configuration
 The sEMMC Soft Peripheral operates from RAM.
 
 .. note::
-   Position Independent Code (PIC) is supported for sEMMC.
-   This allows an application to determine where to load the Soft Peripheral firmware.
+   sEMMC supports Position Independent Code (PIC), which allows an application to determine where to load the Soft Peripheral firmware.
 
 Your build environment must reserve the required RAM and ensure that it is readable and writable by both the application core and the FLPR core.
-This table details the memory region, which should be non-cacheable:
+The following table details the memory region, which should be non-cacheable:
 
 .. list-table:: RAM Configuration Table
    :widths: auto
@@ -272,32 +271,31 @@ This table details the memory region, which should be non-cacheable:
      - Address offset
      - Size
    * - sEMMC firmware
-     - `SP_FIRMWARE_ADDR`
+     - ``SP_FIRMWARE_ADDR``
      - 0x3740
    * - sEMMC execution RAM
-     - `SP_FIRMWARE_ADDR` + 0x3740
+     - ``SP_FIRMWARE_ADDR`` + 0x3740
      - 0x600
    * - sEMMC virtual register interface
-     - `SP_FIRMWARE_ADDR` + 0x3D40
+     - ``SP_FIRMWARE_ADDR`` + 0x3D40
      - 0x200
    * - Context saving
      - 0x2f890000
      - 0x200 (but the entire block should be retained)
 
-The build environment described in the :ref:`semmc_nrf54h_series_porting_guide_code` section must comply with these requirements.
+The build environment described in the :ref:`semmc_nrf54h_series_porting_guide_code` section, you must comply with these requirements.
 This includes proper settings in linker scripts, device tree specifications (DTS), and resource allocation.
 
 Ensure that ``SP_FIRMWARE_ADDR`` is set so that it does not overlap with the context saving address.
-For nRF54H Series devices the firmware has been tested with values after the context saving address. This means that
-``SP_FIRMWARE_ADDR`` is a higher value than the context saving address plus the context saving offset.
-
-``SP_FIRMWARE_ADDR`` has been tested and is considered production-ready for value ``0x2f890200``.
+For nRF54H Series devices, the firmware has been tested using values that follow the context saving address.
+This means, that ``SP_FIRMWARE_ADDR`` should be set higher than the context saving address plus the context saving offset.
+The value ``0x2f890200`` for ``SP_FIRMWARE_ADDR`` has been tested and is considered production-ready.
 
 
 IRQ connection
 **************
 
-For sEMMC to communicate with the application core, the sEMMC IRQ handler must be registered. 
+For sEMMC to communicate with the application core, the sEMMC IRQ handler must be registered.
 The following code line registers the IRQ handler to FLPR:
 
 .. code-block:: c
@@ -310,10 +308,12 @@ The following code line registers the IRQ handler to FLPR:
 Read responses
 **************
 
-sEMMC is not able to process read data and response at the same time, as mentioned in :ref:`semmc_limitations`. There are a couple of things that can be done to mitigate this.
+sEMMC cannot process read data and response at the same time (see the :ref:`semmc_limitations`).
+However, you can mitigate it in the following ways:
 
-The preferred way to do reads is to first do the read as normal and process the response with :c:var:`nrf_semmc_config_t.process_response` set to `NRF_EMMC_RESPONSE_PROC_PROCESS`.
-The response is returned in :c:var:`nrf_semmc_cmd_desc_t.err`. If the response is `NRF_SEMMC_SUCCESS` the read was successful. If any other response is returned, you would
-need to do a second read and ignore the response with :c:var:`nrf_semmc_config_t.process_response` set to `NRF_EMMC_RESPONSE_PROC_IGNORE`.
+* The recommended way is to perform the read operation with the :c:var:`nrf_semmc_config_t.process_response` variable set to ``NRF_EMMC_RESPONSE_PROC_PROCESS``.
+  The response is available in the :c:var:`nrf_semmc_cmd_desc_t.err` variable.
+  If the response is ``NRF_SEMMC_SUCCESS``, the read was successful.
+  If you receive a different response, retry the read operation, this time with the :c:var:`nrf_semmc_config_t.process_response` variable set to ``NRF_EMMC_RESPONSE_PROC_IGNORE``.
 
-The other is doing the wanted read command first with :c:var:`nrf_semmc_config_t.process_response` set to `NRF_EMMC_RESPONSE_PROC_IGNORE` followed by a CMD13 to ensure the status is correct.
+* Alternatively, you can perform the read operation with the :c:var:`nrf_semmc_config_t.process_response` variable set to ``NRF_EMMC_RESPONSE_PROC_IGNORE``, and then follow it with a CMD13 command to verify if the status is correct.

softperipheral/doc/sQSPI/sqspi_nrf54H_series_porting_v1_2_0.rst

@@ -73,11 +73,9 @@ Application core and FLPR configuration
 
 You must adjust the settings for the nRF54H Series SoC to run at highest base clock frequency.
 
-To work with any of the following settings, ensure you have completed the following:
-
-* You have allocated memory for the data pointers used by the sQSPI driver.
-  The memory is independent from the one outlined in the :ref:`nrf54H_series_porting_guide_ram_configuration` subsection.
-  It is designated to function as shared memory for communication purposes, rather than containing the sQSPI executable code.
+To work with any of the following settings, ensure you have allocated memory for the data pointers used by the sQSPI driver.
+The memory is independent from the one outlined in the :ref:`nrf54H_series_porting_guide_ram_configuration` subsection.
+It is designated to function as shared memory for communication purposes, rather than containing the sQSPI executable code.
 
 Security configuration
 ======================
@@ -195,12 +193,12 @@ The following options are available, assuming that the FLPR core has access to t
 Configuring pins
 ================
 
-In some cases you might have to modify the sQSPI driver configuration.
-For example, when changing pin drive strength to guarantee signal integrity for a new PCB design.
+In some cases, you might have to modify the sQSPI driver configuration.
+For example, you might need to change the pin drive strength to guarantee signal integrity for a new PCB design.
 
 .. note::
    When using a custom PCB with the nRF54H20 device you might need to match the output impedance on the port you are using.
-   Refer to `this page <https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_custom_pcb.html>`__ for configuring your application for a custom PCB.
+   Refer to the :ref:`ug_nrf54h20_custom_pcb` page for details.
 
 You must address these cases on the sQSPI application code:
 
@@ -213,11 +211,12 @@ GPIO multiplexing must be handled by setting the correct ``CTRLSEL`` value in UI
 
 Additionally, the sQSPI application requires FastPad bias configuration to run at high frequency on SCLK.
 
-Any conflicting peripherals and existing memory partitions on the same port as sQSPI must be disabled in the overlay depending on your needs.
-An example code snippet of a devicetree overlay to give FLPR access to the pins on port P7 follows below. First in the snippet, the `pinctrl` block
-does GPIO configuration, setting up the pins as described in :ref:`sqspi_nrf54h_series_porting_guide_gpio_config`.
-The `cpuflpr_vpr` block and the following block will do the memory partitioning of VPR and the RAM used by sQSPI.
+Any conflicting peripherals and existing memory partitions on the same port as sQSPI must be disabled in the devicetree overlay, depending on your requirements.
+See an example code snippet of a devicetree overlay that grants FLPR access to the **P7** port.
+
+The first part of the snippet, the ``pinctrl`` block, configures the relevant GPIOs as described in the :ref:`sqspi_nrf54h_series_porting_guide_gpio_config` section.
 
+Next, the ``cpuflpr_vpr`` block and the subsequent block handle the allocation of the VPR memory region and the RAM used by sQSPI.
 
 .. code-block:: dts
 
@@ -297,7 +296,7 @@ The `cpuflpr_vpr` block and the following block will do the memory partitioning
    };
 
 
-You will need the following lines in your application to apply the pin configuration from your sQSPI board DTS overlay, as well as to initialize the soft peripheral:
+You will need the following lines in your application to apply the pin configuration from your sQSPI board DTS overlay, as well as to initialize the Soft Peripheral:
 
 .. code-block:: c
 
@@ -321,11 +320,10 @@ RAM configuration
 The sQSPI Soft Peripheral operates from RAM.
 
 .. note::
-   Starting from sQSPI 1.0.0, Position Independent Code (PIC) is supported.
-   This allows an application to determine where to load the Soft Peripheral firmware.
+   Starting from sQSPI 1.0.0, sQSPI supports Position Independent Code (PIC), which allows an application to determine where to load the Soft Peripheral firmware.
 
 Your build environment must reserve the required RAM and ensure that it is readable and writable by both the application core and the FLPR core.
-This table details the memory region, which should be non-cacheable:
+The following table details the memory region, which should be non-cacheable:
 
 .. list-table:: RAM Configuration Table
    :widths: auto
@@ -335,26 +333,25 @@ This table details the memory region, which should be non-cacheable:
      - Address offset
      - Size
    * - sQSPI firmware
-     - `SP_FIRMWARE_ADDR`
+     - ``SP_FIRMWARE_ADDR``
      - 0x3740
    * - sQSPI execution RAM
-     - `SP_FIRMWARE_ADDR` + 0x3740
+     - ``SP_FIRMWARE_ADDR`` + 0x3740
      - 0x400
    * - sQSPI virtual register interface
-     - `SP_FIRMWARE_ADDR` + 0x3B40
+     - ``SP_FIRMWARE_ADDR`` + 0x3B40
      - 0x200
    * - Context saving
      - 0x2f890000
      - 0x200 (but the entire block should be retained)
 
-The build environment described in the :ref:`nrf54h_series_porting_guide_code` section must comply with these requirements.
+The build environment described in the :ref:`nrf54h_series_porting_guide_code` section, you must comply with these requirements.
 This includes proper settings in linker scripts, device tree specifications (DTS), and resource allocation.
 
 Ensure that ``SP_FIRMWARE_ADDR`` is set so that it does not overlap with the context saving address.
-For nRF54H Series devices the firmware has been tested with values after the context saving address. This means that
-``SP_FIRMWARE_ADDR`` is a higher value than the context saving address plus the context saving offset.
-
-``SP_FIRMWARE_ADDR`` has been tested and is considered production-ready for value ``0x2f890200``.
+For nRF54H Series devices, the firmware has been tested using values that follow the context saving address.
+This means, that ``SP_FIRMWARE_ADDR`` should be set higher than the context saving address plus the context saving offset.
+The value ``0x2f890200`` for ``SP_FIRMWARE_ADDR`` has been tested and is considered production-ready.
 
 IRQ connection
 **************