From ba929f92625962fe73cd6eae0a2daec3f0c119f9 Mon Sep 17 00:00:00 2001 From: Francesco Domenico Servidio Date: Mon, 16 Dec 2024 14:43:08 +0100 Subject: [PATCH] doc: Updated H20 GS and ABI comp Updated H20 GS and ABI comp for 2.9-nRF54H20. Signed-off-by: Francesco Domenico Servidio --- .../device_guides/nrf54h/ug_nrf54h20_gs.rst | 62 ++++--- doc/nrf/links.txt | 3 +- .../abi_compatibility.rst | 61 ++++++- .../migration_guide_2.9.0-nrf54h20-rc1.rst | 164 ++++++++++++++++++ 4 files changed, 263 insertions(+), 27 deletions(-) create mode 100644 doc/nrf/releases_and_maturity/migration/migration_guide_2.9.0-nrf54h20-rc1.rst diff --git a/doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_gs.rst b/doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_gs.rst index 448895c5ae29..839b6b380276 100644 --- a/doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_gs.rst +++ b/doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_gs.rst @@ -24,7 +24,7 @@ Make sure you have all the required hardware and that your computer has one of t Hardware ======== -* nRF54H20 DK version PCA10175 Engineering C - v0.8.3 and later revisions +* nRF54H20 DK version PCA10175 Engineering C - v0.9.0 and later revisions Check the version number on your DK's sticker to verify its compatibility with the |NCS|. @@ -48,9 +48,9 @@ See :ref:`supported_OS` for more information. You also need the following: -* `Git`_ or `Git for Windows`_ (on Linux and Mac, or Windows, respectively). -* `curl`_. -* SEGGER J-Link |jlink_ver| and, on Windows, also the SEGGER USB Driver for J-Link from `SEGGER J-Link`_ |jlink_ver|. +* `Git`_ or `Git for Windows`_ (on Linux and Mac, or Windows, respectively) +* `curl`_ +* SEGGER J-Link |jlink_ver| and, on Windows, also the SEGGER USB Driver for J-Link from `SEGGER J-Link`_ |jlink_ver| .. note:: To install the SEGGER USB Driver for J-Link on Windows, manually install J-Link |jlink_ver| from the command line using the ``-InstUSBDriver=1`` parameter: @@ -66,11 +66,14 @@ You also need the following: .\JLink_Windows_V794i_x86_64.exe -InstUSBDriver=1 #. Follow the on-screen instructions. - #. After installing, add the J-Link executable to the system path on Linux and MacOS, or to the environment variables on Windows, to run it from anywhere on the system. + #. After installing, ensure the J-Link executable can be run from anywhere on your system: -* The latest version of |VSC| for your operating system from the `Visual Studio Code download page`_. -* In |VSC|, the latest version of the `nRF Connect for VS Code Extension Pack`_. -* On Linux, the `nrf-udev`_ module with udev rules required to access USB ports on Nordic Semiconductor devices and program the firmware. + * For Linux and MacOS, add it to the system path. + * For Windows, add it to the environment variables. + +* The latest version of |VSC| for your operating system from the `Visual Studio Code download page`_ +* In |VSC|, the latest version of the `nRF Connect for VS Code Extension Pack`_ +* On Linux, the `nrf-udev`_ module with udev rules required to access USB ports on Nordic Semiconductor devices and program the firmware .. _ug_nrf54h20_gs_installing_software: @@ -82,7 +85,7 @@ To work with the nRF54H20 DK, follow the instructions in the next sections to in .. _ug_nrf54h20_install_toolchain: Installing the |NCS| and its toolchain -************************************** +====================================== You can install the |NCS| and its toolchain by using Toolchain Manager. @@ -95,7 +98,7 @@ To install the toolchain and the SDK using the Toolchain Manager app, complete t a. `Download nRF Connect for Desktop`_ for your operating system. #. Install and run the tool on your machine. - #. In the :guilabel:`APPS` section, click :guilabel:`Install` next to Toolchain Manager. + #. In the :guilabel:`Apps` section, click :guilabel:`Install` next to Toolchain Manager. The app installs on your machine, and the :guilabel:`Install` button changes to :guilabel:`Open`. @@ -147,18 +150,20 @@ To install the toolchain and the SDK using the Toolchain Manager app, complete t You can then follow the instructions in :ref:`creating_cmd`. Installing a terminal application -********************************** +================================= Install a terminal emulator, such as the `Serial Terminal app`_ (from the nRF Connect for Desktop application) or the nRF Terminal (part of the `nRF Connect for Visual Studio Code`_ extension). Both of these terminal emulators start the required :ref:`toolchain environment `. Installing nRF Util and its commands -************************************ +==================================== Using the nRF54H20 DK with the |NCS| version |release| requires the following: -* nRF Util version 7.11.1 or higher -* nRF Util ``device`` version 2.7.2 +* nRF Util version 7.13.0 or higher +* nRF Util ``device`` version 2.7.8 +* nRF Util ``trace`` version 3.10.0 +* nRF Util ``suit`` version 0.9.0 1. Download the nrfutil executable file from the `nRF Util development tool`_ product page. #. Add nRF Util to the system path on Linux and MacOS, or environment variables on Windows, to run it from anywhere on the system. @@ -174,15 +179,23 @@ Using the nRF54H20 DK with the |NCS| version |release| requires the following: nrfutil --version -#. If your version is below 7.11.1, run the following command to update nRF Util:: +#. If your version is below 7.13.0, run the following command to update nRF Util:: nrfutil self-upgrade For more information, consult the `nRF Util`_ documentation. -#. Install the nRF Util ``device`` command version 2.7.2 as follows:: +#. Install the nRF Util ``device`` command version 2.7.8 as follows:: + + nrfutil install device=2.7.8 --force + +#. Install the nRF Util ``trace`` command version 3.10.0 as follows:: + + nrfutil install trace=3.10.0 --force - nrfutil install device=2.7.2 --force +#. Install the nRF Util ``suit`` command version 0.9.0 as follows:: + + nrfutil install suit=0.9.0 --force .. _ug_nrf54h20_gs_bringup: @@ -202,9 +215,8 @@ To prepare the nRF54H20 DK for first use, you must manually program the values o 1. Download the `BICR new binary file`_. #. Connect the nRF54H20 DK to your computer using the **DEBUGGER** port on the DK. -.. note:: - On MacOS, connecting the DK might cause a popup containing the message ``“Disk Not Ejected Properly`` to appear repeatedly on screen. - To disable this, run ``JLinkExe``, then run ``MSDDisable`` in the J-Link Commander interface. + .. note:: + On MacOS, when connecting the DK, you might see a popup with the message ``Disk Not Ejected Properly`` appearing multiple times. #. List all the connected development kits to see their serial number (matching the one on the DK's sticker):: @@ -221,10 +233,11 @@ To prepare the nRF54H20 DK for first use, you must manually program the values o Programming the nRF54H20 SoC binaries ===================================== -After programming the BICR, you need to provide the nRF54H20 SoC with the provisioning of the nRF54H20 SoC binaries, a bundle containing the precompiled firmware for the Secure Domain and System Controller. +After programming the BICR, program the nRF54H20 SoC with the :ref:`nRF54H20 SoC binaries `. +This bundle contains the precompiled firmware for the :ref:`Secure Domain ` and :ref:`System Controller `. To program the nRF54H20 SoC binaries to the nRF54H20 DK, do the following: -1. Download the `nRF54H20 SoC Binaries v0.7.0 for EngC DKs`_, compatible with the nRF54H20 DK v0.8.3 and later revisions. +1. Download the `nRF54H20 SoC Binaries v0.8.0`_, compatible with the nRF54H20 DK v0.9.0 and later revisions. .. note:: On MacOS, ensure that the ZIP file is not unpacked automatically upon download. @@ -279,7 +292,7 @@ If you have multiple Nordic Semiconductor devices, ensure that only the nRF54H20 west flash -The sample will be built and programmed automatically on both the application core and the Peripheral Processor (PPR) of the nRF54H20. +This command builds and programs the sample automatically on both the application core and the Peripheral Processor (PPR) of the nRF54H20 SoC. .. include:: /includes/nRF54H20_erase_UICR.txt @@ -313,7 +326,8 @@ Next steps You are now all set to use the nRF54H20 DK. See the following links for where to go next: -* :ref:`ug_nrf54h20_architecture` for information about the multicore System on Chip, such as the responsibilities of the cores and their interprocessor interactions, the memory mapping, and the boot sequence. +* :ref:`ug_nrf54h20_architecture` for information about the multicore System on Chip. + This includes descriptions of core responsibilities, their interprocessor interactions, memory mapping, and the boot sequence. * The :ref:`introductory documentation ` for more information on the |NCS| and the development environment. * :ref:`configuration_and_build` documentation to learn more about the |NCS| development environment. * :ref:`ug_nrf54h` documentation for more advanced topics related to the nRF54H20. diff --git a/doc/nrf/links.txt b/doc/nrf/links.txt index 41c25d71e753..2195bca6fb58 100644 --- a/doc/nrf/links.txt +++ b/doc/nrf/links.txt @@ -567,7 +567,7 @@ .. _`LwM2M carrier library changelog for v1.9.1`: https://docs.nordicsemi.com/bundle/ncs-1.9.1/page/nrf/libraries/bin/lwm2m_carrier/CHANGELOG.html .. _`LwM2M carrier library changelog for v1.9.0`: https://docs.nordicsemi.com/bundle/ncs-1.9.0/page/nrf/libraries/bin/lwm2m_carrier/CHANGELOG.html - +.. _`Migration guide for nRF Connect SDK v2.9.0-nRF54H20-rc1`: https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/releases_and_maturity/migration/migration_guide_2.9.0-nrf54h20-rc1.html .. _`Migration guide for nRF Connect SDK v2.9.0`: https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/releases_and_maturity/migration/migration_guide_2.9.html .. _`Migration guide for nRF Connect SDK v2.8.0`: https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/releases_and_maturity/migration/migration_guide_2.8.html .. _`Migration guide for nRF Connect SDK v2.7.0`: https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/releases_and_maturity/migration/migration_guide_2.7.html @@ -1750,6 +1750,7 @@ .. _`nRF54H20 SoC binaries v0.6.5`: https://files.nordicsemi.com/artifactory/SDSC/external/nrf54h20_soc_binaries_v0.6.5.zip .. _`nRF54H20 SoC Binaries v0.7.0 for EngC DKs`: https://files.nordicsemi.com/artifactory/SDSC/external/nrf54h20_soc_binaries_v0.7.0_engc.zip .. _`nRF54H20 SoC Binaries v0.7.0 for EngB DKs`: https://files.nordicsemi.com/artifactory/SDSC/external/nrf54h20_soc_binaries_v0.7.0_engb.zip +.. _`nRF54H20 SoC binaries v0.8.0`: https://files.nordicsemi.com/ui/native/SDSC/external/nrf54h20_soc_binaries_v0.8.0.zip .. _`BICR binary file`: https://files.nordicsemi.com/artifactory/SDSC/external/bicr_ext_loadcap.hex .. _`BICR new binary file`: https://files.nordicsemi.com/artifactory/SDSC/external/bicr/bicr.hex diff --git a/doc/nrf/releases_and_maturity/abi_compatibility.rst b/doc/nrf/releases_and_maturity/abi_compatibility.rst index bfaceb3529e2..dfb8e625b7ae 100644 --- a/doc/nrf/releases_and_maturity/abi_compatibility.rst +++ b/doc/nrf/releases_and_maturity/abi_compatibility.rst @@ -1,7 +1,7 @@ .. _abi_compatibility: ABI Compatibility -***************** +################# .. contents:: :local: @@ -19,7 +19,7 @@ For example, adding a new function to a library is typically an ABI-compatible c However, changes that affect data structure layouts, such as altering field order or size, break ABI compatibility as they change the memory layout expected by existing binaries. ABI Compatibility Matrix for the nRF54H20 SoC Binaries -====================================================== +****************************************************** The following table illustrates ABI compatibility between different versions of the nRF54H20 SoC binaries and the |NCS|: @@ -28,6 +28,8 @@ The following table illustrates ABI compatibility between different versions of * - |NCS| versions - Compatible nRF54H20 SoC binaries version + * - |NCS| v2.9.0-nRF54H20 + - `nRF54H20 SoC Binaries v0.8.0`_, compatible with the nRF54H20 DK v0.9.0 and later revisions. * - |NCS| v2.9.0 - `nRF54H20 SoC Binaries v0.7.0 for EngC DKs`_, compatible with the nRF54H20 DK v0.8.3 and later revisions. * - |NCS| v2.8.0 @@ -44,3 +46,58 @@ The following table illustrates ABI compatibility between different versions of ABI compatibility ensures that the Secure Domain and System Controller firmware binaries do not need to be recompiled each time the Application, Radio binaries, or both are recompiled, as long as they are based on a compatible |NCS| version. Additionally, maintaining ABI compatibility allows the nRF54H20 SoC binaries components to work together without recompilation when updating to newer |NCS| versions. + +nRF54H20 SoC Binaries v0.8.0 changelog +************************************** + +The following sections provide detailed lists of changes by component. + +Secure Domain Firmware (SDFW) v9.0.0 +===================================== + +Added +----- + +* Purge protection can be enabled over ADAC. +* Clock control is enabled in SDFW. +* Global domain power request service is integrated in SDFW. +* PUF values from SDROM are cleared on boot. + +Updated +------- + +* Local domain reset will trigger a global reset. + ``RESETINFO`` will contain both the global and local reset reason. +* All processors are booted regardless of whether they have firmware. + They are booted in halted mode if no firmware is present. + +Removed +------- + +* Several services from SSF over ADAC. +* Reset event service. + +Fixed +----- + +* An issue with invoking crypto service from multiple threads or clients. + +System Controller Firmware (SCFW) v4.0.0 +========================================= + +Added +----- + +* GDFS service: New service implementation to handle change of global domain frequency on demand (HSFLL120). +* GDPWR service: New power domains. + +Updated +------- + +* GDPWR service: Renamed power domains. +* GPIO power configuration: + + * When ``POWER.CONFIG.VDDAO1V8 == External``, the function ``power_bicr_is_any_gpio_powered_from_internal_1v8_reg`` now returns ``false``. + This allows proper selection of low power modes when supplying nRF54H20 with an external 1.8V, even if the ``VDDIO_x`` are configured as SHORTED. + +* Temperature sensor coefficients. diff --git a/doc/nrf/releases_and_maturity/migration/migration_guide_2.9.0-nrf54h20-rc1.rst b/doc/nrf/releases_and_maturity/migration/migration_guide_2.9.0-nrf54h20-rc1.rst new file mode 100644 index 000000000000..a9b2dd7c7360 --- /dev/null +++ b/doc/nrf/releases_and_maturity/migration/migration_guide_2.9.0-nrf54h20-rc1.rst @@ -0,0 +1,164 @@ +:orphan: + +.. _migration_2.9.0-nrf54h20-rc1: + +Migration guide for |NCS| v2.9.0-nRF54H20-rc1 +############################################# + +.. contents:: + :local: + :depth: 3 + +This document describes the changes required or recommended when migrating your nRF54H20 application from the |NCS| v2.8.0 to the |NCS| v2.9.0-nRF54H20-rc1. + +.. HOWTO + + Add changes in the following format: + + Component (for example, application, sample or libraries) + ********************************************************* + + .. toggle:: + + * Change1 and description + * Change2 and description + +.. _migration_2.9.0-nrf54h20-rc1_required: + +Required changes +**************** + +The following changes are mandatory to make your application work in the same way as in previous releases. + +nRF54H20 +======== + +This section describes the changes specific to the nRF54H20 SoC and DK support in the |NCS|. + +DK compatibility +---------------- + +.. toggle:: + + * The |NCS| v2.9.0-nRF54H20-rc1 is compatible only with the Engineering C - v0.9.0 and later revisions of the nRF54H20 DK, PCA10175. + Check the version number on your DK's sticker to verify its compatibility with the |NCS|. + +Dependencies +------------ + +The following required dependencies for the nRF54H20 SoC and DK have been updated. + +SDK and toolchain ++++++++++++++++++ + +.. toggle:: + + * To update the SDK and the toolchain, do the following: + + 1. Open Toolchain Manager in nRF Connect for Desktop. + #. Click :guilabel:`SETTINGS` in the navigation bar to specify where you want to install the |NCS|. + #. In :guilabel:`SDK ENVIRONMENTS`, click the :guilabel:`Install` button next to the |NCS| version |release|. + +nRF54H20 SoC binaries ++++++++++++++++++++++ + +.. toggle:: + + * The *nRF54H20 SoC binaries* bundle has been updated to version 0.8.0. + + To update the SoC binaries bundle of your development kit while in Root of Trust, do the following: + + 1. Download the `nRF54H20 SoC Binaries v0.8.0`_. + + .. note:: + On macOS, ensure that the ZIP file is not unpacked automatically upon download. + + #. Purge the device as follows:: + + nrfutil device recover --core Application --serial-number + nrfutil device recover --core Network --serial-number + + #. Erase the device as follows:: + + nrfutil device erase --all --core Network --serial-number + nrfutil device erase --all --core Application --serial-number + nrfutil device reset --reset-kind RESET_PIN --serial-number + + #. Run ``west update``. + #. Move the correct :file:`.zip` bundle to a folder of your choice, then run nRF Util to program the binaries using the following command:: + + nrfutil device x-suit-dfu --firmware nrf54h20_soc_binaries_v0.8.0.zip --serial-number + + #. Erase the device again as follows:: + + nrfutil device erase --all --core Network --serial-number + nrfutil device erase --all --core Application --serial-number + nrfutil device reset --reset-kind RESET_PIN --serial-number + +nrfutil ++++++++ + +.. toggle:: + + * ``nrfutil`` has been updated to version 7.13.0. + + Install nRF Util version 7.13.0 as follows: + + 1. Download the nRF Util executable file from the `nRF Util development tool`_ product page. + #. Add nRF Util to the system path on Linux and macOS, or environment variables on Windows, to run it from anywhere on the system. + On Linux and macOS, use one of the following options: + + * Add nRF Util's directory to the system path. + * Move the file to a directory in the system path. + + #. On macOS and Linux, give ``nrfutil`` execute permissions by typing ``chmod +x nrfutil`` in a terminal or using a file browser. + This is typically a checkbox found under file properties. + #. On macOS, to run the nRF Util executable, you need to allow it in the system settings. + #. Verify the version of the nRF Util installation on your machine by running the following command:: + + nrfutil --version + + #. If your version is below 7.13.0, run the following command to update nRF Util:: + + nrfutil self-upgrade + + For more information, see the `nRF Util`_ documentation. + +nrfutil device +++++++++++++++ + +.. toggle:: + + * ``nrfutil device`` has been updated to version 2.7.8. + + Install the nRF Util ``device`` command version 2.7.8 as follows:: + + nrfutil install device=2.7.8 --force + + For more information, consult the `nRF Util`_ documentation. + +nrfutil trace ++++++++++++++ + +.. toggle:: + + * ``nrfutil trace`` has been updated to version 3.10.0. + + Install the nRF Util ``trace`` command version 3.10.0 as follows:: + + nrfutil install trace=3.10.0 --force + + For more information, consult the `nRF Util`_ documentation. + +nrfutil suit +++++++++++++ + +.. toggle:: + + * ``nrfutil suit`` has been updated to version 0.9.0. + + Install the nRF Util ``suit`` command version 0.9.0 as follows:: + + nrfutil install suit=0.9.0 --force + + For more information, consult the `nRF Util`_ documentation.