diff --git a/CODEOWNERS b/CODEOWNERS index a97acc99171c..baa99b384853 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -57,6 +57,7 @@ Kconfig* @tejlmand /doc/**/conf.py @carlescufi /doc/kconfig/ @gmarull /doc/nrf/ @carlescufi +/doc/nrf/device_guides/working_with_nrf/nrf54h/ @FrancescoSer /doc/nrfx/ @gmarull /doc/matter/ @gmarull /doc/mcuboot/ @carlescufi diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/cpuapp_include_tree.svg b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/cpuapp_include_tree.svg new file mode 100644 index 000000000000..60434de94a16 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/cpuapp_include_tree.svg @@ -0,0 +1,155 @@ + + + + + + + + + + + + + + + + Page-1 + + Nordic Sky + nrf54h20dk_nrf54h20_cpuapp.dts + + nrf54h20dk_nrf54h20_cpuapp.dts + + Nordic Sky.11 + nrf54h20dk_nrf54h20_cpuapp-pinctrl.dtsi + + nrf54h20dk_nrf54h20_cpuapp-pinctrl.dtsi + + Nordic Sky.12 + nrf54h20_cpuapp.dtsi + + nrf54h20_cpuapp.dtsi + + Nordic Sky.14 + nrf54h20.dtsi + + nrf54h20.dtsi + + Nordic Sky.15 + nrf54h20_shared_memory_*.dtsi + + nrf54h20_shared_memory_*.dtsi + + Nordic Sky.16 + haltium_cpuapp_common.dtsi + + haltium_cpuapp_common.dtsi + + Nordic Sky.17 + haltium_cpuapp_local.dtsi + + haltium_cpuapp_local.dtsi + + Nordic Sky.18 + haltium_cpuapp_peripherals.dtsi + + haltium_cpuapp_peripherals.dtsi + + Nordic Sky.19 + nrf_common.dtsi + + nrf_common.dtsi + + Nordic Sky.20 + haltium_global_peripherals.dtsi + + haltium_global_peripherals.dtsi + + Nordic Sky.21 + haltium_global_peripherals_virtual.dtsi + + haltium_global_peripherals_virtual.dtsi + + Nordic Sky.23 + haltium_tdd_peripherals.dtsi + + haltium_tdd_peripherals.dtsi + + Dynamic connector + + + + Dynamic connector.27 + + + + Dynamic connector.28 + + + + Dynamic connector.29 + + + + Dynamic connector.30 + + + + Dynamic connector.32 + + + + Dynamic connector.33 + + + + Dynamic connector.34 + + + + Dynamic connector.35 + + + + Dynamic connector.36 + + + + Dynamic connector.37 + + + + Nordic Blue + ic-next/boards/<arch> ic-next/dts/common ic-next/dts/<arch> + + ic-next/boards/<arch> ic-next/dts/common ic-next/dts/<arch> + + Nordic Lake + + + + Nordic Sun + + + + Nordic Grass + + + + diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nRF54H20_Domains.svg b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nRF54H20_Domains.svg new file mode 100644 index 000000000000..1017b6faf0bb --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nRF54H20_Domains.svg @@ -0,0 +1,96 @@ + + + + + + + + Page-1 + + Nordic Lake.8 + Radio Core + + Radio Core + + Nordic Sky.9 + CPU + + CPU + + Nordic Sky.10 + Multiprotocol 2.4 GHz Radio + + Multiprotocol 2.4 GHz Radio + + Nordic Lake.14 + Application Core + + Application Core + + Nordic Sky.15 + CPU + + CPU + + Nordic Lake.19 + Global Domain + + Global Domain + + Nordic Sky.20 + RAM + + RAM + + Nordic Sky.21 + NVM + + NVM + + Nordic Sky.22 + Peripherals + + Peripherals + + Nordic Lake.23 + Secure Domain + + Secure Domain + + Nordic Sky.24 + Secure Boot + + Secure Boot + + Nordic Sky.25 + Secure Storage + + Secure Storage + + Nordic Sky.26 + Physical Security + + Physical Security + + Nordic Sky.28 + Crypto Accelerators + + Crypto Accelerators + + Dynamic connector + + + + diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nRF54H20_appcore.svg b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nRF54H20_appcore.svg new file mode 100644 index 000000000000..208591711032 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nRF54H20_appcore.svg @@ -0,0 +1,60 @@ + + + + + + + + Page-1 + + Nordic Lake + + + + Nordic Sky + Arm Cortex-M33 Max 320 MHz DVFS L1 I-Cache, L1 D-Cache Trustz... + + Arm Cortex-M33 Max 320 MHz DVFS L1 I-Cache, L1 D-Cache Trustzone, FPU, DSP + + Nordic Sky.9 + MVDMA + + MVDMA + + Nordic Sky.10 + SPU + + SPU + + Nordic Sky.11 + MPC + + MPC + + Nordic Sky.12 + IPC + + IPC + + Nordic Sky.13 + 2x WDT + + 2x WDT + + Nordic Sky.14 + 32 KB RAM + + 32 KB RAM + + diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nRF54H20_bootsequence.svg b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nRF54H20_bootsequence.svg new file mode 100644 index 000000000000..30b21537b416 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nRF54H20_bootsequence.svg @@ -0,0 +1,135 @@ + + + + + + + + + + + + + + + + Page-1 + + Nordic Lake.1003 + Primary boot stage + + Primary boot stage + + Nordic Lake.1004 + Secondary boot stage + + Secondary boot stage + + Nordic Blue + System Controller ROM + + System Controller ROM + + Nordic Sky + Calibrate MRAM from OTP Re-calibrate system from FICR once MR... + + · Calibrate MRAM from OTP · Re-calibrate system from FICR once MRAM is up + + Nordic Blue.7 + Secure Domain ROM + + Secure Domain ROM + + Nordic Sky.8 + Verify secure domain firmware Move PUF keys to CRACEN Authent... + + · Verify secure domain firmware · Move PUF keysto CRACEN · Authenticated erase + + Nordic Blue.9 + Secure Domain firmware + + Secure Domain firmware + + Nordic Sky.10 + Configure global resources Control access port(s) Verify syst... + + · Configure global resources · Control access port(s) · Verify system controller firmware · Verify local cares firmware · Secure servicesfor local cores + + Nordic Blue.11 + System Controller firmware + + System Controller firmware + + Nordic Sky.12 + Global services for local cores + + · Global servicesfor local cores + + Nordic Blue.13 + Radio Core + + Radio Core + + Nordic Blue.27 + Application Core + + Application Core + + Event.1005 + + + Dynamic connector.1006 + + + + Dynamic connector.1007 + + + + Dynamic connector.1008 + + + + Dynamic connector.1009 + + + + Dynamic connector.1010 + + + + diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nRF54H20_globaldomain.svg b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nRF54H20_globaldomain.svg new file mode 100644 index 000000000000..2b37c0634bbb --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nRF54H20_globaldomain.svg @@ -0,0 +1,311 @@ + + + + + + + + Page-1 + + Nordic Blue + High-Speed + + High-Speed + + Nordic Blue.10 + Low-Leakage + + Low-Leakage + + Nordic Blueslate + Memories + + Memories + + Nordic Blueslate.14 + Peripherals + + Peripherals + + Nordic Blue.17 + SRAM 768 KB + + SRAM 768 KB + + Nordic Blue.18 + MRAM 1024 KB + + MRAM 1024 KB + + Nordic Blue.19 + MRAM 1024 KB + + MRAM 1024 KB + + Nordic Blue.20 + ROM + + ROM + + Nordic Lake + Peripheral Handling (optional) Software-defined peripherals + + Peripheral Handling (optional) Software-defined peripherals + + Nordic Blue.27 + HS-SPIM + + HS-SPIM + + Nordic Blue.28 + HS-SPIS + + HS-SPIS + + Nordic Blue.29 + HS-SPIM / UART + + HS-SPIM / UART + + Nordic Blue.30 + HS-USB + + HS-USB + + Nordic Blue.31 + 2x I3C + + 2x I3C + + Nordic Blue.32 + HS-PWM + + HS-PWM + + Nordic Blue.33 + 2x Timer + + 2x Timer + + Nordic Blue.34 + 128 KB RAM + + 128 KB RAM + + Nordic Blue.35 + FLPR CPU + + FLPR CPU + + Nordic Blueslate.36 + Configuration and control + + Configuration and control + + Nordic Blueslate.37 + + + + Nordic Blue.38 + SPU + + SPU + + Nordic Blue.39 + IPCT + + IPCT + + Nordic Blue.40 + MPC + + MPC + + Nordic Blue.41 + DDPIC + + DDPIC + + Nordic Blue.42 + 100 MHz 1.8 V GPIO Port + + 100 MHz 1.8 V GPIO Port + + Nordic Blue.43 + 200 MHz 1.8 V GPIO Port + + 200 MHz 1.8 V GPIO Port + + Nordic Blueslate.45 + Peripherals + + Peripherals + + Nordic Lake.46 + Peripheral Handling (optional) + + Peripheral Handling (optional) + + Nordic Blue.47 + Global RTC + + Global RTC + + Nordic Blue.48 + 8x SPI/TWI/UART + + 8x SPI/TWI/UART + + Nordic Blue.49 + 8x Timer + + 8x Timer + + Nordic Blue.50 + 14-bit ADC + + 14-bit ADC + + Nordic Blue.51 + 4x 4ch PWM + + 4x 4ch PWM + + Nordic Blue.52 + PDM + + PDM + + Nordic Blue.53 + Audio PLL + + Audio PLL + + Nordic Blue.54 + 80 KB RAM + + 80 KB RAM + + Nordic Blue.55 + PPR CPU + + PPR CPU + + Nordic Blueslate.56 + Configuration and control + + Configuration and control + + Nordic Blueslate.57 + + + + Nordic Blue.58 + SPU + + SPU + + Nordic Blue.59 + IPCT + + IPCT + + Nordic Blue.60 + MPC + + MPC + + Nordic Blue.61 + DDPIC + + DDPIC + + Nordic Blue.62 + 1.8 – 3.6 V GPIO Port + + 1.8 –V GPIO Port + + Nordic Blue.63 + 3x 1.2 – 1.8 V GPIO Port + + 3x 1.2 –V GPIO Port + + Nordic Blue.64 + COMP + + COMP + + Nordic Blue.65 + SIMIF + + SIMIF + + Nordic Blue.66 + NFC A-Tag + + NFC A-Tag + + Nordic Blue.67 + CAN + + CAN + + Nordic Blue.68 + LPCOMP + + LPCOMP + + Nordic Blue.69 + 2x QDEC + + 2x QDEC + + Nordic Blue.70 + 2x I2S / 2x TDM + + 2x I2S / 2x TDM + + Nordic Blue.71 + IRQMAP + + IRQMAP + + Nordic Blue.72 + IPCMAP + + IPCMAP + + Nordic Blue.1000 + HS-USB + + HS-USB + + Nordic Blue.1001 + 2x I3C + + 2x I3C + + Nordic Blue.1002 + HS-PWM + + HS-PWM + + Nordic Blue.1003 + 2x Timer + + 2x Timer + + diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nRF54H20_lifecycle_states.svg b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nRF54H20_lifecycle_states.svg new file mode 100644 index 000000000000..f4eb8068d3d2 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nRF54H20_lifecycle_states.svg @@ -0,0 +1,125 @@ + + + + + + + + + + + + + + + + + + + + + + Page-1 + + Nordic Light Grey.37 + Production + + Production + + Nordic Light Grey.36 + End-of-life + + End-of-life + + Nordic Light Grey.35 + In-field + + In-field + + Nordic Blue + DISCARDED + + DISCARDED + + Nordic Blue.16 + ANALYSIS + + ANALYSIS + + Nordic Blue.17 + DEPLOYED + + DEPLOYED + + Nordic Blue.18 + RoT + + RoT + + Nordic Blue.19 + EMPTY + + EMPTY + + Dynamic connector + + + + Dynamic connector.21 + + + + Dynamic connector.22 + + + + Dynamic connector.23 + + + + Dynamic connector.24 + + + + Dynamic connector.25 + + + + Dynamic connector.26 + + + + Dynamic connector.28 + + + + Dynamic connector.31 + + + + Dynamic connector.32 + + + + Dynamic connector.33 + + + + diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nRF54H20_memorymap.svg b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nRF54H20_memorymap.svg new file mode 100644 index 000000000000..e64cca1ca191 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nRF54H20_memorymap.svg @@ -0,0 +1,394 @@ + + + + + + + + Page-1 + + Rectangle.27 + Internal data memory (non-secure) + + Internal data memory (non-secure) + + Rectangle.6 + Secure alias of internal data memory region + + Secure alias of internal data memory region + + Rectangle.33 + Peripherals (non-secure) + + Peripherals (non-secure) + + Rectangle.35 + Secure alias of peripherals region + + Secure alias of peripherals region + + Rectangle.38 + Global Domain EXMIF (unencrypted view of external memory) + + Global Domain EXMIF (unencrypted view of external memory) + + Rectangle.40 + Global Domain EXMEE (encrypted alias of external memory) + + Global Domain EXMEE (encrypted alias of external memory) + + Rectangle.44 + STM trace + + STM trace + + Rectangle.46 + Peripherals accessible to all masters + + Peripherals accessible to all masters + + Rectangle.48 + Global Trace&Debug Components + + Global Trace&Debug Components + + Rectangle.50 + Peripherals accessible to a specific CPU + + Peripherals accessible to a specific CPU + + Rectangle.52 + Cortex-M System PPB + + Cortex-M System PPB + + Rectangle.54 + System Vendor_SYS + + System Vendor_SYS + + Sheet.18 + 0xFFFF_FFFF + + 0xFFFF_FFFF + + Rectangle.22 + Internal program memory (non-secure) + + Internal program memory (non-secure) + + Rectangle.23 + Secure alias of internal program memory region + + Secure alias of internal program memory region + + Sheet.1012 + 0xF000_0000 + + 0xF000_0000 + + Sheet.1013 + 0xE100_0000 + + 0xE100_0000 + + Sheet.1014 + 0xE000_0000 + + 0xE000_0000 + + Sheet.1015 + 0xC100_0000 + + 0xC100_0000 + + Sheet.1016 + 0xBF00_0000 + + 0xBF00_0000 + + Sheet.1017 + 0xA000_0000 + + 0xA000_0000 + + Sheet.1018 + 0x8000_0000 + + 0x8000_0000 + + Sheet.1019 + 0x6000_0000 + + 0x6000_0000 + + Sheet.1020 + 0x4000_0000 + + 0x4000_0000 + + Sheet.1021 + 0x3000_0000 + + 0x3000_0000 + + Sheet.1022 + 0x2000_0000 + + 0x2000_0000 + + Sheet.1023 + 0x1000_0000 + + 0x1000_0000 + + Sheet.1024 + 0x0000_0000 + + 0x0000_0000 + + Sheet.1025 + 0x5000_0000 + + 0x5000_0000 + + Rectangle.1026 + Secure Domain’s local peripherals + + Secure Domain’s local peripherals + + Rectangle.1027 + Application Core’s local peripherals + + Application Core’s local peripherals + + Rectangle.1028 + Radio Core’s local peripherals + + Radio Core’s local peripherals + + Rectangle.1029 + + + + Rectangle.1030 + Global Domain’s global peripherals + + Global Domain’s global peripherals + + Rectangle.1032 + Memory reserved for local aliases + + Memory reserved for local aliases + + Rectangle.1033 + Memory reserved for Secure Domain PROGMEM + + Memory reserved for Secure Domain PROGMEM + + Rectangle.1034 + Memory reserved for Application Core PROGMEM + + Memory reserved for Application Core PROGMEM + + Rectangle.1035 + Memory reserved for Radio Core PROGMEM + + Memory reserved for Radio Core PROGMEM + + Rectangle.1036 + + + + Rectangle.1037 + Global Domain’s program memory (MRAM) + + Global Domain’s program memory (MRAM) + + Rectangle.1038 + Memory reserved for local aliases + + Memory reserved for local aliases + + Rectangle.1039 + Secure Domain local RAM + + Secure Domain local RAM + + Rectangle.1040 + Application Core local RAM + + Application Core local RAM + + Rectangle.1041 + Radio Core local RAM + + Radio Core local RAM + + Rectangle.1042 + + + + Rectangle.1043 + Global Domain’s global peripherals + + Global Domain’s global peripherals + + Rectangle.1044 + Memory reserved for local aliases + + Memory reserved for local aliases + + Sheet.1045 + 0x5000_0000 + + 0x5000_0000 + + Sheet.1046 + 0x4F00_0000 + + 0x4F00_0000 + + Sheet.1047 + 0x4300_0000 + + 0x4300_0000 + + Sheet.1048 + 0x4200_0000 + + 0x4200_0000 + + Sheet.1049 + 0x4100_0000 + + 0x4100_0000 + + Sheet.1050 + 0x4000_0000 + + 0x4000_0000 + + Sheet.1052 + 0x1000_0000 + + 0x1000_0000 + + Sheet.1053 + 0x0E00_0000 + + 0x0E00_0000 + + Sheet.1054 + 0x0400_0000 + + 0x0400_0000 + + Sheet.1055 + 0x0300_0000 + + 0x0300_0000 + + Sheet.1056 + 0x0200_0000 + + 0x0200_0000 + + Sheet.1057 + 0x0100_0000 + + 0x0100_0000 + + Sheet.1058 + 0x0000_0000 + + 0x0000_0000 + + Sheet.1059 + 0x3000_0000 + + 0x3000_0000 + + Sheet.1060 + 0x2F00_0000 + + 0x2F00_0000 + + Sheet.1062 + 0x2300_0000 + + 0x2300_0000 + + Sheet.1063 + 0x2200_0000 + + 0x2200_0000 + + Sheet.1064 + 0x2100_0000 + + 0x2100_0000 + + Sheet.1065 + 0x2000_0000 + + 0x2000_0000 + + Sheet.1073 + + + + Sheet.1074 + + + + Sheet.1075 + + + + Sheet.1076 + 0xB000_0000 + + 0xB000_0000 + + Sheet.1077 + 0x4400_0000 + + 0x4400_0000 + + Sheet.1078 + 0x2400_0000 + + 0x2400_0000 + + diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nRF54H20_radiocore.svg b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nRF54H20_radiocore.svg new file mode 100644 index 000000000000..5ec0ec330229 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nRF54H20_radiocore.svg @@ -0,0 +1,88 @@ + + + + + + + + Page-1 + + Nordic Lake + + + + Nordic Sky + Arm Cortex-M33 256 MHz Fast Start-Stop L1 I-Cache, L1 D-Cache... + + Arm Cortex-M33 256 MHz Fast Start-StopL1 I-Cache, L1 D-CacheTrustZone, FPU, DSP + + Nordic Sky.11 + Multiprotocol 2.4 GHz Radio Bluetooth Low Energy Bluetooth LE... + + Multiprotocol2.4 GHz Radio Bluetooth Low EnergyBluetooth LE Audio Bluetooth mEsh IEEE 802.15.42.4 GHz proprietary protocols + + Nordic Sky.13 + 192 KB RAM + + 192 KB RAM + + Nordic Sky.14 + MVDMA + + MVDMA + + Nordic Sky.15 + AES-128 + + AES-128 + + Nordic Sky.16 + RTC + + RTC + + Nordic Sky.17 + 2x WDT + + 2x WDT + + Nordic Sky.18 + DPPI + + DPPI + + Nordic Sky.19 + Timer + + Timer + + Nordic Sky.20 + MPC + + MPC + + Nordic Sky.21 + SPU + + SPU + + Nordic Sky.22 + IPC + + IPC + + diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_IPC_layers.svg b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_IPC_layers.svg new file mode 100644 index 000000000000..019f21f9dafc --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_IPC_layers.svg @@ -0,0 +1,92 @@ + + + + + + + + + + + + + + + + Page-1 + + Nordic Blue + Communication libraries + + Communication libraries + + Nordic Blue.6 + IPC service library (ipc_service) + + IPC service library (ipc_service) + + Nordic Blue.7 + IPC transport library (icmsg) + + IPC transport library (icmsg) + + Nordic Blue.8 + Shared RAM + + Shared RAM + + Nordic Blue.17 + Signaling hardware + + Signaling hardware + + Sheet.18 + Presentation layer Application layer + + Presentation layer Application layer + + Sheet.20 + Session layer + + Session layer + + Sheet.21 + Transport layer + + Transport layer + + Sheet.22 + Physical layer + + Physical layer + + Dynamic connector + + + + Dynamic connector.27 + + + + Dynamic connector.28 + + + + Dynamic connector.29 + + + + diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_arm_to_vpr.svg b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_arm_to_vpr.svg new file mode 100644 index 000000000000..6fd59c15f38e --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_arm_to_vpr.svg @@ -0,0 +1,117 @@ + + + + + + + + + + + + + + + + Page-1 + + Nordic Lake.9 + Global Domain + + Global Domain + + Nordic Blue.1001 + PPR + + PPR + + Nordic Lake + Application Core + + Application Core + + Nordic Sky + RAM shared buffers + + RAM shared buffers + + Nordic Blue + Peripherals + + Peripherals + + Nordic Sky.11 + BELLBOARD Application Core + + BELLBOARD Application Core + + Nordic Sky.14 + VEVIF + + VEVIF + + Dynamic connector + + + + Dynamic connector.18 + + + + Dynamic connector.19 + + + + Dynamic connector.21 + + + + Dynamic connector.25 + + + + Nordic Blue.27 + + + + Dynamic connector.28 + + + + Dynamic connector.29 + + + + Sheet.28 + BUS system IRQ system + + BUS system IRQ system + + Nordic Sky.1000 + VPR core + + VPR core + + Dynamic connector.1002 + + + + diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_cpu_to_cpu.svg b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_cpu_to_cpu.svg new file mode 100644 index 000000000000..8bf4beb62020 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_cpu_to_cpu.svg @@ -0,0 +1,149 @@ + + + + + + + + + + + + + + + + + + + Page-1 + + Nordic Lake + Application Core + + Application Core + + Nordic Lake.7 + Radio Core + + Radio Core + + Nordic Lake.8 + Secure Domain + + Secure Domain + + Nordic Lake.9 + Global Domain + + Global Domain + + Nordic Sky + RAM shared buffers + + RAM shared buffers + + Nordic Blue + Peripherals + + Peripherals + + Nordic Sky.12 + BELLBOARD Application Core + + BELLBOARD Application Core + + Nordic Sky.13 + BELLBOARD Radio Core + + BELLBOARD Radio Core + + Nordic Sky.14 + BELLBOARD Secure Domain + + BELLBOARD Secure Domain + + Dynamic connector + + + + Dynamic connector.17 + + + + Dynamic connector.18 + + + + Dynamic connector.19 + + + + Dynamic connector.20 + + + + Dynamic connector.21 + + + + Dynamic connector.22 + + + + Dynamic connector.23 + + + + Dynamic connector.24 + + + + Dynamic connector.25 + + + + Dynamic connector.26 + + + + Nordic Blue.27 + + + + Dynamic connector.28 + + + + Dynamic connector.29 + + + + Sheet.30 + BUS system IRQ system + + BUS system IRQ system + + diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_app.png b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_app.png new file mode 100644 index 000000000000..744683cd57b2 Binary files /dev/null and b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_app.png differ diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_app.svg b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_app.svg new file mode 100644 index 000000000000..cb7f8d76927c --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_app.svg @@ -0,0 +1,48 @@ + + + + + + + + Page-1 + + Rectangle.1000 + Free memory + + Free memory + + Rectangle.1001 + Application Core’s non-secure data (optional, planned) + + Application Core’s non-secure data (optional, planned) + + Rectangle.1002 + Application Core’s secure data + + Application Core’s secure data + + Sheet.1003 + 0x2200_8000 + + 0x2200_8000 + + Sheet.1006 + 0x2200_0000 + + 0x2200_0000 + + diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_bbproc.svg b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_bbproc.svg new file mode 100644 index 000000000000..d46b0c22e74d --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_bbproc.svg @@ -0,0 +1,46 @@ + + + + + + + + Page-1 + + Rectangle.1014 + BBPROC data + + BBPROC data + + Rectangle.1015 + BBPROC code + + BBPROC code + + Rectangle.1020 + BBPROC ↔ Radio Core IPC shared memory + + BBPROC ↔ Radio Core IPC shared memory + + Sheet.1027 + 0x2301_8000 + + 0x2301_8000 + + Sheet.1032 + 0x2301_1000 + + 0x2301_1000 + + diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_mram10.png b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_mram10.png new file mode 100644 index 000000000000..387e74596cff Binary files /dev/null and b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_mram10.png differ diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_mram10.svg b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_mram10.svg new file mode 100644 index 000000000000..693f5ff6b4ca --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_mram10.svg @@ -0,0 +1,91 @@ + + + + + + + + + + + + + + + + Page-1 + + Rectangle.40 + System Controller's and Secure Domain’s code and data + + System Controller's and Secure Domain’s code and data + + Rectangle.44 + Radio Core's secure code + + Radio Core's secure code + + Rectangle.46 + Radio Core's secure/non-secure callable + + Radio Core's secure/non-secure callable + + Rectangle.48 + Radio Core's non-secure code + + Radio Core's non-secure code + + Rectangle.50 + Application Core's secure code + + Application Core's secure code + + Rectangle.52 + Application Core's secure/non-secure callable + + Application Core's secure/non-secure callable + + Rectangle.54 + Application Core's non-secure code + + Application Core's non-secure code + + Dynamic connector.56 + May extend to MRAM_11 + + May extend to MRAM_11 + + Sheet.1000 + 0x0E10_0000 + + 0x0E10_0000 + + Sheet.1001 + 0x0E05_4000 + + 0x0E05_4000 + + Sheet.1003 + 0x0E00_0000 + + 0x0E00_0000 + + diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_mram11.png b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_mram11.png new file mode 100644 index 000000000000..87422cdebe22 Binary files /dev/null and b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_mram11.png differ diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_mram11.svg b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_mram11.svg new file mode 100644 index 000000000000..1eb8a4e2bb89 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_mram11.svg @@ -0,0 +1,59 @@ + + + + + + + + Page-1 + + Rectangle.27 + Application Core's non-secure code (planned) + + Application Core's non-secure code (planned) + + Rectangle.30 + Application Core's non-volatile storage + + Application Core's non-volatile storage + + Rectangle.33 + Radio Core's non-volatile storage + + Radio Core's non-volatile storage + + Rectangle.54 + Secure Domain's non-volatile storage (planned) + + Secure Domain's non-volatile storage (planned) + + Rectangle.55 + DFU storage bank + + DFU storage bank + + Sheet.1017 + 0x0E20_0000 + + 0x0E20_0000 + + Sheet.1018 + 0x0E10_0000 + + 0x0E10_0000 + + diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_radio.png b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_radio.png new file mode 100644 index 000000000000..b1262cf2422b Binary files /dev/null and b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_radio.png differ diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_radio.svg b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_radio.svg new file mode 100644 index 000000000000..b79cce65c316 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_radio.svg @@ -0,0 +1,48 @@ + + + + + + + + Page-1 + + Rectangle.1000 + Free memory + + Free memory + + Rectangle.1001 + Radio Core’s non-secure data (optional, planned) + + Radio Core’s non-secure data (optional, planned) + + Rectangle.1002 + Radio Core’s secure data + + Radio Core’s secure data + + Sheet.1003 + 0x2301_8000 + + 0x2301_8000 + + Sheet.1004 + 0x2300_0000 + + 0x2300_0000 + + diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_ram0x.png b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_ram0x.png new file mode 100644 index 000000000000..510e9f002313 Binary files /dev/null and b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_ram0x.png differ diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_ram0x.svg b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_ram0x.svg new file mode 100644 index 000000000000..52df0e78635b --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_ram0x.svg @@ -0,0 +1,90 @@ + + + + + + + + Page-1 + + Rectangle.5 + Free memory + + Free memory + + Rectangle.1 + Secure Domain ↔ Application Core IPC shared memory + + Secure Domain ↔ Application Core IPC shared memory + + Rectangle.7 + Secure Domain's secure data + + Secure Domain's secure data + + Rectangle.10 + Application Core's secure data + + Application Core's secure data + + Rectangle.11 + Radio Core's non-secure data (optional, planned) + + Radio Core's non-secure data (optional, planned) + + Rectangle.18 + Secure Domain ↔ Radio Core IPC shared memory + + Secure Domain ↔ Radio Core IPC shared memory + + Rectangle.20 + Radio Core's secure data (planned) + + Radio Core's secure data (planned) + + Rectangle.22 + Application Core ↔ Radio Core IPC shared memory + + Application Core ↔ Radio Core IPC shared memory + + Rectangle.24 + Application Core's non-secure data (optional, planned) + + Application Core's non-secure data (optional, planned) + + Rectangle.26 + Secure Domain's non-secure data (planned) + + Secure Domain's non-secure data (planned) + + Sheet.1000 + 0x2F0E_0000 + + 0x2F0E_0000 + + Sheet.1001 + 0x2F00_0000 + + 0x2F00_0000 + + diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_ram20.png b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_ram20.png new file mode 100644 index 000000000000..627552f3c791 Binary files /dev/null and b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_ram20.png differ diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_ram20.svg b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_ram20.svg new file mode 100644 index 000000000000..8c6cced60f9e --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_ram20.svg @@ -0,0 +1,155 @@ + + + + + + + + Page-1 + + Rectangle.1 + System Controller data + + System Controller data + + Rectangle.7 + System Controller code + + System Controller code + + Rectangle.12 + System Controller’s ROM data + + System Controller’s ROM data + + Rectangle.13 + System Controller → Radio Core IPC shared memory + + System Controller → Radio Core IPC shared memory + + Rectangle.15 + System Controller ← Radio Core IPC shared memory + + System Controller ← Radio Core IPC shared memory + + Rectangle.17 + Radio Core’s mngMBOX (planned) + + Radio Core’s mngMBOX (planned) + + Rectangle.19 + System Controller → Application Core IPC shared memory + + System Controller → Application Core IPC shared memory + + Rectangle.21 + System Controller ← Application Core IPC shared memory + + System Controller ← Application Core IPC shared memory + + Rectangle.23 + Application Core’s mngMBOX (planned) + + Application Core’s mngMBOX (planned) + + Rectangle.25 + System Controller → Secure Domain IPC shared memory + + System Controller → Secure Domain IPC shared memory + + Rectangle.27 + System Controller ← Secure Domain IPC shared memory + + System Controller ← Secure Domain IPC shared memory + + Rectangle.31 + System Controller’s mngMBOX (planned) + + System Controller’s mngMBOX (planned) + + Sheet.1001 + 0x2F89_0000 + + 0x2F89_0000 + + Sheet.1002 + 0x2F88_FF00 + + 0x2F88_FF00 + + Sheet.1003 + 0x2F88_FE80 + + 0x2F88_FE80 + + Sheet.1004 + 0x2F88_FE00 + + 0x2F88_FE00 + + Sheet.1005 + 0x2F88_FDE0 + + 0x2F88_FDE0 + + Sheet.1006 + 0x2F88_FD60 + + 0x2F88_FD60 + + Sheet.1007 + 0x2F88_FCE0 + + 0x2F88_FCE0 + + Sheet.1008 + 0x2F88_FCC0 + + 0x2F88_FCC0 + + Sheet.1009 + 0x2F88_FC40 + + 0x2F88_FC40 + + Sheet.1010 + 0x2F88_FBC0 + + 0x2F88_FBC0 + + Sheet.1011 + 0x2F88_FBA0 + + 0x2F88_FBA0 + + Sheet.1012 + 0x2F88_BBA0 + + 0x2F88_BBA0 + + Sheet.1013 + 0x2F88_0000 + + 0x2F88_0000 + + diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_ram21.png b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_ram21.png new file mode 100644 index 000000000000..8a6de2af67b7 Binary files /dev/null and b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_ram21.png differ diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_ram21.svg b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_ram21.svg new file mode 100644 index 000000000000..59140520e4d6 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_ram21.svg @@ -0,0 +1,59 @@ + + + + + + + + Page-1 + + Rectangle.5 + Free memory + + Free memory + + Rectangle.1 + FLPR data (planned) + + FLPR data (planned) + + Rectangle.7 + FLPR code (planned) + + FLPR code (planned) + + Rectangle.12 + FLPR ↔ Application Core IPC shared memory (planned) + + FLPR ↔ Application Core IPC shared memory (planned) + + Rectangle.16 + EasyDMA buffers for fast peripherals: CAN, UARTE, SPI, I3C + + EasyDMA buffers for fast peripherals: CAN, UARTE, SPI, I3C + + Sheet.1000 + 0x2F89_8000 + + 0x2F89_8000 + + Sheet.1001 + 0x2F89_0000 + + 0x2F89_0000 + + diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_ram3x.png b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_ram3x.png new file mode 100644 index 000000000000..5f38546b3512 Binary files /dev/null and b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_ram3x.png differ diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_ram3x.svg b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_ram3x.svg new file mode 100644 index 000000000000..a0ff0b9838d5 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_ram3x.svg @@ -0,0 +1,63 @@ + + + + + + + + Page-1 + + Rectangle.1013 + Free memory + + Free memory + + Rectangle.1014 + PPR data + + PPR data + + Rectangle.1015 + PPR code + + PPR code + + Rectangle.1020 + PPR ↔ Application Core IPC shared memory + + PPR ↔ Application Core IPC shared memory + + Rectangle.1022 + Radio Core's EasyDMA buffers + + Radio Core's EasyDMA buffers + + Rectangle.1024 + Application Core's EasyDMA buffers for slow peripherals + + Application Core's EasyDMA buffers for slow peripherals + + Sheet.1027 + 0x2FC0_8000 + + 0x2FC0_8000 + + Sheet.1032 + 0x2FC0_0000 + + 0x2FC0_0000 + + diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_secure.png b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_secure.png new file mode 100644 index 000000000000..3d1cfbd347db Binary files /dev/null and b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_secure.png differ diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_secure.svg b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_secure.svg new file mode 100644 index 000000000000..aabcca969c19 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memory_map_secure.svg @@ -0,0 +1,36 @@ + + + + + + + + Page-1 + + Rectangle.1001 + Secure Domain’s data + + Secure Domain’s data + + Sheet.1010 + 0x2100_8000 + + 0x2100_8000 + + Sheet.1011 + 0x2100_0000 + + 0x2100_0000 + + diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memorymap.png b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memorymap.png new file mode 100644 index 000000000000..1f5d0edc84a1 Binary files /dev/null and b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_memorymap.png differ diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_default_manifest_topology.png b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_default_manifest_topology.png new file mode 100644 index 000000000000..ffe7f73da250 Binary files /dev/null and b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_default_manifest_topology.png differ diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_envelope_structure.png b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_envelope_structure.png new file mode 100644 index 000000000000..18a23494b04a Binary files /dev/null and b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_envelope_structure.png differ diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_example_update_package.png b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_example_update_package.png new file mode 100644 index 000000000000..573e4dc18adc Binary files /dev/null and b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_example_update_package.png differ diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_example_update_process.png b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_example_update_process.png new file mode 100644 index 000000000000..925594025f96 Binary files /dev/null and b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_example_update_process.png differ diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_example_update_workflow.png b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_example_update_workflow.png new file mode 100644 index 000000000000..ad6eba9a2a16 Binary files /dev/null and b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_example_update_workflow.png differ diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_generator_workflow.png b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_generator_workflow.png new file mode 100644 index 000000000000..8c37deb55c68 Binary files /dev/null and b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_generator_workflow.png differ diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_invocation_workflow.png b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_invocation_workflow.png new file mode 100644 index 000000000000..67178285a6c6 Binary files /dev/null and b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_invocation_workflow.png differ diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_manifest_topology.png b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_manifest_topology.png new file mode 100644 index 000000000000..97600e9eca92 Binary files /dev/null and b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_manifest_topology.png differ diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_mcuboot_comparison.png b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_mcuboot_comparison.png new file mode 100644 index 000000000000..f89cef11177e Binary files /dev/null and b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_mcuboot_comparison.png differ diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_update_workflow.png b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_update_workflow.png new file mode 100644 index 000000000000..e8822685346a Binary files /dev/null and b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/nrf54h20_suit_update_workflow.png differ diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/thread_platform_design_nRF54h20.svg b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/thread_platform_design_nRF54h20.svg new file mode 100644 index 000000000000..6e0f5acbc84c --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/thread_platform_design_nRF54h20.svg @@ -0,0 +1,252 @@ + + + + + + + + + + + + + + + + + + + Page-1 + + Sheet.1015 + + + + Sheet.661 + + + + Dynamic connector.1022 + + + + Sheet.662 + nRF54H20 Application Core + + nRF54H20 Application Core + + Sheet.663 + Application + + Application + + Sheet.699 + Zephyr integration + + Zephyr integration + + Sheet.701 + Secure boot + + Sheet.702 + + + + Zephyr integration + + + Sheet.1016 + nRF54H20 Radio Core + + nRF54H20 Radio Core + + Sheet.1018 + Multiprotocol Service Layer (MPSL) + + Multiprotocol Service Layer (MPSL) + + Sheet.1023 + OpenAMP (Spinel) + + OpenAMP (Spinel) + + Sheet.1007 + + + + Sheet.1008 + nRF IEEE 802.15.4 radio driver + + nRF IEEE 802.15.4radio driver + + Sheet.1009 + IEEE 802.15.4 PHY + + IEEE 802.15.4 PHY + + Sheet.1072 + + Sheet.667 + + + + Sheet.668 + Thread stack (OpenThread) + + Thread stack (OpenThread) + + + Sheet.1073 + + Sheet.703 + + + + Sheet.704 + nRF IEEE 802.15.4 radio driver + + nRF IEEE 802.15.4 radio driver + + + Sheet.1074 + + + + Sheet.1075 + nRF54H20 Secure Domain + + nRF54H20 Secure Domain + + Sheet.1081 + Cryptographically Secure Pseudo Random Number Generator + + Cryptographically Secure Pseudo Random Number Generator + + Sheet.1082 + Cryptography + + Cryptography + + Sheet.1083 + Key management + + Key management + + Sheet.1084 + + Sheet.1079 + + + + Sheet.1080 + Device Firmware Update + + Device Firmware Update + + + Sheet.1085 + + Sheet.1077 + + + + Sheet.1078 + Secure storage + + Secure storage + + + Dynamic connector.1086 + + + + Dynamic connector.1087 + + + + Dynamic connector.1088 + + + + Dynamic connector.1089 + + + + Dynamic connector.1090 + + + + Sheet.1091 + PSA Crypto API + + PSA Crypto API + + Sheet.1092 + PSA Crypto API + + PSA Crypto API + + Sheet.1093 + Remote Procedure Call + + Remote Procedure Call + + Sheet.1094 + (nRF RPC; between domains) + + (nRF RPC; between domains) + + Sheet.1095 + (Thread security mgmt) + + (Thread security mgmt) + + Sheet.1096 + (Matter security mgmt) + + (Matter security mgmt) + + Sheet.1097 + Remote Procedure Call + + Remote Procedure Call + + Sheet.1098 + (nRF RPC; between domains) + + (nRF RPC; between domains) + + Sheet.1099 + PSA Crypto API + + PSA Crypto API + + Sheet.1100 + (Radio security mgmt) + + (Radio security mgmt) + + diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/images/thread_platform_design_nRF54h20_multi.svg b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/thread_platform_design_nRF54h20_multi.svg new file mode 100644 index 000000000000..a076c32768ae --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/images/thread_platform_design_nRF54h20_multi.svg @@ -0,0 +1,296 @@ + + + + + + + + + + + + + + + + + + + Page-1 + + Sheet.1015 + + + + Sheet.661 + + + + Sheet.1071 + + Sheet.665 + + + + Sheet.666 + Bluetooth® LE stack + + Bluetooth® LE stack + + + Dynamic connector.1022 + + + + Sheet.662 + nRF54H20 Application Core + + nRF54H20 Application Core + + Sheet.663 + Application + + Application + + Sheet.699 + Zephyr integration + + Zephyr integration + + Sheet.701 + Secure boot + + Sheet.702 + + + + Zephyr integration + + + Sheet.780 + + Sheet.683 + + + + Sheet.764 + Zephyr host + + Zephyr host + + + Sheet.1016 + nRF54H20 Radio Core + + nRF54H20 Radio Core + + Sheet.1018 + Multiprotocol Service Layer (MPSL) + + Multiprotocol Service Layer (MPSL) + + Sheet.1023 + OpenAMP (Spinel) + + OpenAMP (Spinel) + + Dynamic connector.1025 + + + + Sheet.1024 + OpenAMP (HCI) + + OpenAMP (HCI) + + Sheet.1011 + + + + Sheet.1013 + nRF Bluetooth® LE Controller + + nRF Bluetooth® LE Controller + + Sheet.1007 + + + + Sheet.1008 + nRF IEEE 802.15.4 radio driver + + nRF IEEE 802.15.4radio driver + + Sheet.1009 + IEEE 802.15.4 PHY + + IEEE 802.15.4 PHY + + Sheet.1072 + + Sheet.667 + + + + Sheet.668 + Thread stack (OpenThread) + + Thread stack (OpenThread) + + + Sheet.1073 + + Sheet.703 + + + + Sheet.704 + nRF IEEE 802.15.4 radio driver + + nRF IEEE 802.15.4 radio driver + + + Sheet.1074 + + + + Sheet.1075 + nRF54H20 Secure Domain + + nRF54H20 Secure Domain + + Sheet.1081 + Cryptographically Secure Pseudo Random Number Generator + + Cryptographically Secure Pseudo Random Number Generator + + Sheet.1082 + Cryptography + + Cryptography + + Sheet.1083 + Key management + + Key management + + Sheet.1084 + + Sheet.1079 + + + + Sheet.1080 + Device Firmware Update + + Device Firmware Update + + + Sheet.1085 + + Sheet.1077 + + + + Sheet.1078 + Secure storage + + Secure storage + + + Dynamic connector.1086 + + + + Dynamic connector.1087 + + + + Dynamic connector.1088 + + + + Dynamic connector.1089 + + + + Dynamic connector.1090 + + + + Sheet.1091 + PSA Crypto API + + PSA Crypto API + + Sheet.1092 + PSA Crypto API + + PSA Crypto API + + Sheet.1093 + Remote Procedure Call + + Remote Procedure Call + + Sheet.1094 + (nRF RPC; between domains) + + (nRF RPC; between domains) + + Sheet.1095 + (Thread security mgmt) + + (Thread security mgmt) + + Sheet.1096 + (Matter security mgmt) + + (Matter security mgmt) + + Sheet.1097 + Remote Procedure Call + + Remote Procedure Call + + Sheet.1098 + (nRF RPC; between domains) + + (nRF RPC; between domains) + + Sheet.1099 + PSA Crypto API + + PSA Crypto API + + Sheet.1100 + (Radio security mgmt) + + (Radio security mgmt) + + diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/nrf54h20_glossary.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/nrf54h20_glossary.rst new file mode 100644 index 000000000000..415b44260e00 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/nrf54h20_glossary.rst @@ -0,0 +1,139 @@ +:orphan: + +.. _nrf54h20_glossary: + +Glossary +######## + +.. contents:: + :local: + :depth: 2 + +.. glossary:: + :sorted: + + Advanced eXtensible Interface (AXI) Communication + A system that transfers data between components inside a computer or between computers. + + BELLBOARD + A peripheral associated with a given core that provides support for the inter-domain SW signaling. + It includes a set of tasks and events intended for signaling within an interprocessor communication (IPC) framework. + + Bill of materials (BoM) + List of the raw materials, sub-assemblies, intermediate assemblies, sub-components, parts, and the quantities of each needed to manufacture an end product. + + Core + Subsets of domains. + Most memory and peripherals can be flexibly allocated to cores at compile time. + + CRACEN + A hardware cryptographic engine within nRF54H devices. + + Easy Direct Memory Access (EasyDMA) + A module that some peripherals implement to gain direct access to data RAM. + + Enhanced ShockBurst (ESB) + A basic protocol supporting two-way data packet communication including packet buffering, packet acknowledgment, and automatic retransmission of lost packets. + ESB provides radio communication with low power consumption. + The implementation is small in code size and easy to use. + + External Memory Interface Encryption Engine (EXMEE) + A peripheral that supports on-the-fly encryption and authentication for the memory connected to EXMIF. + The AES tweaked mode is used to provide encryption, and one of single hash, granular hash, or Merkle tree is used to provide authentication, using the SHA3 algorithm. + + External Memory Interface (EXMIF) + A bus protocol for communication from an integrated circuit, such as a microprocessor, to an external memory device located on a circuit board. + + Domain + Functional blocks included in the system/SoC. + Contains the user-programmable main CPU and associated functions. + + Dynamic Voltage and Frequency Scaling (DVFS) + A power management technique that allows adjusting the operating voltage and operating frequency of a CPU, depending on the workload. + + Fully Depleted Silicon-on-Insulator (FD-SOI) + A type of SOI technology that uses a thin layer of silicon that is fully depleted of electrons. + + Frequency-locked loop (FLL) + An electronic control system that generates a signal that is locked to the frequency of an input or "reference" signal. + + Fast Lightweight Processor (FLPR, pronounced “Flipper”) + A processor that is located in the high-speed portion of the Global Domain primarily intended to implement software-defined peripheral functions. + + Interprocessor Communication Transceiver (IPCT) + A peripheral used for direct signalling between peripherals in other domains. + + Spin-Transfer Torque Magneto-Resistive Random Access Memory (MRAM (STT-MRAM)) + An alternative non-volatile memory (NVM) to flash memory. + Compared to flash, MRAM does not have to be erased before writing and can simply be written, making it easier to use. + + Memory Privilege Controller (MPC) + Performs security configuration, enforcement, and bus decoding. + It implements security filtering, checking bus accesses against the configured access properties and blocking any unauthorized accesses. + + Memory-to-memory Vector Direct Memory Access (MVDMA) + A peripheral capable of copying data from one memory address to another memory address. + It is not a complement to the EasyDMA (:term:`Easy Direct Memory Access (EasyDMA)`). + The scatter-gather property applies to MVDMA as well. + + Peripheral Processor (PPR, pronounced “Pepper”) + A processor that is located in the low-leakage portion of the Global Domain and is primarily intended to: + + * Handle peripherals in low-power states while the main processors are in sleep mode. + * Coordinate peripherals. + * Implement low-level protocols for communicating with sensors and actuators + + Platform Security Architecture Certified (PSA Certified) + A security certification scheme for Internet of Things (IoT) hardware, software and devices. + + Power Management Service + A service that automatically handles the settings described by an application. + It decides how registers will be retained, which parts of the device are put into what mode, and what clock signals are running. + + Physically Unclonable Function (PUF) + A function device that exploits inherent randomness introduced during manufacturing to give a physical entity a unique "fingerprint" or a trust anchor. + + Quad Serial Peripheral Interface (QSPI) + A peripheral that provides support for communicating with an external flash memory device using SPI. + + Secure domain (SecDom) + A dedicated domain which executes a pre-compiled firmware component that is signed by Nordic Semiconductor. + It exposes security services to the other cores through an IPC interface. + + Serial Peripheral Interface (SPI) + An interface bus commonly used to send data between microcontrollers and small peripherals such as shift registers, sensors, and SD cards. + + Serial Peripheral Interface Master (SPIM) + A peripheral that can communicate with multiple slaves using individual chip select signals for each of the slave devices attached to a bus. + + Serial Peripheral Interface Slave (SPIS) + A peripheral used for ultra-low power serial communication from an external SPI master. + + System Controller + A VPR that implements system startup and power management functionalities that in the past would have been implemented in hardware. + + Tightly Coupled Memory (TCM) + Part of RAM which provides a low-latency memory access that the core can use with predictable access time. + Unlike cached memories for which the access latency is unpredictable. + + TIMER + A peripheral that runs on the high-frequency clock source (HFCLK) and includes a four-bit (1/2X) prescaler that can divide the timer input clock from the HFCLK controller. + It can operate in two modes: timer and counter. + + TrustZone + Provides a cost-effective methodology to isolate security-critical components in an ARM Cortex CPU by hardware separating a rich operating system from smaller, secure operating system. + + Trusted Third Party (TTP) + An entity which facilitates interactions between two parties who both trust the third party. + + VPR Core (pronounced “Viper”) + A core that is compatible with the RISC-V instruction set, meaning the industry-standard RISC-V development tools can be used. + VPR implements the RV32E instruction set (Base Integer Instruction Set (embedded) - 32 bit, 16 registers) and the following extensions: + + * M: Multiply and divide extension + * C: Compressed extension (compressed instructions) + + The nRF54H20 PDK uses several VPR cores: :term:`Fast Lightweight Processor (FLPR, pronounced “Flipper”)`, :term:`Peripheral Processor (PPR, pronounced “Pepper”)` and :term:`System Controller`. + + VPR Event Interface (VEVIF) + A real-time peripheral that allows interaction with the VPR's interrupts and the PPI system in the domain where the VPR is instantiated. diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_app_samples.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_app_samples.rst new file mode 100644 index 000000000000..1f0f479f9554 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_app_samples.rst @@ -0,0 +1,78 @@ +:orphan: + +.. _ug_nrf54h20_app_samples: + +nRF54H20 applications and samples +################################# + +.. contents:: + :local: + :depth: 2 + +This page outlines the available samples for the nRF54H20. +It includes the nRF Connect SDK samples and nRF Connect SDK application sections that showcase how to implement typical use cases with Nordic Semiconductor libraries and drivers. +Additionally, the page lists the available Zephyr samples that are compatible with the nRF54H20. +You can also find these in Zephyr’s Samples and Demos documentation. + +|NCS| samples +************* + +The following |NCS| samples have been developed and tested on the nRF54H20: + +* :ref:`multicore_hello_world` +* :ref:`central_and_peripheral_hrs` +* :ref:`bluetooth_central_hids` +* :ref:`central_uart` +* :ref:`peripheral_hids_keyboard` +* :ref:`peripheral_hids_mouse` +* :ref:`peripheral_uart` +* :ref:`ble_throughput` +* :ref:`peripheral_rscs` +* :ref:`peripheral_lbs` +* :ref:`direct_test_mode` +* :ref:`matter_lock_sample` +* :ref:`matter_template_sample` +* :ref:`ot_cli_sample` +* ``esb_prx_ptx`` +* :ref:`radio_test` +* :ref:`caf_sensor_manager_sample` +* :ref:`ipc_service_sample` +* :ref:`event_manager_proxy_sample` +* ``nrf54h_suit_sample`` +* :ref:`record_launch_app` +* :ref:`record_text` +* :ref:`nfc_shell` +* :ref:`writable_ndef_msg` +* :ref:`crypto_aes_cbc` +* :ref:`crypto_aes_ccm` +* :ref:`crypto_aes_ctr` +* :ref:`crypto_aes_gcm` +* :ref:`crypto_chacha_poly` +* :ref:`crypto_ecdh` +* :ref:`crypto_ecdsa` +* :ref:`crypto_hkdf` +* :ref:`crypto_hmac` +* :ref:`crypto_rng` +* :ref:`crypto_rsa` +* :ref:`crypto_sha256` + +|NCS| applications +****************** + +The following |NCS| application has been developed and tested on the nRF54H20: + +* :ref:`nrf_machine_learning_app` +* :ref:`nrf_desktop` +* ``nrf_tbr_app`` + +Zephyr samples +************** + +The following Zephyr samples have been developed and tested on the nRF54H20: + +* :zephyr:code-sample:`blinky` +* :ref:`zephyr:peripheral_hr` +* :ref:`zephyr:bluetooth_central_hr` +* :ref:`zephyr:bluetooth-hci-ipc-sample` +* ``zephyr:coremark_sample`` +* ``zephyr:qdec_sensor`` diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture.rst new file mode 100644 index 000000000000..ed06e65ea844 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture.rst @@ -0,0 +1,26 @@ +:orphan: + +.. _ug_nrf54h20_architecture: + +Architecture of nRF54H20 +######################## + +.. contents:: + :local: + :depth: 2 + +The nRF54H20 is a multicore System-on-Chip (SoC) that uses an asymmetric multiprocessing (AMP) configuration. +Each core is tasked with specific responsibilities, and is optimized for different workloads. + +The following pages briefly describe topics like the responsibilities of the cores, their interprocessor interactions, the memory mapping, and the boot sequence in nRF54H20. + +.. toctree:: + :maxdepth: 2 + :caption: Subpages: + + ug_nrf54h20_architecture_intro + ug_nrf54h20_architecture_cpu + ug_nrf54h20_architecture_memory + ug_nrf54h20_architecture_ipc + ug_nrf54h20_architecture_boot + ug_nrf54h20_architecture_lifecycle diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_boot.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_boot.rst new file mode 100644 index 000000000000..2c554690bd8e --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_boot.rst @@ -0,0 +1,87 @@ +:orphan: + +.. _ug_nrf54h20_architecture_boot: + +nRF54H20 Boot Sequence +###################### + +.. contents:: + :local: + :depth: 2 + +The nRF54H20 startup procedure can be performed in two scenarios: + + * Cold boot + * Warm boot + +During cold boot the system has no state retained in its RAM memory or hardware registers and performs full initialization. +This procedure is performed on following events: + + * Power on reset + * Pin reset + * System Controller watchdog reset + * Ctrl-AP reset (debugging Secure Domain or System Controller) + * Secure Domain reset request + * Secure Domain watchdog reset + * Tamper detection + +Warm boot is performed when system is being woken up from a deep sleep (system off with RAM retention). +The state of the system is retained in RAM. +This procedure is faster than cold boot, because content of the memories represents operational state of the system. +The procedure requires only restoring the state of hardware peripherals and registers. +The triggers of the warm boot procedure are: + + * GPIO event + * LPCOMP event + * NFC field detection + * USB VBUS rising + * Entering the debug interface mode + * GRTC event + +Cold Boot Sequence +****************** + +The nRF54H20 boot sequence has two key characteristics: + +* An immutable boot ROM provides the initial root-of-trust (RoT). + This boot ROM is responsible for verifying the secure domain firmware signature before allowing the code to be executed. +* The secure domain acts as the boot master in the system. + It completes the allocation of all the global resources before any other local domain is allowed to execute. + This order of operation is needed for robustness and security of the system. + It ensures that global resources are allocated for other local domains before any of them has opportunity to access global resources (correct access to allocated resources, or tries of malicious access to resources owned by other domains). + +Boot stages +*********** + +The Secure Domain boots the System Controller, the Application Core, and the Radio Core: + +* VPRs (PPR, FLPR, BBPROC) are started by their owners when the owners decide. +* PPR and FLPR are owned by the Application Core in most applications, but any of them can be reassigned to the Radio Core. + +See the following overview of the boot sequence, where the left-most block indicates what starts first from when power-on reset is applied. + +.. figure:: images/nRF54H20_bootsequence.svg + :alt: Boot sequence of the nRF54H20 + + Boot order of the nRF54H20 + +The following is a description of the boot sequence steps: + +1. Immediately after reset, the SysCtrl CPU starts executing code from a ROM memory in Global Domain. + This ROM code perform chip calibration, like trim and power-up the MRAM macro. + This ROM code does not affect the runtime services offered by SysCtrl firmware during the secondary boot stage. + +#. The SysCtrl ROM powers up the secure domain and then halts. + +#. The secure domain is taken out of reset (as the first local domain), and the Cortex-M33 CPU inside the secure domain automatically starts executing code from a local ROM memory. + As the MRAM is now calibrated and working correctly, the secure domain ROM can perform signature verification of the secure domain firmware components installed into the MRAM. + The secure domain ROM also configures the device according to the current life-cycle state (LCS) and extracts silicon-unique fingerprints from the physical unclonable function (PUF) in GD , retaining this inside CRACEN. + +#. If the secure domain firmware signature is valid, the secure domain ROM reconfigures ROM memory as non-executable and non-readable and then branches into the firmware stored in MRAM. + This is the first step of the primary boot stage where a user-installable firmware component is executed by any CPU in the system. + +#. At the end of the primary boot stage, the secure domain firmware configures and restricts access to all global resources, and initiates the secondary boot stage. + +#. In the secondary boot stage, SysCtrl and other local domains are released from reset and in parallel start to execute their respective MRAM firmware components. + +#. Each of the local domains is responsible to configure its local resources partitioning. diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_cpu.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_cpu.rst new file mode 100644 index 000000000000..5b3cd84df08c --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_cpu.rst @@ -0,0 +1,180 @@ +:orphan: + +.. _ug_nrf54h20_architecture_cpu: + +nRF54H20 Domains +################ + +.. contents:: + :local: + :depth: 2 + +The nRF54H20 is partitioned into functional blocks, called *Domains*. +The domains containing the user-programmable main CPUs and associated functions are called *Cores*. +Most memory and peripherals can be flexibly allocated to cores at compile time. +To make this possible, the memory and peripherals are located in a separate area called the Global Domain. +Security functions are centralized into the Secure Domain. + +The following image shows the domains in the nRF54H20: + +.. figure:: images/nRF54H20_Domains.svg + :alt: nRF54H20 Domains + + nRF54h20 Domains + +The CPU cores in the nRF54H20 are based on two types of CPU architectures: + +* Arm Cortex-M33. +* RISC-V (VPR cores). + The VPR (pronounced “Viper”) is a small, efficient CPU developed by Nordic Semiconductor. + It is compatible with the RISC-V instruction set. + +Application Core +**************** + +The following image shows the Application Core in the final silicon: + +.. figure:: images/nRF54H20_appcore.svg + :alt: Application Core + + Application Core + +The Application Core contains the Arm Cortex-M33 CPU with the highest processing power in the system. +Its purpose is to run the main application. +It is also designed to have the highest active power efficiency, meaning it can run computing-intensive operations at an optimal power consumption. + +Due to Dynamic Voltage and Frequency Scaling (DVFS) support and power efficiency optimizations, it takes some time for it to start and stop. +That is why the workloads that require frequent starting and stopping are better suited to run either on the Radio Core or the PPR and FLPR processors. + +Moreover, the clock speed of the processor is very high compared to the low-leakage peripherals running at 16 MHz. +This means that in a code frequently accessing peripheral registers, the Application Core wastes multiple cycles waiting for the peripherals to respond. +Code requiring a lot of accesses to low-leakage peripherals in the Global Domain is better suited to run on the PPR processor if efficiency is a key concern. + +32 kB of local RAM, which is configured like a Tightly Coupled Memory (TCM) and is accessible single-cycle, is provided. +This can be used by timing-sensitive code that cannot tolerate variable latency due to cache hits/misses when accessing memory. + +.. note:: + During the initial limited sampling, the firmware to change DVFS settings will not be available, and all code will run at the maximum clock frequency. + Dynamic switching of voltage and frequency will be enabled at a later date. + In later versions, developers will be able to select an optimal clock frequency at run time, depending on the task at hand. + +Radio Core +********** + +The following image shows the Radio Core in the final silicon: + +.. figure:: images/nRF54H20_radiocore.svg + :alt: Radio Core + + Radio Core + +The Radio Core is intended to run the radio protocol stacks, such as Bluetooth Low Energy, IEEE 802.15.4, Thread, Enhanced ShockBurst (ESB), or other proprietary protocols. +It is also possible to implement a combination of protocols that use multiprotocol support. + +.. note:: + IEEE 802.15.4 will not be supported for the initial limited sampling. + +Any remaining processing power of this core can be used for tasks other than the ones required by the radio protocol stacks. + +The main CPU in the Radio Domain is an Arm Cortex-M33 running at a fixed clock speed of 256 MHz and is optimized for quick starts and stops, which are frequent in protocol stack workloads. +Other workloads with similar characteristics are also well suited for running on the Radio Core. + +.. note:: + The protocol stack software may need to run at the highest priority to meet its timing requirements. + If that is the case, the user code needs to run at lower priority. + +The Radio Core has 192 kB of local RAM, making single-cycle memory accesses possible. + +.. note:: + In the prototype silicon provided for the initial limited sampling, the size of the local RAM is 64 kB. + +For performance reasons, the Radio Core includes its own AES-128 hardware accelerator for implementing link-layer encryption. +For asymmetric cryptography, it relies on services provided by the Secure Domain. + +The Radio Core is user-programmable, if you want to add or modify code, but it is also possible to leave the core running Nordic’s default protocol stack software and only engage with its high-level interface. +Since the Radio Core is physically separate from the Application Core, a separation of concerns exists, and, unlike single-core implementations, the protocol stack software running on the Radio Core will not influence the execution of application code running on the Application Core. + +While any peripheral in Radio's local APB2 bus (including the radio) is active, the 32 MHz crystal oscillator will be enabled, and the radio itself will be clocked from this clock source. + +Global Domain +************* + +The following image shows the Global Domain in the final silicon: + +.. figure:: images/nRF54H20_globaldomain.svg + :alt: Global Domain + + Global Domain + +The Global Domain contains most of the memory and peripherals of the nRF54H20. +This offers flexibility to assign memory regions and peripherals to different cores. +If this flexibility is not needed, it is possible to use the |NCS| defaults, where most of the memory and peripherals are assigned to the Application Core. + +The Global Domain includes two sets of power domains: + +* The low-leakage power domains runs at a clock speed of 16 MHz and contains the peripherals that do not need a higher clock speed than this. +* The high-speed power domains contains the main memories (MRAM and RAM) and high-speed peripherals that have clock speeds higher than 16 MHz. + +Peripheral Processor (PPR) +========================== + +The Peripheral Processor (PPR, pronounced “Pepper”) is a VPR core running at 16 MHz located in the low-leakage area of the Global Domain. +It is designed to perform simple I/O-related operations and low-level peripheral handling with lower power and lower latency than the Arm-based processors. + +This processor is suitable for the following use cases: + +* Reading and aggregating data from sensors. + Based on data, making decisions on when to wake up the rest of the system. +* Servicing serial ports. +* Coordinating several peripherals to achieve a task. + +It has been optimized for using very few clock cycles to service interrupts and can start and stop quickly. +Since the PPR is running from the same clock as the low-leakage peripherals, it does not need to implement any wait cycles to access peripheral registers. + +Fast Lightweight Processor (FLPR) +================================= + +The Fast Lightweight Processor (FLPR, pronounced Flipper) is a VPR core running at up to 320 MHz, located in the high-speed area of the Global Domain. +This CPU is intended to implement software-defined peripherals. + +.. note:: + FLPR firmware support will not be available during the initial limited sampling. + +Secure Domain +************* + +The Secure Domain (SecDom) is a dedicated domain which executes a pre-compiled and Nordic Semiconductor-signed firmware component. +It exposes security services to the other cores through an IPC interface. + +The Secure Domain has its own CPU, local RAM, and local peripherals to provide background services to the other Cores. +The Secure Domain provides the initial root of trust (RoT), handles all the global resource allocation, acts as a trusted third party (TTP) between other MCU domains, and is used to secure cryptographic operations. +Since the nRF54H platform supports global resource sharing, where memory partitions and peripherals in the global domain can be assigned to different local domains, the Secure Domain Firmware controls this partitioning while also acting as the boot master for the entire system. + +The Secure Domain Firmware (SDFW) exposes security-related services to the Cores in the system located in local domains (like Application and Radio). + +System Controller +***************** + +System Controller is a VPR that implements system startup and power management functionalities that in the past would have been implemented in hardware. + +Cores management +**************** + +In the nRF54H20, the cores can be divided into the following groups: cores that are programmable by the user, by Nordic, or by both. + +Cores managed by Nordic Semiconductor + Secure Domain and System Controller are cores that are exclusively managed by Nordic Semiconductor. + + The firmware for cores managed by Nordic will come as part of the nRF Connect SDK. + This means that the components can be modified by Nordic Semiconductor only. + +Cores managed by the user and Nordic Semiconductor + Firmware for the Radio Core will come as part of the nRF Connect SDK. + You can either use the default Nordic’s Radio Core firmware, modify it, or provide a custom implementation. + If you rely on Nordic to provide the firmware, the default correct controller library will be used depending on the short-range protocol selected in the software configuration. + +Cores managed by the user + Although there are multiple distinctive cores in the system, you will be responsible mostly for preparing the firmware for the Application Core. + If the application firmware is executed in non-secure mode, the secure firmware (TF-M) is delivered as part of the nRF Connect SDK. + + You can choose to move some of the processing from the Application Core to the Peripheral Processor (PPR) or to the Fast Lightweight Processor (FLPR). diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_intro.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_intro.rst new file mode 100644 index 000000000000..91d2c8540a4a --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_intro.rst @@ -0,0 +1,12 @@ +:orphan: + +.. _ug_nrf54h20_architecture_intro: + +Introduction to the architecture of the nRF54H20 SoC +#################################################### + +The following documents introduce the architecture of the nRF54H20 SoC: + +* The `Introduction to nRF54H20`_ PDF document, providing an overview of the hardware and software features of the nRF54H20. +* The `nRF54H20 Objective Product Specification 0.3.1`_ (OPS) PDF document. +* The `nRF54H20 prototype difference`_ PDF document, listing the major differences between the final and the prototype silicon provided in the initial limited sampling. diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_ipc.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_ipc.rst new file mode 100644 index 000000000000..ae84f73cc0fb --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_ipc.rst @@ -0,0 +1,224 @@ +:orphan: + +.. _ug_nrf54h20_architecture_ipc: + +Interprocessor Communication in nRF54H20 +######################################## + +.. contents:: + :local: + :depth: 2 + +Interprocessor communication (IPC) is the communication between different CPUs (and domains). +The nRF54H20 includes several types of CPUs that are optimized for different types of workloads. +This provides an asymmetric multiprocessing environment where you can freely select the CPU that is best suited to the workloads that compose your application. + +Interprocessor Communication is required in asymmetric multiprocessing environments to share services' requests, responses, and data between processors. + +The following sections describe the communication protocol used for IPC in |NCS| for the nRF54H20 SoC. +They also include an overview of the connection scheme between the cores available in the system. + +Technical solution +****************** + +A single Interprocessor Communication instance used in the nRF54H20 SoC allows full-duplex communication between two cores. +It support only unicast messages. + +To communicate with multiple peers, a core requires multiple IPC instances, at least as many as the number of peers. +It is possible to create multiple IPC instances towards a single peer to separate messages with different priority levels. +The number of IPC instances which might be created is limited by the available hardware resources (numbers of channels in the signaling peripherals). + +The Interprocessor Communication can be described using the OSI model. +See the following figure: + +.. figure:: images/nrf54h20_IPC_layers.svg + :alt: nRF54H20 IPC layers + +Physical layer +============== + +The physical layer used by IPC in the nRF54H20 SoC consists of shared RAM and signaling peripherals. + +The shared RAM must be accessible (both for reads and writes) by both cores using this RAM region for communication. +See :ref:`General-purpose shared RAM (RAM0x)` for a description of shared RAM and its placement in the memory map. + +Signaling peripherals are the hardware peripherals which can be used by one core to trigger an IRQ in another core. +Each ARM Cortex-M33 core in nRF54H20 has an associated BELLBOARD signaling peripheral. +Each VPR core in nRF54H20 has an associated VEVIF signaling peripheral: + +* When a core signals an IRQ to its ARM Cortex-M33 peer, it uses the BELLBOARD associated with the peer. +* When a core signals an IRQ to a VPR peer, it uses the VEVIF associated with the peer. +* When a core receives an IRQ signal, it uses the BELLBOARD or the VEVIF associated with it, regardless which peer originated the signal. + +Each VEVIF and BELLBOARD has multiple channels. +The peer originating the signal is recognized with a channel number associated with the peer. +The channel numbers association is presented in the following table: + +============================ ========== +Signal originator Channel id +============================ ========== +SecDom 0 +SecDom: signal to a debugger 1 +System Controller 6 +Application 12 +Radio 18 +============================ ========== + +Some of the channels in BELLBOARDs and VEVIFs are interpreted differently by other receivers. + +The following tables show signals received only by specified cores. + + Secure Domain core: + + ============================ ========== + Signal originator Channel id + ============================ ========== + System Controller's debugger 7 + Application's debugger 13 + Radio's debugger 19 + ============================ ========== + + Application core: + + This assignment applies only when PPR and FLPR owner is set to the Application. + + ================= ========== + Signal originator Channel id + ================= ========== + PPR 12 + FLPR 13 + ================= ========== + + Radio Core: + + This assignment applies only when BBPROC owner is set to the Radio. + + ================= ========== + Signal originator Channel id + ================= ========== + BBPROC 18 + ================= ========== + +Some of the channels in BELLBOARDs and VEVIFs are reserved for functions different from IPC. + +MAC, Network, Transport +======================= + +The layers responsible for maintaining a stable full-duplex stream of data between two cores (MAC, Network, Transport) are implemented in an IPC transport library. +The default IPC transport library for nRF54H20 is :ref:`ICMsg `. +This lightweight library maintains the connection between a pair of cores for each IPC instance with minimal memory overhead. +Each IPC instance requires an instance of the icmsg library. +Each icmsg library instance requires the following: + + * One memory buffer for A->B messages + * One memory buffer for B->A messages + * A pair of signaling channels (one for A->B, one for B->A). + +The icmsg library is designed to efficiently send short messages to a peer. +Its buffer allocation is not optimized for bulk transfer of long messages and it does not provide a zero-copy model. +To transfer bigger amount of data (like network packets) between two cores, icmsg can be used as control plane. +However, you must use as data plane memory allocation mechanisms optimized for bigger data and supporting flexible memory allocation and a zero-copy model (like Zephyr's :ref:`zephyr:net_buf_interface`). + +.. note:: + The memory allocation mechanism for the data plane is a single-core memory allocation working on shared memory buffers. + It does not have to involve another IPC transport. + The ownership of the shared buffers is passed between the cores using the control plane, but only one of the cores is responsible for managing (allocating, resizing, freeing) the buffers. + +For more information, consult the :ref:`ICMsg ` backend documentation. + +Session +======= + +The IPC session establishment in the nRF54H20 SoC is performed by the :ref:`IPC service ` library. +This library provides a unified API for IPC transports and it integrates specific transports as its backends. +ICMsg is integrated as one of the available IPC service backends. +The library is responsible for creating IPC instances based on the system configuration described in the devicetree. + +It is recommended to use the ipc_service API to perform inter-processor communication in the nRF54H20 SoC. + +For more information, consult the :ref:`IPC service ` library documentation. + +Presentation and Application layers +=================================== + +The presentation and application layers are connection specific. +Each connection has other requirements regarding the type and the nature of the exchanged messages. + +The solutions selected for each connection are listed in the table below: + +====================== ===================== +Connection Communication library +====================== ===================== +System Controller nrfs +Secure Domain RPC (:ref:`nrfxlib:nrf_rpc`) +Radio Bluetooth HCI or :ref:`nrfxlib:nrf_rpc` +Radio 802.15.4 Spinel +PPR with event_manager :ref:`event_manager_proxy` +====================== ===================== + +IPC connections scheme +********************** + +The following figures show the IPC connection schemes in the nRF54H20 SoC: + +.. figure:: images/nrf54h20_cpu_to_cpu.svg + :alt: nRF54H20 IPC between ARM cores + +.. figure:: images/nrf54h20_arm_to_vpr.svg + :alt: nRF54H20 IPC between ARM cores and VPR cores + +Radio core +========== + +The Radio core exposes radio communication services to the Application Core through IPC. +These services include: + + * Bluetooth (HCI or host API) + * IEEE 802.15.4 radio driver API + +These services are hidden behind Zephyr APIs available in the Application Core, like the Bluetooth host API or the IEEE 802.15.4 driver API. +All services can be enabled simultaneously using separated endpoints in a shared IPC instance. +You can implement other services running in the Radio Core and expose them to the Application Core using more endpoints from the shared IPC instance. + +Secure Domain core +================== + +The Secure Domain core exposes security-related services to the other local cores in the system (Application, Radio). +The list of services also includes: + + * Key management + * Secure storage + * Cryptography + + * Cryptographically Secure Pseudo Random Number Generator + + * Device Firmware Upgrade + * Debugger access management + * Reset notifications + * Encrypted core dumps + +System Controller +================= + +The System Controller exposes the following services to local cores (Application, Radio, Secure Domain) through IPC: + + * Clocks accuracy notification and calibration requests + * MRAM latency management (related to power management) + * CPU frequency management (using Dynamic Voltage and Frequency Scaling) + * Die temperature service + * L2CACHE performance + * Power output service + +Fast Lightweight Processor (FLPR) +================================= + +The Fast Lightweight Processor (FLPR) exposes IPC communication for its owner to manage its operations. +The communication details depends on the FLPR role in the system. + +Peripheral Processor (PPR) +========================== + +The Peripheral Processor (PPR) exposes IPC communication for its owner to manage its operations. +The communication details depends on the PPR role in the system. + +In the :ref:`nrf_machine_learning_app` application, PPR uses an :ref:`event_manager_proxy` through IPC to extend the Event Manager framework running in the Application Core. diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_lifecycle.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_lifecycle.rst new file mode 100644 index 000000000000..9a044ec192d0 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_lifecycle.rst @@ -0,0 +1,58 @@ +:orphan: + +.. _ug_nrf54h20_architecture_lifecycle: + +nRF54H20 lifecycle states +######################### + +.. contents:: + :local: + :depth: 2 + +The Secure Domain ROM firmware defines the lifecycle states (LCS) for the nRF54H20 SoC. +The states are based on the Arm PSA Security Model and allow for programming and safely erasing the device assets. + +.. caution:: + The device must be kept to Root of Trust (RoT) during the initial limited sampling. + Changing the lifecycle state of the nRF54H20 devices during the initial limited sampling will brick your devices. + + The lifecycle state will be changeable only in the final silicon. + +The LCS available are the following: + +.. list-table:: nRF54H20 lifecycle states + :header-rows: 1 + :align: center + :widths: auto + + * - LCS + - Supply chain stage + - Description + * - EMPTY + - Production + - RAM empty and Secure Domain Firmware unprogrammed. + * - Root of Trust + - Production + - Secure Domain Firmware and certificates provisioned. + * - DEPLOYED + - In-field + - Secure Domain debug access port is locked, and unlock is only possible using an authenticated operation. + * - ANALYSIS + - End-of-life + - All device assets in MRAM are erased to allow for Nordic RMA procedures. + * - DISCARDED + - End-of-life + - All device assets in MRAM are erased. + +See the following diagram: + +.. figure:: images/nRF54H20_lifecycle_states.svg + :alt: nRF54H20 lifecycle states and transitions + + nRF54H20 lifecycle states and transitions available on the final silicon. + +This figure shows the states and transitions that will be available on the final silicon. +Black arrows illustrate forward unauthenticated transitions and red arrows illustrate backward authenticated transitions. + +Changing the lifecycle state will be useful during development. +Test devices in their final configuration would require the device to be in the deployed state, however, updating the Secure Domain firmware and the System Controller firmware will be easier with the device in RoT state. diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_memory.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_memory.rst new file mode 100644 index 000000000000..022c54f2d6bb --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_memory.rst @@ -0,0 +1,453 @@ +:orphan: + +.. _ug_nrf54h20_architecture_memory: + +nRF54H20 Memory Layout +###################### + +.. contents:: + :local: + :depth: 2 + +The memory inside the nRF54H20 can be classified by several characteristics, like retention without power and CPU association. +When classifying memories by storage time, the nRF54H20 contains the following types of memory: + +* Static RAM (RAM) +* Magnetic RAM (MRAM) with non volatile memory properties + +MRAM retains its content after disconnecting the system from power, while RAM does not. +MRAM is intended to store executable firmware images, as well as credentials, and other data at rest. + +When classifying memories by a CPU association, the nRF54H20 contains the following types of memory: + +* Local Memory +* Global Memory + +The MRAM is a global memory available to all CPUs in the system. +Some RAM memories are, instead, tightly coupled to a specific CPU, while others are intended to be shared between multiple CPUs. + +.. note:: + In the nRF54H20 initial limited sampling, TrustZone is disabled on all cores. + +RAM +*** + +There are multiple RAM banks in the system. +Each local domain (like Application or Radio) contains its own RAM. +There is also a large part of the RAM in the global domain to be shared between the cores in the system. + + +.. image:: images/nrf54h20_memorymap.png + +Local RAM +========= + +Local RAM is present in each of local domains + +Application Core RAM +-------------------- + +.. image:: images/nrf54h20_memory_map_app.svg + :width: 300 px + +The Application Core contains 32 KB of local RAM. +Accessing this memory from the Application Core CPU has minimal latency, but accessing it from any other core adds significant latency. +Because of this property, the local RAM in the application domain should be used mainly to store data frequently accessed by the Application Core, or to store timing-critical parts of the code executed by Application Core. + +Address range + 0x22000000 - 0x22008000 + +Size + 32 KB + +Access control + Application domain local RAM is accessible by the Application Core. + Any core (like FLPR or PPR) or peripheral configured to be owned by Application Core (like UARTE or SAADC) can access this memory as well. + Any core with access to this memory can execute code from it. + + If the TrustZone feature is enabled for Application Core, this memory can be partitioned in one secure and one non-secure region. + The secure region is accessible only by code executed with the secure attribute, while the non-secure region is accessible by any code. + + .. note:: + Code executed by VPRs (like FLPR or PPR) has its secure attribute matching the given VPR security configuration in the SPU. + Local RAM cannot include a Non-Secure Callable section. + +Radio Core RAM +-------------- + +.. image:: images/nrf54h20_memory_map_radio.svg + :width: 300 px + +The Radio Core contains 96 KB of local RAM. +Any access to this memory has minimal latency if originated either from Radio Core CPU or from peripherals with EasyDMA located in the Radio Core. +Any access from any other core has a significant latency. +Because of this property, local RAM in the Radio Core should be used mainly to store data frequently accessed by the Radio Core CPU or the radio protocol frames to be accessed by CCM or RADIO peripherals, or to store timing critical parts of the code executed by the Radio Core CPU. + +Address range + 0x23000000 - 0x23018000 + +Size + 96 KB + +Access control + The Radio Core local RAM is accessible by the Radio Core. + Any core (like FLPR or PPR) or peripheral configured to be owned by the Radio Core (like UARTE or SAADC) can access this memory as well. + Any core with access to this memory can execute code from it. + + If the TrustZone feature is enabled for the Radio Core, this memory can be partitioned in one secure and one non-secure region. + The secure region is accessible only by code executed with the secure attribute, while the non-secure region is accessible by any code. + + .. note:: + Code executed by VPRs (like FLPR or PPR) has its secure attribute matching the given VPR security configuration in the SPU + Local RAM cannot include a Non-Secure Callable section. + +BBPROC memory +^^^^^^^^^^^^^ + +.. image:: images/nrf54h20_memory_map_bbproc.svg + :width: 300 px + +The Lower 32 KB of local RAM in the Radio Domain (0x23010000 - 0x23018000) is tightly coupled with BBPROC. +Any access to this memory has minimal latency if originated from BBPROC. +Any access originated from the Radio Core or from peripherals with EasyDMA located in radio domain have a little greater latency while accessing BBPROC memory. +Access from other domains is possible, but with significant latency. + +BBPROC memory is the only memory from which BBPROC can fetch its instructions. +Because of this property, this memory block is mostly intended to store BBPROC code and data. +When BBPROC is unused in a system, this memory can be used as additional local RAM in the Radio Domain. + +Address range + 0x23010000 - 0x23018000 + +Size + 32 KB + +Access control + The access to the BBPROC memory is configured as the access to the local RAM in the Radio Domain. + +Secure Domain +------------- + +.. image:: images/nrf54h20_memory_map_secure.svg + :width: 300 px + +The Secure Domain contains 32 KB of local RAM. +Any access to this memory from the Secure Domain core has minimal latency, but accesses from any other core have significant latency. +Because of this property, the local RAM in the Secure Domain should be used mainly to store data frequently accessed by its local core, or to store timing critical parts of the code executed by it. + +Address range + 0x21000000 - 0x21008000 + +Size + 32 KB + +Access control + The Secure-Domain local RAM is accessible by its local core. + Any core (like FLPR or PPR) or peripheral configured to be owned by the Secure Domain (like UARTE or SAADC) can access this memory as well. + Any core with access to this memory can execute code from it. + + If the TrustZone feature is enabled for the Secure Domain, this memory can be partitioned in one secure and one non-secure region (both regions owned by Secure Domain). + The secure region is accessible only by code executed with the Secure attribute, while the Non-secure region is accessible by any code. + The Local RAM cannot include a Non-Secure Callable section. + +Global RAM +========== + +The Global Domain RAM (or Global RAM, GRAM) is distributed in multiple instances across the system. +Each of the instances has other properties and other purposes. + +.. _ug_nrf54h20_architecture_memory_gp_shared_ram: + +General-purpose shared RAM (RAM0x) +---------------------------------- + +.. image:: images/nrf54h20_memory_map_ram0x.svg + :width: 300 px + +The biggest part of the RAM memory in the system is located in the Global Domain as general-purpose shared RAM. +Access to this memory is relatively fast from all the local domains (like the Application or the Radio ones). +Access to this memory from DMA used by USB has minimal latency. + +This memory is intended to store the majority of the data used by local cores (and does not fit in local domains' RAM) including shared memory used for Inter-Processor Communication (IPC) between local cores. +Buffers for USB data must be stored in this memory part, in the region owned by the core owning USB (usually the Application Core in typical applications). + +Address range + 0x2F000000 - 0x2F0E0000 + +Size + 896 KB + +Access control + The general-purpose shared RAM is split into multiple partitions. + Each of the local cores has two partitions assigned: one configured as Secure, the other one as Non-Secure. + The partitions are configured in the given core's UICR. + + If TrustZone is enabled for a core, the Secure partition is used to store the data of the Secure Processing Environment, while the Non-Secure partition stores the data of the Non-Secure Processing Environment and the shared memory used by the Inter-Processor Communication towards other local domains. + If TrustZone is disabled for a core, the Secure partition assigned to this core is used to store program data, while the Non-Secure partition contains the shared memory used by IPC. + + Secure partitions are grouped at the beginning of the general-purpose shared RAM block, while Non-Secure partitions are grouped at the end. + Non-Secure partitions are overlapping to define shared-memory IPC regions. + + A partition assigned to a core is accessible from this core, other cores owned by this core, or DMAs used by peripherals used by this core. + Access from other cores or peripherals is prevented. + A partition configured as Secure is accessible only from the Secure Processing Environment in the core owning the given partition. + A partition configured as Non-Secure is accessible from both the Secure and Non-Secure Processing Environments running in the core owning the given partition. + + + .. note:: + If TrustZone is disabled for a given core, the only available Processing Environment is Secure. + +SYSCTRL memory (RAM20) +---------------------- + +.. image:: images/nrf54h20_memory_map_ram20.svg + :width: 300 px + +The SYSCTRL memory is a part of the global RAM tightly coupled with the System Controller. +Access to this memory block from the System Controller has minimal latency and can be performed without powering up any other parts of the system. +Access to this memory from the local domains has higher latency than access to the general-purpose shared RAM. + +This memory is statically partitioned. +The layout is not to be adjusted for specific products. + +This memory is intended to store the code executed in the System Controller, the System Controller's data, and the shared memory used for Inter-Processor Communication between the System Controller and other cores. +Because of the static allocation property, this memory stores also the shared memory used for communication between debugger probes connected to cores in the system and the Secure Domain Core. + +Address range + 0x2F880000 - 0x2F890000 + +Size + 64 KB + +Access control + The SYSCTRL memory is split into multiple partitions. + The System Controller has access to all of them (System Controller's code and data, and shared memory regions). + The shared memory regions are also accessible by the cores using particular region for communication with the System Controller and the debugger. + The shared memory regions are configured in the given core's UICR. + Cores do not have access to other parts of the SYSCTRL memory. + + If TrustZone is enabled for a core, the shared memory region is accessible from the Non-Secure Processing Environment. + If TrustZone is disabled for a core, the shared memory region is accessible from the Secure Processing Environment. + +Fast global RAM (RAM21) +----------------------- + +.. image:: images/nrf54h20_memory_map_ram21.svg + :width: 300 px + +The Fast global RAM is a part of the global RAM tightly coupled with the Fast Lightweight Processor. +Access to this memory block from the FLPR and fast peripherals' DMA (I3C, CAN, PWM120, UARTE120, SPIS120, SPIM120, SPIM121) has minimal latency and can be performed without powering up any other parts of the system. +Access to this memory from the local domains has higher latency than access to the general-purpose shared RAM. + +This memory is intended to store the code executed in the FLPR, the FLPR's data, the shared memory used for Inter-Processor Communication between the FLPR and the core managing the FLPR, and DMA buffers for the fast peripherals. + +Address range + 0x2F890000 - 0x2F898000 + +Size + 32 KB + +Access control + The FLPR and its owner have access to all partitions assigned to FLPR and its Inter-Processor Communication. + Each of the memory partition assigned for DMA of the fast peripherals is accessible from the core owning given set of the peripherals. + The FLPR and the fast peripherals are by default owned by the Application Core. + This ownership and matching memory access rights can be customized in UICRs. + + The security attribute of memory partitions must follow FLPR and DMA engines security settings. + +Slow global RAM (RAM3x) +----------------------- + +.. image:: images/nrf54h20_memory_map_ram3x.svg + :width: 300 px + +The Slow global RAM is a part of the global RAM tightly coupled with the Peripheral Processor. +Access to this memory block from the PPR and slow periperals' DMA has minimal latency and can be performed without powering up any other parts of the system. +Access to this memory from the local domains has higher latency than access to the general-purpose shared RAM. + +This memory is intended to store the code executed in the PPR, the PPR's data, the shared memory used for Inter-Processor Communication between the PPR and the core managing the PPR, and DMA buffers for the slow peripherals. + +Address range + 0x2FC00000 - 0x2FC08000 + +Size + 32 KB + +Access control + The PPR and its owner have access to all the partitions assigned to the PPR and its Inter-Processor Communication. + Each of the memory partition assigned for DMA of the slow peripherals is accessible from the core owning the given set of peripherals. + The PPR and the slow peripherals are by default owned by the Application Core. + The ownership and matching memory access rights can be customized in UICRs. + + The security attribute of memory partitions must follow PPR and CMA engines security settings. + +MRAM (non-volatile memory) +************************** + +The MRAM is divided in the following parts: + +* MRAM_10 +* MRAM_11 + +MRAM_10 +======= + +.. image:: images/nrf54h20_memory_map_mram10.svg + :width: 300 px + +The MRAM_10 is a part of the non-volatile memory intended to keep firmware images to execute. +Access to this memory has minimal latency to avoid CPU stalls on instruction fetches. +This part of the memory is not writable while the main application is running (it is writable only during the Firmware Upgrade procedure) to avoid any latency caused by write operations. +Apart from executable code images, this part of the memory stores the Secure Information Configuration Registers (SICR) used by the programs running in the Secure Domain Core. +If code and data for the Application Core do not fit in MRAM_10, it can be partially or fully placed in MRAM_11. + +Address range + 0x0E000000 - 0x0E100000 + +Size + 1024 KB + +Access control + The Application Core and the Radio Core have read and execute access to memory regions assigned to them. + If Trustzone is disabled for any of these cores, then the assigned memory region is a single block containing secure code and data. + If Trustzone is enabled for any of these cores, then the assigned memory region is split in three blocks: + + * Secure code and data + * Non-secure code and data + * Non-secure callable (NSC) + + The code executed in the Secure Processing Environment of a core has access to all three blocks assigned to the core. + The code executed in the Non-Secure Processing Environment has access only to the Non-secure code and data block, and can call function veneers located in the NSC block. + + The System Controller's code and data region is accessible only by the Secure Domain Core. + The content of this region is copied by the Secure Domain Core to RAM_20 before the System Controller is started. + The System Controller accesses its code and data from the copy in RAM_20. + + Secure Domain has access to all parts of the MRAM_10. + Other cores can access only the parts assigned to them, according to the security rules described above. + +MRAM_11 +======= + +.. image:: images/nrf54h20_memory_map_mram11.svg + :width: 300 px + +The MRAM_11 is a part of the non-volatile memory intended to keep non-volatile writable data. +Writing to MRAM_11 can increase access latency for other cores reading from MRAM_11. +When a core is reading or executing code from MRAM_11, the impact of the additional latency must be taken in consideration. +Each of the local cores (Application, Radio, Secure Domain) have an allocated partition in MRAM_11 to store their non-volatile data. +Each of the cores has full control on the data layout and management in the assigned MRAM partition. +There is also a Device Firmware Upgrade partition used to store firmware images used during the upgrade procedure. +If code and data for the Application Core do not fit in MRAM_10, it can be partially or fully placed in MRAM_11. + +Address range + 0x0E100000 - 0x0E200000 + +Size + 1024 KB + +Access control + The Application Core and the Radio Core have read and write access to their assigned non-volatile data regions. + The non-volatile data region assigned to the core having trustzone disabled is marked as Secure, while the non-volatile data region assigned to the core having trustzone enabled is marked as Non-Secure. + + If code or data for the Application Core is placed in MRAM_11, the Application Core has *read and execute* access to this partition. + This access can be configured as follows: + + * Default configuration - all the application code and data is placed in MRAM_10. + It is configured with a single MPC configuration entry contained entirely in MRAM_10. + * All the app code and data is placed in MRAM_11. + It is configured with a single MPC configuration entry contained entirely in MRAM_11. + * The app code and data is partially in MRAM_10, partially in MRAM_11. + It is configured with a single MPC configuration entry covering partially MRAM_10 and partially MRAM_11. + Because of the continuous memory address range it is possible to use a single memory region to describe such data block. + + The Secure Domain has access to all the parts of MRAM_11. + The Application Core has read and write access to the DFU partition. + The security configuration of this partition follows the Trustzone configuration of the Application Core (Secure if Trustzone is disabled, or Non-Secure if Trustzone is enabled). + +Memory Privilege Controller (MPC) configuration +*********************************************** + +The Secure Domain configures Memory Privilege Controllers (MPCs) before it boots other domains. +MPC configuration provides rights for other cores to access memory regions assigned to them. +If a core tries to access a memory address not assigned to it, the transaction fails. + +The Secure Domain can access all the memory regions in the system and does not require explicit access rights in MPC. + +The Secure Domain configures OVERRIDEs in the MPC assigned to ``AXI_0`` to provide the access rights needed: + +=========== ===== =========== ========== ====================================================== +OVERRIDE Id Owner Permissions SECUREMASK Regions +=========== ===== =========== ========== ====================================================== +1 App RW 1 App's NV storage; DFU storage bank +2 Radio RW 1 Radio's NV storage +3 All R any UICRs, FICR +4 App RW 1 Radio <-> App IPC; App's Non-Secure data +5 App RWS 1 * SecDom <-> App IPC; App's Secure data +6 App RX 1 App's Non-Secure code +7 App RXS 0 App's S-NSC; App's Secure code +8 Radio RW 1 Radio <-> App IPC; Radio's Non-Secure data +9 Radio RWS 1 * SecDom <-> Radio IPC; Radio's Secure data +10 Radio RX 1 Radio's Non-Secure code +11 Radio RXS 0 Radio's S-NSC; Radio's Secure code +=========== ===== =========== ========== ====================================================== + +.. note:: + SECUREMASK can be set to ``0`` for any secure memory partition. + However, because of the hardware configuration, OVERRIDEs marked with ``*`` have SECUREMASK set to ``1``. + Such configuration implies that addresses of this entry should have 28th bit cleared. + It does not expose any security thread because permissions filtering denies access from non-secure masters. + +The Secure Domain configures OVERRIDEs in the MPC assigned to ``AXI_1`` to provide the access rights needed: + +=========== ======= =========== ========== ================================================================================================================ +OVERRIDE Id Owner Permissions SECUREMASK Regions +=========== ======= =========== ========== ================================================================================================================ +5 SysCtrl RW 1 Radio's non-volatile storage; App's non-volatile storage; DFU storage bank; Secure Domain's non-volatile storage +=========== ======= =========== ========== ================================================================================================================ + + .. note:: + During the installation step of the Device Firmware Update procedure, write access is enabled for more MRAM partitions. + During this step the only active core is the Secure Domain Core. + +The Secure Domain configures OVERRIDEs in the MPC assigned to ``AXI_2`` to provide the access rights needed: + +=========== ===== =========== ========== ============================================================================== +OVERRIDE Id Owner Permissions SECUREMASK Regions +=========== ===== =========== ========== ============================================================================== +1 App RW 1 Application mngMbox; SysCtrl <-> App IPC +2 App RWX 1 FLPR code; FLPR data; FLPR <-> App IPC; DMA buffers for App's fast peripherals +3 Radio RW 1 Radio mngMbox; SysCtrl <-> Radio IPC +4 Radio RW 1 DMA buffers for Radio's fast peripherals (if any) +=========== ===== =========== ========== ============================================================================== + +The Secure Domain configures OVERRIDEs in the MPC assigned to ``AXI_3`` to provide the access rights needed: + +=========== ===== =========== ========== =========================================================================== +OVERRIDE Id Owner Permissions SECUREMASK Regions +=========== ===== =========== ========== =========================================================================== +1 App RWX 1 PPR code; PPR data; PPR <-> App IPC; DMA buffers for App's fast peripherals +3 Radio RW 1 DMA buffers for Radio's fast peripherals (if any) +=========== ===== =========== ========== =========================================================================== + +SAU configuration +***************** + +.. note:: + In the nRF54H20 initial limited sampling, SAU is disabled and the entire memory is marked as secure. + +Each one of the Cortex-M33 CPUs in the system with the TrustZone feature enabled (specifically, the Application, Radio, and Secure Domain Cores) associates a Security Attribution Unit (SAU) peripheral. +The Secure Domain configures the SAUs for itself during its initialization before it switches to the Non-Secure Processing Environment (NSPE). +The Secure Domain configures the SAUs for other cores before it boots them. + +SAU configuration provides the rights for the Non-Secure Processing Environment to access resources allocated for it. +If the NSPE tries to access a memory address not allocated to it, the transaction fails. + +============= ================== =================================== ==================================================================================================================================================================================== +SAU region Id Security attribute Region Comments +============= ================== =================================== ==================================================================================================================================================================================== +0 NS 0x0000_0000 - 0x1000_0000 The entire non-secure address space of the MRAM. Proper partitioning is done in MPC. +1 NS Core's S-NSC in MRAM S-NSC veneers in the secure address space of MRAM. +2 NS 0x2000_0000 - 0x3000_0000 The entire non-secure address space of the RAM. Proper partitioning is done in MPC. +3 NS Core's S-NSC in RAM - 0x1_0000_0000 S-NSC veneers in the secure address space of the global MRAM, all peripherals, external memory, and CPU registers. If no S-NSC is in the RAM, the start address must be 0x4000_0000. +============= ================== =================================== ==================================================================================================================================================================================== diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_configuration.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_configuration.rst new file mode 100644 index 000000000000..865c6ae438b6 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_configuration.rst @@ -0,0 +1,88 @@ +:orphan: + +.. _ug_nrf54h20_configuration: + +Configuring the nRF54H20 PDK +############################ + +.. contents:: + :local: + :depth: 2 + +The nRF54H20 PDK uses both devicetree and Kconfig for its hardware and software configuration. + +You can find the basics of both devicetree and Kconfig in Zephyr in the :ref:`zephyr:application` section of the Zephyr documentation. +You can also read the :ref:`app_build_system` section describing the |NCS| additions to the Zephyr configuration system. + +However, the multicore nature of the nRF54H20 PDK required some changes to the way devicetree files are organized. + +DTS file scheme +*************** + +.. note:: + This file scheme is valid only for the nRF54H20 initial limited sampling version of |NCS|. + It is subject to changes or improvements in future releases. + +The following is the DTS file structure implemented for all the SoCs of the 54H family: + +* Arch-specific DTS files, located in the :file:`../dts/arm/nordic_nrf_next/` and :file:`dts/riscv/nordic_nrf_next folder​` directories: + + * Project-wide files (:file:`haltium_cpu.dtsi` and :file:`haltium_global_*.dtsi`)​ + * Core-specific files per product (:file:`nrf54h20_cpu*.dtsi`)​ + +* Common directory, located in the :file:`../common/nordic_nrf_next` folder​: + + * Arch-independent configurations​ + * Common platform overlays + * Common memory and peripherals overlay applicable across products​ + * Product-specific overlays applicable to all cores​ + * Project-wide overlays + +The following is the include tree for the Application core of the nRF54H20 (cpuapp): + +.. figure:: images/cpuapp_include_tree.svg + :alt: nRF54H20 CPUAPP include tree + +The files shown in the figure are currently hosted in the ``ic-next`` repository. + +Customizing the DTS configuration +********************************* + +The output files created in your application build directory are documented in :ref:`zephyr:devicetree-in-out-files`. +You can use overlay files to customize this configuration. + +To see and test how to use overlays for changing nodes, see the *Lesson 3* of the `nRF Connect SDK Fundamentals course`_ on the Nordic Developer Academy website. + +Generated HEX files +******************* + +When building an application for the nRF54H20 PDK, you are building all domain images at once. +During this process, the following :file:`zephyr.hex` images are built: + +* Application core application +* PPR core application +* Secure Domain firmware +* System Controller firmware +* Radio core firmware + +Additionally, the following user information configuration registers (UICR) contents (:file:`uicr.hex`) are generated for setup access for domains: + +* System Controller UICR +* Application UICR +* Radio UICR + +.. note:: + ``west flash`` uses :file:`uicr_merged.hex` files that are pre-merged HEX files combining the relevant :file:`zephyr.hex` + :file:`uicr.hex` for a domain that has UICRs. + Flashing both :file:`zephyr.hex` + :file:`uicr.hex` will result in the same configuration. + +All of the HEX files need to be flashed into the device. +For more information on building images for the nRF54H20 PDK, see :ref:`ug_nrf54h20_gs`. +For additional information on multi-image builds see :ref:`ug_multi_image`. + +Other revelant resources +************************ + +For more resources, see the following: + +* The `nrf-regtool`_ - A script tool that generates files of register content for memory-mapped peripherals in Nordic Semiconductor products. +* ``Arborist`` - A framework for validating resources reserved through User Information Configuration Register (UICR) configurations. diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_custom_pcb.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_custom_pcb.rst new file mode 100644 index 000000000000..a3770f0227e8 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_custom_pcb.rst @@ -0,0 +1,201 @@ +:orphan: + +.. _ug_nrf54h20_custom_pcb: + +Configuring your application for a custom PCB +############################################# + +.. contents:: + :local: + :depth: 2 + +This guide demonstrates how to create your custom board files for your PCB for the nRF54H20 SoC. + +Prepare your PCB +**************** + +First, you need to create your PCB for the nRF54H20 SoC. + +We highly recommend using the PCB layouts and component values provided by Nordic Semiconductor, especially for clock and power sources. +However, if you plan to select your own power sources, consider the following limitations: + +* The DC/DC inductor must be present on the PCB. + If the DC/DC power converter is to be used, the BICR value ``POWER.CONFIG.INDUCTOR`` must also be programmed to ``Present`` (``0``). + + .. note:: + Currently, there is a bug (LIL-9968) causing the nRF54H20 limited sampling SoC to not wake up from the System OFF if DC/DC is enabled. + Temporarily, the workaround is to not use the DC/DC power converter. + +* For the lowest sleep power consumption, use a 32 KHz crystal. +* The **P9** port (3 V) cannot be used with internal nor external pull-down resistors. +* For optimal performance, the output impedance of the **P6** and **P7** ports configured in ``IOPORT.DRIVECTRLX.PY`` should match the PCB and external device pin impedance. + However, an existing limitation requires this configuration to be 50 ohms. + +.. note:: + For a list of major differences between the final and the prototype silicon provided in the initial limited sampling, consult the `nRF54H20 prototype difference`_ document. + +Consult the `nRF54H20 Objective Product Specification 0.3.1`_ (OPS) for more information on the mechanical specification of the SoC package and the reference circuitry used in the PDK. + +Prepare the configuration files for your custom board in the |NCS| +****************************************************************** + +The nRF54H20 PDK uses multiple board files for its configuration: + +* `ARM cores configuration files`_ +* `Risc-V cores configuration files`_ + +You can use these files as a starting point for configuring your own custom board. +The easiest way to do so, when creating a :ref:`Zephyr repository application `, is to create a copy of these folders under :file:`sdk-nrf-next/boards/arm/your_custom_board_name` (for the ARM configuration files) and :file:`sdk-nrf-next/boards/riscv/your_custom_board_name` (for the Risc-V configuration files), respectively. + +.. caution:: + Do not modify the configuration files related to the Secure Domain (:file:`*_cpusec` in the ARM folder) and the System Controller (:file:`*_cpusys` in the Risc-V folder). + +You must edit the :file:`.dts` and :file:`.overlay` files for your project to match your board configuration, similarly to any new board added to the |NCS| or Zephyr. + +See the following documentation pages for more information: + +* The :ref:`zephyr:devicetree` documentation to familiarize yourself with the devicetree language and syntax +* The :ref:`ug_nrf54h20_configuration` page for more information on how to configure your DTS files for the nRF54H20 SoC. +* The :ref:`zephyr:zephyr-repo-app` page for more information on Zephyr application types. +* The :ref:`dm_adding_code` documentation for details on the best user workflows to add your own code to the |NCS|. + +.. note:: + The configuration of board files is based on the `nRF54H20 common SoC files`_. + Each new |NCS| revision might change these files, breaking the compatibility with your custom board files created for previous revisions. + Ensure the compatibility of your custom board files when migrating to a new |NCS| release. + +Configure, generate, and flash BICR +*********************************** + +The Board Information Configuration Registers (BICR) are non-volatile memory (NVM) registers that contain information on how the nRF54H20 SoC must interact with other board elements, including the information about the power and clock delivery to the SoC. +The power and clock control firmware uses this information to apply the proper regulator and oscillator configurations. + +.. caution:: + You must ensure that the configuration is correct. + An incorrect configuration can damage your device. + +BICR allows for the configuration of various components on your custom board, like the following: + +* Power rails +* Low-frequency oscillator +* High-frequency oscillator (HFXO) +* GPIO ports power and drive control +* Tamper switches +* Active shield channels + +You can find the details of each register contained in BICR in the relevant `BICR register's PDF file`_. +When not set, the register's default value is ``0xFFFFFFFF``. + +The ``LFOSC.LFXOCAL`` register is used by the device to store the calibration of the LFXO. + +When ``LFOSC.LFXOCAL`` is ``0xFFFFFFFF`` at device boot, the firmware recalibrates the LFXO oscillator and writes the calibration data to the ``LFOSC.LFXOCAL`` register. +This is useful when making a change on the PCB (for example, when changing the crystal). +This initial calibration is only performed once. +Each subsequent start will use this initial calibration as the starting point. + +BICR configuration +================== + +The nRF54H20 PDK BICR configuration can be found in the board configuration directory as :file:`boards/arm/nrf54h20dk_nrf54h20/nrf54h20soc1_pdk_bicr.dtsi`. +This file is used by the |NCS| build system to generate a corresponding HEX file. +You can start from this file when editing the values of the devicetree properties inside your custom board folder (:file:`boards/arm/your_custom_board`), according to your board configuration. + +Generating the BICR binary +========================== + +To generate the BICR binary, you must first set the Kconfig option :kconfig:option:`CONFIG_INCLUDE_BICR` to ``y``. +When running ``west build``, the build system then runs the BICR devicetree node through `nrf-regtool`_ to create the relevant HEX file (:file:`bicr.hex`) at build time. +Based on the peripheral definition extracted from the nRF54H20 SVD file, the modified registers from the configuration are mapped into their relevant position in memory. + +.. note:: + If the build system cannot locate the ``bicr`` node inside your custom board's devicetree, or if you did not create a custom :file:`.dtsi` file for it, the BICR generation cannot progress, and the build system will skip it. + +You can find the generated :file:`bicr.hex` file in the :file:`build_dir/zephyr/`. +The presence of a ``bicr`` node in the application devicetree will automatically trigger a build of the BICR binary, and will place this file alongside the other binary outputs such as ``zephyr.hex`` and ``uicr.hex``. + +Flashing the BICR binary +======================== + +After the nRF Connect SDK build system generates the BICR binary, you must flash this binary manually. +The content of BICR should be loaded to the SoC only once and should not be erased nor modified unless the PCB layout changes. +To manually flash the generated :file:`bicr.hex` file to the SoC, use ``nrfjprog`` as follows:: + + nrfjprog --snr ${FPGA_SEGGER_ID} --coprocessor CP_SECURE -f nrf54h --program bicr.hex --verify + nrfjprog --coprocessor CP_SECURE --erasepage 0xfff8000 + nrfjprog --coprocessor CP_SECURE --erasepage 0xfffa000 + +You need to follow this flashing process only one time, as the PCB configuration will not change. + +Verify the Life Cycle State (LCS) of the SoC +******************************************** + +To successfully run your custom application on your custom board, the SoC must have its Lifecycle State (LCS) set to ``RoT`` (meaning Root of Trust). +To verify that, run nrfjprog from the nRF Command Line Tools version 10.23.3_ec as follows:: + + nrfjprog -s --memrd 0x0E000084 --w 32 --n 8 + +If nrfjprog returns ``0x2000`` twice, the LCS of the SoC is set to ``RoT``. +If nrfjprog returns ``0x1000`` twice, the LCS of the SoC is set to ``EMPTY``, meaning no LCS is set, and it needs to be switched to ``RoT``. + +If you get the following error, the SoC is in ROM boot mode:: + + [error] [ Client] - Encountered error -90: Command read_memory_descriptors executed for 1 milliseconds with result -90 + [error] [ Worker] - Ap-protect is enabled, can't read memory descriptors. + [error] [ Client] - Encountered error -90: Command read executed for 80 milliseconds with result -90 + [error] [haltium] - Device responded to command with error status in ADAC packet: INVALID_COMMAND (0x7FFF). + [error] [ Worker] - Access protection is enabled, can't access memory. + ERROR: The operation attempted is unavailable due to readback protection in + ERROR: your device. Please use --recover to unlock the device. + NOTE: For additional output, try running again with logging enabled (--log). + NOTE: Any generated log error messages will be displayed. + +Switch to ``NORMAL`` mode first, then run again the previous command:: + + nrfjprog -s --bootmode NORMAL + nrfjprog -s --memrd 0x0E000084 --w 32 --n 8 + +Switch LCS to RoT +================= + +To transition the LCS to ``RoT``, do the following: + +1. Program BICR and secdom:: + + nrfjprog -f nrf54h --coprocessor CP_SECURE --program /*insert_path_to_your_build_directory_here*/secdom/src/secdom-build/zephyr/zephyr.hex --verify + nrfjprog -f nrf54h --coprocessor CP_SECURE --program bicr.hex --verify + +#. Run these commands:: + + nrfjprog --coprocessor CP_SECURE --memwr 0x0E000108 --val 0x40000 + nrfjprog --coprocessor CP_SECURE --memwr 0x0E00010C --val 0x0E003000 + + nrfjprog --family nrf54h --bootmode ROM + nrfjprog --family nrf54h --adac lcs_change PSA_ROT_PROVISIONING --single-step + nrfjprog --family nrf54h --bootmode NORMAL + +#. Flash your application using west:: + + west flash + +#. Verify if the LCS is set to ``RoT``:: + + nrfjprog --memrd 0x0E000084 --w 32 --n 8 + + If nrfjprog returns ``0x2000`` twice, the LCS of the SoC is correctly set to ``RoT``. + +Create or modify your application for your custom board +******************************************************* + +You can now create or modify your application for your custom board. +When doing so, consider the following: + +* When reusing the |NCS| applications and samples, you must provide board-specific overlay files when such files are needed. + For general information on configuration overlays, see :ref:`configure_application`. + + However, you must consider the following nRF54H20-specific differences: + + * The application might require board overlays for multiple cores. + In this case, ensure that these overlays are consistent with each other. + +* When creating a new application specific to your new board, DTS board files can contain all necessary configurations, and no overlay file is needed. + However, the same limitations regarding the consistency and UICR configuration apply, but should be kept on the board files level. diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_debugging.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_debugging.rst new file mode 100644 index 000000000000..5e03f9842769 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_debugging.rst @@ -0,0 +1,124 @@ +:orphan: + +.. _ug_nrf54h20_debugging: + +nRF54H20 debugging +################## + +.. contents:: + :local: + :depth: 2 + +The main recommended tool for debugging in the |NCS| for the limited sampling of the nRF54H20 PDK is the `GNU Project Debugger`_ (GDB tool). + +When working from the command line, you can use west with the GDB tool. +For details, read the :ref:`Debugging with west debug ` section on the :ref:`zephyr:west-build-flash-debug` page in the Zephyr documentation. + +A useful tool for debugging the communication over Bluetooth is the `nRF Sniffer for Bluetooth LE`_. +The nRF Sniffer allows you to look into data exchanged over-the-air between devices. + +Debug configuration +******************* + +Set the following Kconfig options to ``y`` for the images running on the cores you want to debug: + +* :kconfig:option:`CONFIG_DEBUG_OPTIMIZATIONS` - This option limits the optimizations made by the compiler to only those that do not impact debugging. +* :kconfig:option:`CONFIG_DEBUG_THREAD_INFO` - This option adds additional information to the thread object so that the debugger can discover the threads. + This will work for any debugger. + +Debug build types +***************** + +Some applications and samples provide a specific build type that enables additional debug functionalities. +You can select build types when you are :ref:`configuring the build settings `. + +Debugging multiple cores +************************ + +To debug only the Application core firmware, a single debug session is sufficient. +To debug the firmware running also on the other cores, you need to set up a separate debug session for each one of the cores you want to debug. +When debugging another core, the application core debug session runs in the background and you can debug both cores if needed. + +If you want to reset the other cores while debugging, make sure to first reset the application core and execute the code. + +Using GDB as an external debugger +********************************* + +An external debugger can access the device using the Debug Access Port (DAP). +The DAP is a standard Arm® CoreSight™ serial wire debug port (SWJ-DP) that implements the serial wire debug (SWD) protocol with a two-pin serial interface. + +There are several access ports that connect to different parts of the system: + + * AHB-AP 0: Application core access port ID + * AHB-AP 1: Radio core access port ID + * AHB-AP 2: Secure domain access port ID + * AHB-AP 3: Auxiliary access port ID + * CTRL-AP 4: Device level control access port ID + * APB-AP 5: CoreSight™ subsystem access port ID + +The following sections describe how to debug the nRF54H20 using GDB as the external debugger with J-link. + +.. note:: + J-Link version 7.80c is required. + +Selecting the core +================== + +To debug a specific core using ``JLinkExe`` do the following: + +1. Run J-Link on the Application core:: + + JLinkExe -USB -if SWD -Device Cortex-M33 + + You can use this command to run J-Link also on other Arm cores. + You can find the ``SEGGER-ID`` as follows: + + * Check the ``SEGGER ID`` printed on the label on the bottom side of the PDK. + * Run the ``nrfjprog --ids`` command. + + If just one PDK is connected to the machine, defining ``SEGGER-ID`` is not necessary. + If more than one PDK is connected to the machine and ``SEGGER-ID`` is undefined, a pop up window will appear where you can manually select the ID of the PDK you want to run J-Link on. + + .. note:: + PPR core debugging is not functional in the initial limited sampling. + +#. Connect to the Application core:: + + exec CORESIGHT_SetIndexAHBAPToUse = + connect + + ```` is the ID of the access port. + +J-Link script files +=================== + +You can also create J-Link script files in your local directory and add them to a GDB server call for a remote debugging session. + +1. Create a script file with the following content:: + + void ConfigTargetSettings(void) { + J-Link_CORESIGHT_AddAP(, CORESIGHT_AHB_AP); + CORESIGHT_IndexAHBAPToUse = ; + } + +2. Add the script file to the GDB server call:: + + -scriptfile [*full_path/to/script_file_name*] + +Debug logging +************* + +You can use the logging system to get more information about the state of your application. +Logs are integrated into various modules and subsystems in the |NCS| and Zephyr. +These logs are visible once you configure the logger for your application. + +You can also configure log level per logger module to, for example, get more information about a given subsystem. +See :ref:`ug_nrf54h20_logging` for details on how to enable and configure logs on the nRF54H20 PDK. + +Debugging stack overflows +************************* + +One of the potential root causes of fatal errors in an application are stack overflows. +Read the Stack Overflows section on the :ref:`zephyr:fatal` page in the Zephyr documentation to learn about stack overflows and how to debug them. + +You can also use a separate module, such as Zephyr's :ref:`zephyr:thread_analyzer`, to make sure that the stack sizes used by your application are big enough to avoid stack overflows. diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_gs.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_gs.rst new file mode 100644 index 000000000000..dbbe44e4c20c --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_gs.rst @@ -0,0 +1,453 @@ +:orphan: + +.. _ug_nrf54h20_gs: + +Getting started with the nRF54H20 PDK +##################################### + +.. contents:: + :local: + :depth: 2 + +This page will get you started with your nRF54H20 PDK using the |NCS|. +It first tells you how to test that your PDK is working correctly by using the preflashed :zephyr:code-sample:`blinky` sample. +After the test, it will guide you on how to configure, build, and program the :ref:`multicore_hello_world` sample to the development kit and read logs from it. + +If you have already set up your nRF54H20 PDK and want to learn more, see the :ref:`ug_nrf54h20_architecture` documentation for an in-depth description of the architecture of the nRF54H20. + +.. _ug_nrf54h20_gs_requirements: + +Minimum requirements +******************** + +Make sure you have all the required hardware and that your computer has one of the supported operating systems. + +Hardware +======== + +* nRF54H20 PDK +* USB-C cable + +Software +======== + +On your computer, one of the following operating systems: + +* Microsoft Windows +* Ubuntu Linux +* macOS + +|supported OS| + +You also need to install `Git`_ or `Git for Windows`_ (on Linux and Mac, or Windows, respectively). + +.. _ug_nrf54h20_gs_test_blinky: + +Testing with the Blinky sample +****************************** + +In the limited sampling release, the nRF54H20 PDK comes preprogrammed with the :zephyr:code-sample:`blinky` sample. + +Complete the following steps to test that the PDK works correctly: + +1. Connect the USB-C end of the USB-C cable to the **IMCU USB** port the nRF54H20 PDK. +#. Connect the other end of the USB-C cable to your PC. +#. Move the **POWER** switch to **On** to turn the nRF54H20 PDK on. + The switch is located in the top left corner of the PDK PCB. + +**LED1** will turn on and start to blink. + +If something does not work as expected, contact Nordic Semiconductor support. + +.. _nrf54h20_gs_installing_software: + +Installing the required software +******************************** + +To work with the nRF54H20 PDK, you need to install the limited sampling version of the |NCS|. +Follow the instructions in the next sections to install the required tools. + +.. _nrf54h20_install_commandline: + +Installing the nRF Command Line Tools +===================================== + +You need the nRF Command Line Tools specific to the limited sampling release of the |NCS|. + +To install the nRF Command Line Tools, you need to download and install the version corresponding to your system: + +* `10.23.3_ec 64-bit Windows, executable`_ +* `10.23.3_ec macOS, zip archive`_ +* 64-bit Linux: + + * `10.23.3_ec x86 system, deb format`_ + * `10.23.3_ec x86 system, RPM`_ + * `10.23.3_ec x86 system, tar archive`_ + + * `10.23.3_ec ARM64 system, deb format`_ + * `10.23.3_ec ARM64 system, RPM`_ + * `10.23.3_ec ARM64 system, tar archive`_ + +* 32-bit Linux: + + * `10.23.3_ec ARMHF system, zip archive`_ + +.. _nrf54h20_install_toolchain: + +Installing the toolchain +======================== + +You can install the toolchain for the limited sampling of the |NCS| by running an installation script. +Before installing it, however, you need to have been granted an access to the necessary GitHub repositories using an authenticated account that does not have a passphrase key for credentials. +The access is granted as part of the onboarding process for the limited sampling release. +Ensure that you additionally have Git and curl installed. + +.. tabs:: + + .. tab:: Windows + + Follow these steps: + + 1. Create on GitHub your `Personal Access Token (PAT)`_. + #. Open git bash. + #. Download and run the :file:`bootstrap-toolchain.sh` installation script file using the following command: + + .. parsed-literal:: + :class: highlight + + curl --proto '=https' --tlsv1.2 -sSf https://developer.nordicsemi.com/.pc-tools/scripts/bootstrap-toolchain.sh | NCS_TOOLCHAIN_VERSION=v2.4.99-cs3 sh + + Depending on your connection, this might take some time. + Use your GitHub username and Personal Access Token (PAT) when prompted to. + #. Run the following command in Git Bash: + + .. parsed-literal:: + :class: highlight + + c:/ncs-lcs/nrfutil.exe toolchain-manager launch --terminal --chdir "c:/ncs-lcs/work-dir" --ncs-version v2.4.99-cs3 + + This opens a new terminal window with the |NCS| toolchain environment, where west and other development tools are available. + Alternatively, you can run the following command:: + + c:/ncs-lcs/nrfutil.exe toolchain-manager env --as-script + + This gives all the necessary environmental variables you need to copy-paste and execute in the same terminal window to be able to run west directly there. + + .. caution:: + When working with the limited sampling release, you must always use the terminal window where the west environmental variables have been called. + + #. Install the `Serial Terminal from nRF Connect for Desktop`_. + + If you run into errors during the installation process, delete the :file:`.west` folder inside the :file:`C:\\ncs-lcs` directory, and start over. + + We recommend adding the nrfutil path to your environmental variables. + + + .. tab:: Linux + + Follow these steps: + + 1. Create on GitHub your `Personal Access Token (PAT)`_. + #. Open a terminal window. + #. Download and run the :file:`bootstrap-toolchain.sh` installation script file using the following command: + + .. parsed-literal:: + :class: highlight + + curl --proto '=https' --tlsv1.2 -sSf https://developer.nordicsemi.com/.pc-tools/scripts/bootstrap-toolchain.sh | NCS_TOOLCHAIN_VERSION=v2.4.99-cs3 sh + + Depending on your connection, this might take some time. + Use your GitHub username and Personal Access Token (PAT) when prompted to. + #. Run the following command in your terminal: + + .. parsed-literal:: + :class: highlight + + $HOME/ncs-lcs/nrfutil toolchain-manager launch --shell --chdir "$HOME/ncs-lcs/work-dir" --ncs-version v2.4.99-cs3 + + This makes west and other development tools in the |NCS| toolchain environment available in the same shell session. + + .. caution:: + When working with west in the limited sampling release version of |NCS|, you must always use this shell window. + + #. Install the `Serial Terminal from nRF Connect for Desktop`_. + + If you run into errors during the installation process, delete the :file:`.west` folder inside the :file:`ncs-lcs` directory, and start over. + + We recommend adding the nrfutil path to your environmental variables. + + .. tab:: macOS + + Follow these steps: + + 1. Create on GitHub your `Personal Access Token (PAT)`_. + #. Open a terminal window. + #. Install `Homebrew`_: + + .. code-block:: bash + + /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" + + #. Use ``brew`` to install the required dependencies: + + .. code-block:: bash + + brew install cmake ninja gperf python3 ccache qemu dtc wget libmagic + + Ensure that these dependencies are installed with their versions as specified in the :ref:`Required tools table `. + To check the installed versions, run the following command: + + .. parsed-literal:: + :class: highlight + + brew list --versions + + #. Download and run the :file:`bootstrap-toolchain.sh` installation script file using the following command: + + .. parsed-literal:: + :class: highlight + + curl --proto '=https' --tlsv1.2 -sSf https://developer.nordicsemi.com/.pc-tools/scripts/bootstrap-toolchain.sh | NCS_TOOLCHAIN_VERSION=v2.4.99-cs3 sh + + Depending on your connection, this might take some time. + Use your GitHub username and Personal Access Token (PAT) when prompted to. + + .. note:: + On macOS, the install directory is :file:`/opt/nordic/ncs`. + This means that creating the directory requires root access. + You will be prompted to grant the script admin rights for the creation of the folder on the first install. + The folder will be created with the necessary access rights to the user, so subsequent installs do not require root access. + + Do not run the toolchain-manager installation as root (for example, using `sudo`), as this would cause the directory to only grant access to root, meaning subsequent installations will also require root access. + If you run the script as root, to fix permissions delete the installation folder and run the script again as a non-root user. + + #. Run the following command in your terminal: + + .. parsed-literal:: + :class: highlight + + /Users/*yourusername*/ncs-lcs/nrfutil toolchain-manager launch --shell --chdir "/Users/*yourusername*/ncs-lcs/work-dir" --ncs-version v2.4.99-cs3 + + This makes west and other development tools in the |NCS| toolchain environment available in the same shell session. + + .. caution:: + When working with west in the limited sampling release version of |NCS|, you must always use this shell window. + + #. Run the following commands in your terminal to install the correct lxml dependency: + + .. parsed-literal:: + :class: highlight + + pip uninstall -y lxml + pip install lxml + + #. Install the `Serial Terminal from nRF Connect for Desktop`_. + + If you run into errors during the installation process, delete the :file:`.west` folder inside the :file:`ncs-lcs` directory, and start over. + + We recommend adding the nrfutil path to your environmental variables. + +.. _nrf54h20_install_ncs: + +Installing the |NCS| +==================== + +After you have installed nRF Command Line Tools and the toolchain, complete the following steps to get the limited sampling version of the |NCS|: + +1. In the terminal window opened during the toolchain installation, initialize west with the revision of the |NCS| from the limited sampling by running the following command: + + .. parsed-literal:: + :class: highlight + + west init -m https://github.com/nrfconnect/sdk-nrf-next --mr v2.4.99-cs3 + + A window pops up to ask you to select a credential helper. + You can use any of the options. + +#. Set up GitHub authentication: + + ``west update`` requires :ref:`west ` to fetch from private repositories on GitHub. + + There are two ways you can authenticate when accessing private repositories on GitHub: + + * Using SSH authentication, where your git remotes URLs use ``ssh://``. + * Using HTTPS authentication, where your git remotes URLs use ``https://``. + + GitHub has a comprehensive `documentation page on authentication methods`_. + + However, we suggest to choose your authentication method depending on your scenario: + + * If this is the first time you are setting up GitHub access, use HTTPS. + * If you already have a git credentials file, use HTTPS. + * If you already have an SSH key generated and uploaded to GitHub, use SSH. + * If you are still undecided, use HTTPS. + + .. tabs:: + + .. tab:: HTTPS authentication + + The `west manifest file`_ in the |NCS| uses ``https://`` URLs instead of ``ssh://``. + When using HTTPS, you may be prompted to type your GitHub username and password or multiple times. + This can be avoided by creating on GitHub a Personal Access Token (PAT) (needed for two-factor authentication) and using `Git Credential Manager`_ (included in the git installation) to store your credentials in git and handle GitHub authentication. + + 1. Store your GitHub credentials (your username and the PAT created before) on disk using the ``store`` command from the git credential helper. + + .. code-block:: shell + + git config --global credential.helper store + + #. Create a :file:`~/.git-credentials` (or :file:`%userprofile%\\.git-credentials` on Windows) and add this line to it:: + + https://:@github.com + + See the `git-credential-store`_ manual page for details. + + If you don't want to store any credentials on the file system, you can store them in memory temporarily using `git-credential-cache`_ instead. + + .. tab:: SSH authentication + + The `west manifest file`_ in the |NCS| uses ``https://`` URLs instead of ``ssh://``. + If you are already using `SSH-based authentication`_, you can reuse your SSH setup by adding the following to your :file:`~/.gitconfig` (or :file:`%userprofile%\\.gitconfig` on Windows): + + .. parsed-literal:: + :class: highlight + + [url "ssh://git@github.com"] + insteadOf = https://github.com + + This will rewrite the URLs on the fly so that Git uses ``ssh://`` for all network operations with GitHub. + + You achieve the same result also using Git Credential Manager: + + .. code-block:: shell + + git config --global credential.helper store + git config --global url."git@github.com:".insteadOf "https://github.com/" + + If your SSH key has no password, fetching should just work. If it does have a + password, you can avoid entering it manually every time using `ssh-agent`_. + + On GitHub, see `Connecting to GitHub with SSH`_ for details on configuration + and key creation. + +#. Enter the following command to clone the project repositories:: + + west update + + Depending on your connection, this might take some time. + +#. Export a :ref:`Zephyr CMake package `. + This allows CMake to automatically load the boilerplate code required for building |NCS| applications:: + + west zephyr-export + +#. As an administrator (or superuser), install the requirements from `nrf-regtool`_ using the following command:: + + pip install -r modules/lib/nrf-regtool/scripts/requirements-base.txt + +Your directory structure now looks similar to this:: + + ncs-lcs/work-dir + |___ .west + |___ bootloader + |___ modules + |___ nrf + |___ nrfxlib + |___ zephyr + |___ ... + + +Note that there are additional folders, and that the structure might change. +The full set of repositories and folders is defined in the manifest file. + +.. _ug_nrf54h20_gs_sample: + +Programming the sample +********************** + +The :ref:`multicore_hello_world` sample is a multicore sample running on both the Application core (``cpuapp``) and the Peripheral Processor (PPR, ``cpuppr``). +It uses the ``nrf54h20dk_nrf54h20_cpuapp@soc1`` build target. + +To build and program the sample to the nRF54H20 PDK, complete the following steps: + +1. Connect the nRF54H20 PDK to you computer using the IMCU USB port on the PDK. +#. Navigate to the :file:`nrf/samples/multicore/hello_world` folder containing the sample. +#. Build the sample by running the following command:: + + west build -b nrf54h20dk_nrf54h20_cpuapp@soc1 + +#. Program the sample using nrfjprog. + If you have multiple Nordic Semiconductor devices, make sure that only the nRF54H20 PDK you want to program is connected. + + .. code-block:: console + + west flash + +The sample will be automatically built and programmed on both the Application core and the Peripheral Processor (PPR) of the nRF54H20. + +.. _nrf54h20_sample_reading_logs: + +Reading the logs +**************** + +With the :ref:`multicore_hello_world` sample programmed, the nRF54H20 PDK outputs logs for the application core and the peripheral processor. +The logs are output over UART. + +To read the logs from the :ref:`multicore_hello_world` sample programmed to the nRF54H20 PDK, complete the following steps: + +1. Connect to the PDK with a terminal emulator (for example, `Serial Terminal from nRF Connect for Desktop`_) using the following settings: + + * Baud rate: 115200 + * 8 data bits + * 1 stop bit + * No parity + * HW flow control: None + +#. Press the **Reset** button on the PCB to reset the PDK. +#. Observe the console output for both cores: + + * For the application core, the output should be as follows: + + .. code-block:: console + + *** Booting Zephyr OS build v2.7.99-ncs1-2193-gd359a86abf14 *** + Hello world from nrf54h20dk_nrf54h20_cpuapp + + * For the PPR core, the output should be as follows: + + .. code-block:: console + + *** Booting Zephyr OS build v2.7.99-ncs1-2193-gd359a86abf14 *** + Hello world from nrf54h20dk_nrf54h20_cpuppr + +.. note:: + If no output is shown when using nRF Serial Terminal, select a different serial port in the terminal application. + +See the :ref:`ug_nrf54h20_logging` page for more information. + +Install |nRFVSC| +**************** + +To open and compile projects in the |NCS| for the initial limited sampling of the nRF54H20, you can now install and use also the |nRFVSC|. + +.. _installing_vsc: + +|vsc_extension_description| +For installation and migration instructions, see `How to install the extension`_. + +.. note:: + After the installation of both Visual Studio Code and the |nRFVSC| extension, you have to manually point Visual Studio Code to the folder where nrfutil is installed. + To do so, manually set the ``nrf-connect.nrfutil.home`` option in the user settings of Visual Studio Code. + Usually, the location is :file:`${env:HOME}/.nrfutil` on macOS and Linux, or :file:`${env:USERPROFILE}/.nrfutil` on Windows. + +For other instructions related to the |nRFVSC|, see the `nRF Connect for Visual Studio Code`_ documentation site. + +Next steps +********** + +You are now all set to use the nRF54H20 PDK. +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_app_samples` to see the available samples for the nRF54H20 PDK for the initial limited sampling. +* The :ref:`introductory documentation ` for more information on the |NCS| and the development environment. diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_logging.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_logging.rst new file mode 100644 index 000000000000..df39bb4b3339 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_logging.rst @@ -0,0 +1,190 @@ +:orphan: + +.. _ug_nrf54h20_logging: + +nRF54H20 logging +################ +.. contents:: + :local: + :depth: 2 + +To read logs on the nRF54H20 PDK, you can use the following methods: + +* A direct UART connection to a specific core. +* Local domain logging with System Trace Macrocell (STM). + STM has two modes: + + * Standalone logging + * Assisted multicore logging + +For general information on how logging works in the |NCS|, consult the :ref:`ug_logging` and :ref:`zephyr:logging_api` documentation pages. + +nRF54H20 logging using a direct UART connection +*********************************************** + +Similarly to other SoCs from Nordic Semiconductor, to use a UART connection for reading logs, follow the :ref:`ug_logging_backends_uart` logging guide in the application development section. + +nRF54H20 logging using System Trace Macrocell (STM) +*************************************************** + +nRF54H20 domains contain ARM Coresight System Trace Macrocell (STM) hardware devices for collecting trace data from multiple domains, using either standalone logging or assisted multicore logging. +The STM uses memory-mapped registers to write trace data generated by the domains in the system. +It multiplexes the data as trace protocol data, formatted according to the MIPI System Trace Protocol (STP) v2, and synchronizes the data on a single output, such as a single UART. +This approach has a minimal cost on performance and code size, allowing for a non-intrusive collection of system debug-and-trace information. + +The STM implements a frontend of the Zephyr logging subsystem, allowing you to use the standard Zephyr logging API. + +.. note:: + + Currently, only the :ref:`multicore_hello_world` sample supports STM logging. + +Embedded Trace Router (ETR) +=========================== + +The Embedded Trace Router (ETR) is a hardware feature that provides a circular buffer in RAM for trace data. +It can trigger interrupts when the buffer is half-full or full, allowing the CPU to be woken up in time to handle the data. +The ETR buffer size is limited to 4 Kb, and it requires additional formatting with 16-byte frames. + +When using ETR, one of the cores is designated as a *proxy* to manage the trace data. + +.. note:: + Currently, the Secure Domain is the only core that can be designated as proxy. + +The proxy core is responsible for handling the data from the ETR and outputting it through the desired transport mechanism (like UART or USB). +The proxy core approach allows for on-chip data processing, offering more flexibility than the Trace Port Interface Unit (TPIU). +However, due to the limited size of the ETR buffer, there is a risk of data loss if not handled promptly. + +Standalone logging +================== + +The current implementation for the standalone logging mode with STM works as follows: + +1. All domains write the raw encoded log data to their own STM peripheral called the STM Extended Stimulus Port (STMESP). +#. The STMESP generates a data stream based on the register writes. +#. The STM multiplexes the data stream with streams from other domains, and it places them in the single memory buffer provided by the ETR. +#. The Secure Domain Firmware (SDFW), acting as the ETR-designated proxy, reads the buffer and decodes the raw encoded log data. +#. The SDFW outputs the logging data in a human-readable format over UART. + +Standalone logging leverages the frontend API of the Zephyr logging subsystem to select the stimulus ports and writes log messages directly to memory-mapped registers. +This method bypasses the need for string formatting functions and peripheral drivers, as the core writes directly to the STM port. + +Configuration +------------- + +To show the logs for a given domain in the UART output, you must enable the STM for that domain. + +To enable the STM for a domain, set the :kconfig:option:`CONFIG_LOG_STM` Kconfig option for that domain's image to ``y``. +The STM will be enabled by the build system in the configuration of the SDFW. + +Reading the logs +---------------- + +To read the STM log output on the UART, consult the following documentation pages: + +* If you want to use the *nRF Serial Terminal* from the |nRFVSC|, see the `nRF Terminal documentation`_ on the `nRF Connect for Visual Studio Code`_ documentation site. +* If you want to use PuTTY, see :ref:`putty`. + +.. note:: + To use UART in your application, the UART's node must be described in devicetree. + For more details, see :ref:`zephyr:devicetree-intro`. + +The following is an example log output:: + + [00:00:00.154,790] app/spsc_pbuf: alloc in 0x2f0df800 + [00:00:00.163,319] app/spsc_pbuf: alloc 0x2f0df800 wr_idx:20 + [00:00:00.181,112] app/spsc_pbuf: commit in 0x2f0df800 + [00:00:00.189,090] app/spsc_pbuf: commit 0x2f0df800, len:20 wr_idx: 44 + [00:00:00.202,577] rad/icmsg: mbox_callback + [00:00:00.214,750] rad/spsc_pbuf: claim 0x2f0df800 rd_idx:20 + [00:00:00.235,823] rad/spsc_pbuf: free 0x2f0df800 len:20 rd_idx: 44 + [00:00:00.244,507] rad/spsc_pbuf: read done 0x2f0df800 len:20 + [00:00:00.272,444] rad/host: ep recv 0x330021f0, len:20 + [00:00:00.283,939] rad/host: rx:00 exp:00 + [00:00:00.292,200] rad/icmsg: read 0 + [00:00:05.077,026] rad/spsc_pbuf: alloc in 0x2f0df000 + [00:00:05.077,068] rad/spsc_pbuf: alloc 0x2f0df000 wr_idx:44 + [00:00:05.077,098] rad/spsc_pbuf: commit in 0x2f0df000 + [00:00:05.077,134] rad/spsc_pbuf: commit 0x2f0df000, len:20 wr_idx + +Each log line contains a domain-related or core-related prefix between the log level and the module name, indicating the core that generated the log entry. +The following are the prefixes used to indicate the cores: + +.. csv-table:: nRF54H20 log prefixes + :header: "Core", "Prefix" + + Secure Domain, ``sec`` + Application core, ``app`` + Radio core, ``rad`` + System Controller (SysCtrl), ``sys`` + Fast Lightweight Processor (FLPR), ``flpr`` + Peripheral Processor (PPR), ``ppr`` + +Assisted multicore logging +========================== + +Assisted multicore logging uses dictionary-based logging to send messages without redundant strings to STM, and is based on the :ref:`logging_guide_dictionary` feature of the logging API provided by Zephyr. +Instead of including the format strings in the log messages, it logs the addresses (message IDs) where the strings are stored, which reduces the size of the logging subsystem. +If the data goes to the ETR buffer, the proxy core's responsibility is to dump this data. +The host PC, equipped with a decoder tool, translates these addresses back into human-readable text using a JSON database generated during the build process. + +When using logs, this method has the following advantages: + +* It reduces the size of the binary, as the strings used in the log messages are not stored in the binary itself. +* It reduces the amount of data that needs to be sent to and processed by the application core, as the string formatting is offloaded to the host side. + +Configuration +------------- + +To enable the assisted multicore logging for a domain, set the :kconfig:option:`CONFIG_LOG_STM_DICT` Kconfig option for that domain's image to ``y``. + +After building your application, a dictionary database file named :file:`log_database.json` will be generated in the :file:`build/zephyr` directory. +This file is crucial for decoding the logs and is updated with every build. + +Reading the logs +---------------- + +To read the dictionary-based STM log output, do the following: + +1. Set up the log capture. + + Use the ``nrfutil trace stm`` command to start capturing logs from the device, specifying the database configuration for each domain ID, as well as the serial port, the baud rate, and the output file name:: + + nrfutil trace stm --database-config 33:build/secdom/src/secdombuild/zephyr/log_dictionary.json,34:build/zephyr/log_dictionary.json --input-serialport /dev/ttyACM1 --baudrate 115200 --output-ascii out.txt + +#. Capture and decode the logs. + + nrfutil will capture the log data from the specified UART port and use the provided dictionary databases to decode the logs into a human-readable format. + The decoded logs will be saved in the specified output file (the :file:`out.txt` file in the previous example). + +#. Open the output file to review the decoded log messages. + + The file will contain timestamps and the log messages in a format that is human-readable. + +If the log capture fails to find a sync, rerun the capture process. + +.. note:: + Decoding artifacts or incorrect timestamps might occur when rerunning the process. + +Each log line contains a domain-related or core-related prefix between the log level and the module name, indicating the core that generated the log entry. +The following are the prefixes used to indicate the cores: + +.. csv-table:: nRF54H20 log prefixes + :header: "Core", "Prefix", "ID" + + Secure Domain, ``sec``, 0x21 + Application core, ``app``, 0x22 + Radio core, ``rad``, 0x23 + System Controller (SysCtrl), ``sys``, 0x2c + Fast Lightweight Processor (FLPR), ``flpr``, 0x2d + Peripheral Processor (PPR), ``ppr``, 0x2e + , ``mod``, 0x24 + +Additional considerations +------------------------- + +When using assisted multicore logging, consider the following: + +* Use optimized log macros (having up to 2 word size numeric arguments, like ``LOG_INF("%d %c", (int)x, (char)y)``) to improve the size and speed of logging. +* For memory constrained applications (for example, when running on the PPR or FLPR cores), disable the ``printk()`` function by setting both the :kconfig:option:`CONFIG_PRINTK` and :kconfig:option:`CONFIG_BOOT_BANNER` Kconfig options to ``n`` in your project configuration. +* When working with multiple domains, such as the Secure Domain and Application core, ensure that each database is prefixed with the correct domain ID. +* Some log messages might be dropped due to the limited size of the RAM buffer that stores STM logs. diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_matter_thread.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_matter_thread.rst new file mode 100644 index 000000000000..df4b33122008 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_matter_thread.rst @@ -0,0 +1,309 @@ +:orphan: + +.. _ug_nrf54h20_matter_thread: + +Working with nRF54H20 and Matter and Thread +########################################### + +.. contents:: + :local: + :depth: 2 + +.. caution:: + + The limited customer sampling version of the |NCS| is affected by the OpenThread KeyID Mode 2 Security Vulnerability. + This vulnerability impacts all Thread devices using OpenThread and allows an attacker in physical proximity to compromise non-router-capable devices and the entire Thread network in the case of router-capable devices. + The vulnerability allows an attacker in physical proximity to inject arbitrary IPv6 packets into the Thread network via IEEE 802.15.4 frame transmissions. + Because the Thread Management Framework (TMF) protocol does not have any additional layer of security, the attacker could exploit this vulnerability to update the Thread Network Key and gain full access to the Thread network. + There is no known exploitation of vulnerability. + + Due to this issue, the Thread certifications for OpenThread libraries in all |NCS| releases up to v2.4.0, which the limited customer sampling is based on, are deprecated. + +Starting with the ``v2.2.99-cs1-dev1`` limited customer sampling tag, the nRF54H20 PDK supports the following Matter and Thread samples: + +* :ref:`Matter door lock sample ` +* :ref:`Matter template sample ` +* :ref:`Thread CLI sample ` + +The Matter support is currently limited to Matter over Thread, and support for both Matter and Thread is currently :ref:`experimental `. +Read the following sections for more information about support in the nRF54H20 PDK and the platform design for the nRF54H20 SoC. + +For more information about Matter and Thread in the |NCS|, read the documentation in the :ref:`ug_matter` and :ref:`ug_thread` protocol sections. + +Platform designs for the nRF54H20 SoC +************************************* + +Matter in the |NCS| supports the *System-on-Chip, multiprotocol* platform design for the nRF54H20 SoC using Matter over Thread. +You can read more about other available platform designs for Matter on the :ref:`Matter platform design page`. + +Thread in the |NCS| supports the *System-on-Chip, single protocol* and *System-on-Chip, multiprotocol* platform designs for the nRF54H20 SoC. +You can read more about other available platform designs for Thread on the :ref:`OpenThread architectures page`. + +For more information about the multiprotocol feature, see :ref:`ug_multiprotocol_support`. + +System-on-Chip, single protocol +=============================== + +In this design, the OpenThread stack runs on several cores and domains of a single nRF54H20 SoC. + +This platform designs is suitable for the following development kit: + +##TODO add to /includes/sample_board_rows.txt + +In this design: + +* The Application Core runs the OpenThread stack. +* The Radio Core runs the component of the OpenThread stack that is related to the 802.15.4 IEEE Radio Driver. +* The Secure Domain stores all the secure components, including keys and certificates. + It also manages the access to peripherals, memory, and other components. + + .. note:: + The PSA crypto API level 3 for storing security components is not yet implemented on the Secure Domain. + +* The Global Domain manages clocks, power, global RAM, and global NVM. + +For more information, see :ref:`ug_nrf54h20_architecture_cpu`. + +The following figure demonstrates the architecture. +The Global Domain is not included. + +.. figure:: images/thread_platform_design_nRF54h20.svg + :alt: Multiprotocol Thread and Bluetooth LE architecture (nRF54H20) + + Single protocol Thread architecture on the nRF54H20 SoC + +System-on-Chip, multiprotocol +============================= + +In this design, the OpenThread stack and the Bluetooth® Low Energy (LE) stack run on several cores and domains of a single nRF54H20 SoC. + +This platform design is suitable for the following development kit: + +##TODO add to /includes/sample_board_rows.txt + +In this design: + +* The Application Core runs the OpenThread stack, and a part of the Bluetooth LE Controller. +* The Radio Core runs both the Bluetooth LE Controller and the component of the OpenThread stack that is related to the 802.15.4 IEEE Radio Driver. +* The Secure Domain stores all the secure components, including keys and certificates. + It also manages the access to peripherals, memory, and other components. + + .. note:: + The PSA crypto API level 3 for storing security components is not yet implemented on the Secure Domain. + +* The Global Domain manages clocks, power, global RAM, and global NVM. + +For more information, see :ref:`ug_nrf54h20_architecture_cpu`. + +The following figure demonstrates the architecture. +The Global Domain is not included. + +.. _nrf54h20_platform_multi_figure: + +.. figure:: images/thread_platform_design_nRF54h20_multi.svg + :alt: Multiprotocol Thread and Bluetooth LE architecture (nRF54H20) + + Multiprotocol Thread and Bluetooth LE architecture on the nRF54H20 SoC + +Matter over Thread +================== + +In this design, the Matter stack, the OpenThread stack, and the Bluetooth® Low Energy (LE) stack run on several cores and domains of a single nRF54H20 SoC. + +This platform design is suitable for the following development kit: + +##TODO add to /includes/sample_board_rows.txt + +In this design: + +* The Application Core runs the Matter stack, the OpenThread stack, and a part of the Bluetooth LE Controller. +* The Radio Core runs both the Bluetooth LE Controller and the component of the OpenThread stack that is related to the 802.15.4 IEEE Radio Driver. +* The Secure Domain stores all the secure components, including keys and certificates. + It also manages the access to peripherals, memory, and other components. + + .. note:: + The PSA crypto API level 3 for storing security components is not yet implemented on the Secure Domain. + +* The Global Domain manages clocks, power, global RAM, and global NVM. + +For more information, see :ref:`ug_nrf54h20_architecture_cpu`. + +Refer to the :ref:`nrf54h20_platform_multi_figure` figure to see the architecture of the SoC. +The Global Domain is not included. + +Additional requirements on the nRF54H20 PDK +******************************************* + +In addition to the standard requirements for the |NCS|, such as the :ref:`ug_matter_gs_tools_gn` for Matter, you need the following to run Matter-enabled or Thread-enabled applications on the nRF54H20 PDK: + +* For DFU - J-Link and a USB cable. +* The compatible version of the nrfjprog tool, included in the :ref:`nRF Command Line Tools version specific to the limited customer sampling`. + +Configuring Matter and Thread on the nRF54H20 PDK +************************************************* + +Currently, only the configuration for Matter over Thread is supported for Matter. +Follow the configuration steps on the :ref:`ug_matter_gs_testing` page to configure the Matter environment for the supported Matter samples. + +Currently, only the :ref:`ot_cli_sample` sample is supported for Thread. +See the sample documentation for how to configure it. + +The Matter and Thread samples included in the limited customer sampling can work on the corresponding networks with standard devices of the same protocol. + +Programming Matter and Thread samples on the nRF54H20 PDK +========================================================= + +To program the compatible Matter or Thread samples on the nRF54H20 PDK, follow the :ref:`ug_nrf54h20_gs_sample` steps. +Read also programming guides prepared for specific Matter samples: :ref:`Matter door lock sample `, and :ref:`Matter template sample `. + +.. note:: + :ref:`Testing using Bluetooth LE with Nordic UART Service ` on the :ref:`Matter door lock sample ` is disabled by default. + +Logging for Matter and Thread samples on the nRF54H20 PDK +========================================================= + +To read logs for Matter samples on the nRF54H20 PDK, complete the following steps: + +1. Connect to the nRF54H20 PDK using a USB cable. +#. Select the first available port to read the logs from. + +For more information, see :ref:`ug_nrf54h20_logging`. + +.. _ug_nrf54h20_matter_thread_matter_wifi: + +Matter over Wi-Fi +================= + +Matter over Wi-Fi is currently supported on the :ref:`Matter door lock sample ` and :ref:`Matter template sample `. + +In this design, the Matter stack, the Wi-Fi stack, and the Bluetooth® Low Energy (LE) stack run on several cores and domains of a single nRF54H20 SoC. + +To run Matter over Wi-Fi on the nRF54H20 PDK you need the additional ``nrf7002_ek`` shield attached through the nRF54H20 PDK to the nRF7002 EK interposer board. + +In this design: + +* The Application Core runs the Matter stack, the Wi-Fi stack, and a part of the Bluetooth LE Controller. +* The Radio Core runs both the Bluetooth LE Controller and the component of the OpenThread stack that is related to the 802.15.4 IEEE Radio Driver. +* The Secure Domain stores all the secure components, including keys and certificates. + It also manages the access to peripherals, memory, and other components. + + .. note:: + The PSA crypto API level 3 for storing security components is not yet implemented on the Secure Domain. + +* The Global Domain manages clocks, power, global RAM, and global NVM. + +To build the sample with Matter over Wi-Fi support run the following command: + +.. code-block:: console + + west build -b nrf54h20dk_nrf54h20_cpuapp@soc1 -- -DCONF_FILE=prj_no_dfu.conf -DSHIELD=nrf700x_nrf54h20dk -DCONFIG_CHIP_WIFI=y + + +.. _ug_nrf54h20_matter_thread_suit_dfu: + +SUIT Device Firmware Upgrade support on the nRF54H20 PDK +======================================================== + +The :ref:`SUIT Device Firmware Upgrade ` feature has been implemented on the nRF54H20 PDK and you can use it in the :ref:`Matter door lock sample `. +In this solution, both Application and Radio Cores can be upgraded sequentially to the newest version using :ref:`SUIT hierarchical manifests `. +The SUIT DFU feature uses :ref:`SUIT manifests ` that contain components and images of the firmware and are used by the Secure Domain to replace, verify and run the firmware. +In the Matter Lock sample, we use the Simple Management Protocol (SMP) over Bluetooth LE transport to deliver the new firmware to the device's DFU partition and then the SUIT processor installs the image according to the instructions that are described in the manifest. +By default, the root manifest contains both Application and Radio Core images, but for the Matter sample the images need to be split to the separate cores and perform upgrades sequentially. +Currently, there is no protection against incompatibility between the new Radio Core and old Application Core images, so you need to ensure that compatibility. +We have prepared manifest templates in the ``configurations/nrf54h20dk_nrf54h20_cpuapp`` directory in the Matter lock sample which are prepared to generate two separate SUIT envelopes - one for the Application Core and another for the Radio Core. They are as follows: + + * :file:`app_envelope.yaml.jinja2` - Contains the procedures for SUIT directives that allow for the Application Core image to be updated. + * :file:`app_envelope.yaml.jinja2.digest` - Contains the digital signature of the SUIT manifest prepared for the Application Core image. + * :file:`multiprotocol_rad_envelope.yaml.jinja2` - Contains the procedures for SUIT directives that allow for the Radio Core image to be updated. + * :file:`multiprotocol_rad_envelope.yaml.jinja2.digest` - Contains the digital signature of the SUIT manifest prepared for the Radio Core image. + * :file:`root_hierarchical_envelope.yaml.jinja2` - Contains the procedures for SUIT directives to run the current firmware. + * :file:`root_hierarchical_envelope.yaml.jinja2.digest` - Contains the digital signature of the SUIT manifest prepared for running the current firmware. + +You can edit the templates for other purposes. +To learn how to do edit the manifest templates, see the :ref:`ug_nrf54h20_suit_customize_dfu` guide. + +To build the firmware with the SUIT DFU support, run the following command with the *number* replaced with the new image number, that should be higher than the previous one: + +.. parsed-literal:: + :class: highlight + + west build -b nrf54h20dk_nrf54h20_cpuapp -- -DCONFIG_SUIT_ENVELOPE_SEQUENCE_NUM=*number* + +You can perform a DFU using the nRF Connect Device Manager mobile application or the :ref:`Mcumgr command-line tool `. +After building the sample you can find two SUIT envelopes created in the build directory and depending on the core type you can search for: + + * the :file:`build/zephyr/app.suit` file to get the SUIT envelope for the Application Core. + * the :file:`build/multiprotocol_rpmsg/zephyr/multiprotocol_rpmsg_subimage.suit` file to get the SUIT envelope for the Radio Core. + +To learn how to perform a DFU using the nRFConnect Device Manager mobile application read instructions in the ``suit smp transfer `` guide. + +Performing DFU on nRF54H20 PDK using Mcumgr command-line tool +------------------------------------------------------------- + + 1. Follow the instructions in the :ref:`Mcumgr command-line tool ` guide to install Mcumgr. + #. Press **Button 1** to enable Bluetooth LE SMP advertising on the nRF54H20 PDK. + #. Run the following command to upgrade the Radio Core: + + .. parsed-literal:: + :class: highlight + + mcumgr --conntype ble --hci *hci number* --connstring peer_name=*peer name* image upload *path to multiprotocol_rpmsg_subimage.suit* -n 0 -w 1 + + Where: + + * *hci number* is the Bluetooth LE device ID on your host device (by default it is ``0``). + * *peer name* is the Bluetooth LE name which is advertised by the nRF54H20 PDK (by default ``"Matter Lock"``). + * *path to multiprotocol_rpmsg_subimage.suit* is a path to the SUIT envelope that contains Radio Core image. + + For example: + + .. parsed-literal:: + :class: highlight + + mcumgr --conntype ble --hci 0 --connstring peer_name="MatterLock" image upload build/multiprotocol_rpmsg/zephyr/multiprotocol_rpmsg_subimage.suit -n 0 -w 1 + + #. Press **Button 1** to enable Bluetooth LE SMP advertising on the nRF54H20 PDK again, because the previous operation disabled it after applying the image. + #. Run the same command as in Step 3 to upgrade the Application Core image, but this time provide a path to the ``app.suit`` file. + + For example: + + .. parsed-literal:: + :class: highlight + + mcumgr --conntype ble --hci 0 --connstring peer_name="MatterLock" image upload build/zephyr/app.suit -n 0 -w 1 + + +Implementing support for the nRF54H20 PDK +========================================= + +If you want to implement support for the nRF54H20 PDK in your Matter-enabled or Thread-enabled application, read the :ref:`ug_nrf54h20_configuration` guide. + +.. _ug_nrf54h20_matter_thread_limitations: + +Limitations for Matter and Thread on the nRF54H20 PDK +***************************************************** + +Matter and Thread support has the following limitations on the nRF54H20 PDK: + +* DFU over Matter or Serial Link is not yet implemented. +* The current implementation is not power-optimized. +* The cryptographic operations related to Matter and Thread are performed on the Application Core, rather than on the Secure Domain. +* The ``west flash --erase`` command is blocked. + See :ref:`ug_nrf54h20_gs_sample` for more information. +* The factory reset functionality does not work properly. + After clearing all NVM storage, the device can not reboot automatically and falls into a hard fault. + + As a workaround, press the reset button on the nRF54H20 PDK board after performing a factory reset. +* Matter over Thread commissioning might be unstable due to the lack of true random generator support on nRF54H20. + + After each reboot or factory reset, the device will always have the same Bluetooth LE and IEEE 80215.4 addresses. + This might impact working within the Thread network because after the second and following connections, Thread Border Router will reject these connections until deleted from the database and commissioning to Matter will take more and more time. + + As a workaround, after each factory reset and before performing the next commissioning to Matter, connect to the device's serial port and run the following command: + + .. parsed-literal:: + :class: highlight + + ot extaddr *address* + + Replace the *address* argument with an 8-byte randomly generated MAC address, for example ``87fb47d5730ac0a0``. diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_components.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_components.rst new file mode 100644 index 000000000000..e4443c37fb27 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_components.rst @@ -0,0 +1,127 @@ +:orphan: + +.. _ug_nrf54h20_suit_components: + +SUIT components +############### + +.. contents:: + :local: + :depth: 2 + +:ref:`Components ` are the fundamental elements that the SUIT manifest operates on and are declared in :ref:`suit-common ` (which is represented as the bstr CBOR value ``suit-common`` within the manifest). +Using and modifying the component types allows for operational, fine-tuned customization of the DFU procedure. + +See the :ref:`component_ID` section for more information. + +Component types +*************** + +The current available component types are as follows: + +* ``MEM`` - MCU memory-mapped slot (such as the MRAM or RAM). + This is used to define a specific area in the memory where an image can be placed, and by default, it is defined automatically from the build system. + The memory components are the abstractions that map to memory locations on the device's memory. + +* ``CAND_MFST`` - The candidate manifest component refers to the dependency candidate in the envelope or in the download cache. + Different values allow you to declare more than one component of that type per manifest. + It points to the candidate manifest instead of copying the content to a memory location. + For example, if an envelope contains all the candidate manifests, then you can refer to the manifest in the envelope using the candidate manifest component. + +* ``CAND_IMG`` - The candidate image component refers to the integrated payload in the candidate envelope or payload in the download cache. + For example, the ``CAND_IMG`` component allows you to validate the candidate before the installation step is performed. + + The following example shows the installation procedure, including the checking of the coherency of the image by using the ``CAND_IMG`` component. + During the installation process, ``directive-fetch`` puts information about the location of the image into component candidate image ``0``. + ``condition-image-match`` performs the digest check on the candidate image ``0`` and verifies the digest of the image. + After the verification, the installation of the image at the final location is done by the ``directive-copy``. + + .. code-block:: console + + components: [ + [MEM/2/0xeff8000/0x10000], + [CAND_IMG/0] + ] + + install: [ + directive-set-component-index 1, + directive-override-parameters { + uri: '#file.bin' + image-digest: [ + algorithm-id: "sha256", + digest-bytes: '00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' + ] + }, + directive-fetch, + condition-image-match, + directive-set-component-index 0, + directive-override-parameters { + source-component: 1 + }, + directive-copy + ] + +* ``INSTLD_MFST`` - The installed manifest component is the slot for the envelope containing the installed manifest, which holds the severed manifest and its authentication block. + It points to the manifest, which is already installed. + +* ``SOC_SPEC`` - SOC-specific components are reserved for Nordic internal usage. + The installation of this component type goes beyond memory CPU-like operations. + +* ``CACHE_POOL`` - The ``CACHE_POOL`` is a space where images downloaded during the ``payload-fetch`` sequence execution can be stored and are ready for installation. + In the context of the Application Domain, the ``payload-fetch`` sequence can contain instructions to fetch images from external sources (such as an HTTP server). + Typically, these images must not be installed directly into the destination components by the ``payload-fetch`` sequence. + They must be verified and installed by the ``install`` sequence, executed in the context of the SDFW or bootloader. + + + ``CACHE_POOL`` allows you to push the envelope to the device, but without any payloads. + When the manifest is processed, it may evaluate what is currently installed on the device. + For example, the manifest calculates the digests of specific images, and based on those calculations, it fetches missing images from outside. + + When the value of ``CACHE_POOL`` is: + + * ``0`` - describes a location in the DFU partition, located right after the candidate envelope. + When the ``CACHE_POOL`` value is ``0``, it is directly accessible by the SDFW, therefore, it may be used to store a companion image that, when executed on the Application MCU, allows the SDFW to access otherwise unsupported memory areas (such as external flash). + + * ``1..n`` - describes a deployment-specific ``CACHE_POOL`` such as, for example, external flash partitions or other MRAM partitions. + It defines multiple different cache pools. + + **Benefits of the ``CACHE_POOL`` component** + + The following are the benefits of the ``CACHE_POOL`` component: + + * Memory optimization - ``CACHE_POOL`` component allows you to conditionally pull missing images from the Application Domain or application framework before installation starts. + It helps in the gradual update process by installing one of the two images in the first installation step and then repeating the process to install another image. + + * Save on data transfer costs - The manifest and the candidate manifest only pull the missing images instead of pushing all the images in the update. + +.. _component_ID: + +Component ID parameters +*********************** + +The component types that can be modified at this time are listed in the following table. +Fields indicate different parameters for component types. + ++----------------------+--------------------------------------------------------+------------------------+------------------------+--------------+----------------------------------------------------------------------------------+ +| Field 0 - Type | Field 1 | Field 2 | Field 3 | Field 4 | Component ID - example | ++======================+========================================================+========================+========================+==============+==================================================================================+ +| ``MEM`` | CPU ID: ``int`` | Slot address: ``uint`` | Slot size: ``uint`` | | Application MCU bootable: | +| | | | | | | +| | (``-1`` indicates no booting capability) | | | | ``MEM/2/0xeff8000/0x10000`` | ++----------------------+--------------------------------------------------------+------------------------+------------------------+--------------+----------------------------------------------------------------------------------+ +| ``CAND_MFST`` | ID: ``uint`` | | | | ``CAND_MFST/0`` | ++----------------------+--------------------------------------------------------+------------------------+------------------------+--------------+----------------------------------------------------------------------------------+ +| ``CAND_IMG`` | ID: ``uint`` | | | | ``CAND_IMG/0`` | ++----------------------+--------------------------------------------------------+------------------------+------------------------+--------------+----------------------------------------------------------------------------------+ +| ``INSTLD_MFST`` | Manifest Class ID: ``bst`` | | | | ``INSTLD_MFST/0x3f6a3a4dcdfa58c5accef9f584c41124`` | ++----------------------+--------------------------------------------------------+------------------------+------------------------+--------------+----------------------------------------------------------------------------------+ +| ``SOC_SPEC`` | ID: ``uint`` | | | | nRF54H20: | +| | | | | | | +| | Identifier valid within the namespace of a specific | | | | ``SOC_SPEC/1`` - SDFW | +| | SOC. | | | | | +| | | | | | ``SOC_SPEC/2`` - SDFW_Recovery | ++----------------------+--------------------------------------------------------+------------------------+------------------------+--------------+----------------------------------------------------------------------------------+ +| ``CACHE_POOL`` | ID: ``uint`` | | | | ``CACHE_POOL`` in DFU Partition (MRAM): | +| | | | | | | +| | | | | | ``CACHE_POOL/0`` | ++----------------------+--------------------------------------------------------+------------------------+------------------------+--------------+----------------------------------------------------------------------------------+ diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_customize_dfu.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_customize_dfu.rst new file mode 100644 index 000000000000..546135c63c71 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_customize_dfu.rst @@ -0,0 +1,606 @@ +:orphan: + +.. _ug_nrf54h20_suit_customize_dfu: + +How to customize the SUIT DFU process +##################################### + +.. contents:: + :local: + :depth: 2 + +Nordic Semiconductor provides a SUIT sample (``nrf54h_suit_sample``) in which the build system uses predefined configuration. +The specified Kconfig options in the sample can be used to modify the artifacts produced by the build system, customize the DFU process, and integrate the DFU solution with external build systems. + +.. note:: + In order to customize the SUIT DFU process, we strongly recommend that you modify the values in the manifest that are associated with the ID values that are configured into the device. + This includes both the ``class-identifier`` and ``vendor-identifier`` values found in manifest(s). + + For additional modifications mentioned in this guide, see the :ref:`ug_nrf54h20_suit_components` page. + +This guide provides a range of instructions and details for how to modify values in the SUIT manifest. +See the :ref:`ug_suit_customize_manifest_quick` section of this document for brief instructions on how to make modifications. + +Build system configuration +========================== + +SUIT envelopes are created by processing the input manifest templates, which are filled in with the appropriate values by the build system as one of the last steps of the build command. +Nordic Semiconductor provides a set of default manifest templates that can be used out-of-the-box for development and demonstration purposes, although some customization for UUIDs used in the manifest templates is highly recommended. +For more information about adding custom UUID values, see the :ref:`ug_suit_using_manifest_gen` section of this document. + +.. note:: + The manifest templates are automatically copied to the sample directory upon the first build. + +To demonstrate this, we can look at the ``nrf54h_suit_sample``. +After the first build, among others, three additional files are created in the :file:`nrf/samples/suit/smp_transfer` directory (alternatively, two levels above the build directory when the ``west -d`` parameter is used): + +* The root manifest - :file:`root_hierarchical_envelope.yaml.jinja2` + +* The Application Domain manifest - :file:`app_envelope.yaml.jinja2` + +* The Radio Domain manifest - :file:`rad_envelope.yaml.jinja2` + +The destination directory into which the :file:`jinja2` file templates are copied to can be changed from the sample root directory (:file:`nrf/samples/suit/smp_transfer`) to another directory by setting the :kconfig:option:`CONFIG_SUIT_ENVELOPE_EDITABLE_TEMPLATES_LOCATION` Kconfig option. + +.. note:: + + The Radio Domain manifest template is only available for the Bluetooth® Low Energy version of the ``nrf54h_suit_sample`` sample, and not the UART version. + +.. _ug_suit_change_manifest_location: + +How to change the location of the manifest templates +---------------------------------------------------- + +Let us assume that you would like to store the editable manifest templates in the ``C:\my_templates\`` directory for a Windows machine, or in ``/home/my_user/my_templates`` for Linux. + +.. tabs:: + + .. group-tab:: Windows + + Enter the following command to change the location where the editable manifest templates are stored: + + .. code-block:: console + + west build -d C:/ncs-lcs/work_dir/build/ -b nrf54h20dk_nrf54h20_cpuapp@soc1 -p -- -DCONFIG_SUIT_ENVELOPE_EDITABLE_TEMPLATES_LOCATION="C:/my_templates" + + .. group-tab:: Linux + + Enter the following command to change the location where the editable manifest templates are stored: + + .. code-block:: console + + west build -b nrf54h20dk_nrf54h20_cpuapp@soc1 -p -- -DCONFIG_SUIT_ENVELOPE_EDITABLE_TEMPLATES_LOCATION="/home/my_user/my_templates" + +The source of the manifest templates can be configured by setting the following Kconfig options: + +* :kconfig:option:`CONFIG_SUIT_ENVELOPE_ROOT_TEMPLATE` + +* :kconfig:option:`CONFIG_SUIT_ENVELOPE_APP_TEMPLATE` + +* :kconfig:option:`CONFIG_SUIT_ENVELOPE_HCI_RPMSG_SUBIMAGE_TEMPLATE` + +Changing the source of manifest templates allows you to create manifest files on your own, without relying on the templates provided by Nordic Semiconductor. + +.. _ug_suit_use_own_manifest: + +How to use your own manifest +---------------------------- + +Let us analyze the case where you would like to: + +* Use your own created manifest template + +* Store editable manifest templates in a custom directory + +.. tabs:: + + .. group-tab:: Windows + + The provided manifest templates are stored in ``C:\my_default_templates``. + Editable manifests should be stored in ``C:\my_templates``. + + .. group-tab:: Linux + + The provided manifest templates are stored in ``/home/my_user/my_default_templates``. + Editable manifests should be stored in ``/home/my_user/my_templates``. + +The following files should be used to create DFU envelope: + +* Root envelope - :file:`root.yaml.jinja2` + +* Application Domain - :file:`app.yaml.jinja2` + +* Radio Domain - :file:`radio.yaml.jinja2` + +.. figure:: images/nrf54h20_suit_example_update_process.png + :alt: Example update process + + Example update process + +To build the described example with the provided manifest templates taken from your customized source folder, and to store it in your customized destination folder: + +.. tabs:: + + .. group-tab:: Windows + + Run the following command: + + .. code-block:: console + + west build -d C:/ncs-lcs/work_dir/build/ -b nrf54h20dk_nrf54h20_cpuapp@soc1 -p -- -DCONFIG_SUIT_ENVELOPE_EDITABLE_TEMPLATES_LOCATION="c:/my_templates" -DCONFIG_SUIT_ENVELOPE_ROOT_TEMPLATE="c:/my_default_templates/root.yaml.jinja2" -DCONFIG_SUIT_ENVELOPE_APP_TEMPLATE="c:/my_default_templates/app.yaml.jinja2" -DCONFIG_SUIT_ENVELOPE_HCI_RPMSG_SUBIMAGE_TEMPLATE="c:/my_default_templates/radio.yaml.jinja2" + + .. group-tab:: Linux + + Run the following command: + + .. code-block:: console + + west build -b nrf54h20dk_nrf54h20_cpuapp@soc1 -p -- -DCONFIG_SUIT_ENVELOPE_EDITABLE_TEMPLATES_LOCATION="/home/my_user/my_templates" -DCONFIG_SUIT_ENVELOPE_ROOT_TEMPLATE="/home/my_user/my_default_templates/root.yaml.jinja2" -DCONFIG_SUIT_ENVELOPE_APP_TEMPLATE="/home/my_user/my_default_templates/app.yaml.jinja2" -DCONFIG_SUIT_ENVELOPE_HCI_RPMSG_SUBIMAGE_TEMPLATE="/home/my_user/my_default_templates/radio.yaml.jinja2" + +Editable manifest copied into the sample directory (or in the directory configured using the :kconfig:option:`CONFIG_SUIT_ENVELOPE_EDITABLE_TEMPLATES_LOCATION` Kconfig option) can be modified to edit the contents of the envelopes and modify the DFU process. +These files will not be overwritten by the build system during the next builds or in consecutive SDK releases. + +For more information about the Kconfig options used in this example, see the `SUIT Kconfig options `__. + +.. _ug_suit_modify_manifest_temps: + +Modify the manifest templates +============================= + +It is recommended to modify the manifest templates with your own UUIDs, which involves modifying the values for ``class-identifier`` and ``vendor-identifier``. + +The whole process of building a DFU envelope (which contains the manifests) can be summarized with the following diagram: + +.. figure:: images/nrf54h20_suit_generator_workflow.png + :alt: Modifying manifest templates workflow + + Modifying manifest templates workflow + +Manifest templates (``.jinja2``) files are rendered to YAML files. +These YAML files are used as a representation of the output binary SUIT envelopes. + +The provided manifest templates (``.jinja2``) files contain variables (represented as components), such as memory ranges, names, and paths to binaries. +The component values are filled out automatically by the build system during the manifest rendering. +However, there are some values which should be customized manually such as ``class-identifier`` and ``vendor-identifier`` + +An example of values that stay static the same are UUIDs used in the device or values (``class-identifier`` and ``vendor-identifier``) that are used to generate these UUIDs. + +.. _ug_suit_example_yaml: + +An example of a YAML representation for a basic installation and invoke-process of the Application firmware could look like the following: + +.. code-block:: + + SUIT_Envelope_Tagged: + suit-authentication-wrapper: + SuitDigest: + suit-digest-algorithm-id: cose-alg-sha-256 + suit-manifest: + suit-manifest-version: 1 + suit-manifest-sequence-number: 1 + suit-common: + suit-components: + - - MEM + - 0x02 + - 0x0E0AA000 + - 0x0007f800 + suit-shared-sequence: + - suit-directive-override-parameters: + suit-parameter-vendor-identifier: + RFC4122_UUID: nordicsemi.com # Vendor identifier value + suit-parameter-class-identifier: + RFC4122_UUID: # Class identifier values + namespace: nordicsemi.com + name: nRF54H20_sample_app + suit-parameter-image-digest: + suit-digest-algorithm-id: cose-alg-sha-256 + suit-digest-bytes: + file: ``/path/to/application_fw.bin`` + suit-parameter-image-size: + file: ``/path/to/application_fw.bin`` + - suit-condition-vendor-identifier: + - suit-send-record-success + - suit-send-record-failure + - suit-send-sysinfo-success + - suit-send-sysinfo-failure + - suit-condition-class-identifier: + - suit-send-record-success + - suit-send-record-failure + - suit-send-sysinfo-success + - suit-send-sysinfo-failure + suit-install: + - suit-directive-override-parameters: + suit-parameter-uri: '#app' + - suit-directive-fetch: + - suit-send-record-failure + suit-integrated-payloads: + '#app': ``/path/to/application_fw.bin`` + + +The ``class-identifier`` expresses the manifest class. +In other words, it expresses the manifest's intended usage. +For example, it expresses which manifest is meant to control the firmware images associated with the Application Domain. + +The ``vendor-identifier`` expresses which vendor the manifest belongs to. +For example "Nordic Semiconductor", or "ACME Corp" used in the examples provided in this document. + +The storing and processing of these variable-length strings would be impractical, therefore the ``RFC4122 uuid5`` is used. + +.. note:: + Default values of OEM-controlled manifests (related to the Application and Radio Domains) are hardcoded in the SDFW, but you can overwrite these values and this is strongly recommended. + +.. _ug_suit_modify_class_vend_id: + +Modify ``class-identifier`` and ``vendor-identifier`` +----------------------------------------------------- + +To update the ``class-identifier`` and ``vendor-identifier`` values in the :file:`app_envelope_yam.jinja2` file, edit the following lines as shown in this example: + +Before modification: + +.. code-block:: + + - suit-directive-override-parameters: + suit-parameter-vendor-identifier: + RFC4122_UUID: nordicsemi.com # Original vendor-identifier value + suit-parameter-class-identifier: + RFC4122_UUID: + namespace: nordicsemi.com # Original class-identifier values + name: nrf54H20_sample_app + + +After modification: + +.. code-block:: + + - suit-directive-override-parameters: + suit-parameter-vendor-identifier: + RFC4122_UUID: ACME Corp # Changed vendor-identifier value + suit-parameter-class-identifier: + RFC4122_UUID: # Changed class-identifier values + namespace: ACME Corp + name: Light bulb + + +Alternatively, you can also define raw values like so: + +Before modification: + +.. code-block:: + + - suit-directive-override-parameters: + suit-parameter-vendor-identifier: + raw: 7617daa571fd5a858f94e28d735ce9f4 # Original raw value + suit-parameter-class-identifier: + raw: 08c1b59955e85fbc9e767bc29ce1b04d # Original raw value + + +After modification: + +.. code-block:: + + - suit-directive-override-parameters: + suit-parameter-vendor-identifier: + raw: bf42bd2ea9895f22933b352cda1730d3 # Changed raw value + suit-parameter-class-identifier: + raw: e0f94076c46a5a1e80a18d3e674bdfe0 # Changed raw value + +Python to generate UUIDs +^^^^^^^^^^^^^^^^^^^^^^^^ + +Note that the UUID raw values in the previous example have been calculated using following Python commands: + +.. code-block:: python + + from uuid import uuid5 + vid = uuid5(uuid.NAMESPACE_DNS, 'ACME Corp') + print(vid) # Result being bf42bd2ea9895f22933b352cda1730d3 + cid = uuid5(vid, 'Light bulb') + print(cid) # Result being e0f94076c46a5a1e80a18d3e674bdfe0 + + +.. note:: + For the development releases (CS 0.2.0 and 0.3.0) only the predefined, presented values are supported. + +.. _ug_suit_var_methods_in_manifest: + +Variables and methods available in the manifest templates +========================================================= + +The manifest templates have access to the following: + +* Devicetree values (`edtlib object `__) + +* Target names + +* Paths to binary artifacts + +* Application version + +Some of these values are stored in the Python dictionaries that are named after the target name. +(Therefore, Python is used within the ``.jinja2`` files to fill in the necessary values in the manifest(s).) +For example, for the ``nrf54h_suit_sample`` there will be two variables available: ``app`` and ``hci_rpmsg_subimage``. +Each variable is a Python dictionary type (``dict``) containing the following keys: + +* ``name`` - name of the target + +* ``dt`` - Devicetree representation (`edtlib object `__) + +* ``binary`` - path to the binary, which holds the firmware for the target + +Additionally, the Python dictionary holds a variable called ``version`` that holds the application version. +With the Python dictionary you are able to, for example: + +* Extract the CPU ID by using ``app['dt'].label2node['cpu'].unit_addr`` + +* Obtain the partition address with ``app['dt'].chosen_nodes['zephyr,code-partition']`` + +* Obtain the size of partition with ``app['dt'].chosen_nodes['zephyr,code-partition'].regs[0].size`` + +* Get the pair of URI name and the binary path by using ``'#{{ app['name'] }}': {{ app['binary'] }}`` + +* Get the application version with ``suit-manifest-sequence-number: {{ version }}`` + +Additionally, the **get_absolute_address** method is available to recalculate the absolute address of the partition. +With these variables and methods, you can define templates which will next be filled out by the build system and use them to prepare the output binary SUIT envelope. +The examples below demonstrate the use of these variables and methods. + +.. _ug_suit_suit_set_comp_def_mem_range: + +Set component definition and memory ranges +------------------------------------------ + +In the :file:`app_envelope_yaml.jinja2` (found `here `__), the component definition and memory ranges are filled out by using the ``edtlib`` object like so: + +.. code-block:: + + suit-components: + - - MEM + - ``{{ app['dt'].label2node['cpu'].unit_addr }}`` + - ``{{ get_absolute_address(app['dt'].chosen_nodes['zephyr,code-partition']) }}`` + - ``{{ app['dt'].chosen_nodes['zephyr,code-partition'].regs[0].size }}`` + +Set integrated payload +---------------------- + +In the :file:`app_envelope_yaml.jinja2` (found `here `__, the integrated payload definition is done using the target name and binary location: + +.. code-block:: + + suit-integrated-payloads: + ``'#{{ app['name'] }}': {{ app['binary'] }}`` + +.. _ug_suit_root_manifest_temp: + +Root manifest template +---------------------- + +The :file:`root_hierarchical_envelope.yaml.jinja2` (found `here `__) contains content that is dynamically created, depending on how many targets are built. +The following example only shows a selected portion of the root manifest file. +For more information, see the file available in the sample and `Jinja `__ documentation: + +.. code-block:: + + {%- set component_index = 0 %} # Initialize the `component_index variable`. + # This variable will be used to assign component indexes dynamically depending on + # how many cores have been built. + + + {%- set component_list = [] %} # Initialize the `component_list variable`. + # This variable will be used to execute `suit-directive-set-component-index` over + # all components, except the first one with index 0. + + SUIT_Envelope_Tagged: + suit-authentication-wrapper: + SuitDigest: + suit-digest-algorithm-id: cose-alg-sha-256 + suit-manifest: + suit-manifest-version: 1 + suit-manifest-sequence-number: {{ version }} # Assign value defined in the `CONFIG_APP_VERSION` Kconfig option. + suit-common: + suit-components: + - - CAND_MFST + - 0 + {%- if hci_rpmsg_subimage is defined %} # Add section below only, in case the Radio Core has been already been built. + {%- set component_index = component_index + 1 %} # Increment `component_index`. + {%- set hci_rpmsg_subimage_component_index = component_index %} # Store the current component index for further use. + {{- component_list.append( hci_rpmsg_subimage_component_index ) or ""}} # Append the current component index to the common list. + - - INSTLD_MFST + - RFC4122_UUID: + namespace: nordicsemi.com + name: nRF54H20_sample_rad + {%- endif %} + {%- if app is defined %} + {%- set component_index = component_index + 1 %} + {%- set app_component_index = component_index %} + {{- component_list.append( app_component_index ) or ""}} + - - INSTLD_MFST + - RFC4122_UUID: + namespace: nordicsemi.com + name: nRF54H20_sample_app + {%- endif %} + +.. _ug_suit_ref_for_edit_manifest: + +Reference for editing manifest values +------------------------------------- + +Some entries in the YAML file will filled in automatically, (upon first build of the sample) by the build system in the final binary DFU envelope. + ++---------------------------------------------------------+------------------------------+------------------------------------------------+ +| Operation | YAML entry | Value in the output binary envelope | ++=========================================================+==============================+================================================+ +| UUID calculation | RFC4122_UUID: | ``3f6a3a4dcdfa58c5accef9f584c41124`` | +| | namespace: | | +| | nordicsemi.com | | +| | name: | | +| | nRF54H20_sample_root | | ++---------------------------------------------------------+------------------------------+------------------------------------------------+ +| Digest calculation for provided file | suit-digest-bytes: | ```` | +| | file: app.bin | | ++---------------------------------------------------------+------------------------------+------------------------------------------------+ +| Image size calculation for provided file | suit-parameter-image-size: | ```` | +| | file: app.bin | | ++---------------------------------------------------------+------------------------------+------------------------------------------------+ +| Attaching data to the envelope as an integrated payload | suit-integrated-payloads: | ```` | +| | '#application': | | +| | app.bin | | ++---------------------------------------------------------+------------------------------+------------------------------------------------+ + +For more information, see the example YAML files available in the `suit-generator repository `__. + +.. _ug_suit_using_manifest_gen: + +How to use the manifest generator +================================= + +The build system uses `suit-generator `__ to generate manifests. +**suit_generator** is a Python-powered tool that creates and parses SUIT envelopes. +If needed, the **suit-generator** can be used as a command line application, Python module, or script. + +To use **suit_generator** from the command line, run the following: + +.. code-block:: + + pip install /modules/lib/suit-generator + suit-generator --help + suit-generator create --input-file input.yaml --output-file envelope.suit + suit-generator parse --input-file envelope.suit + +To use **suit_generator** as a Python module, add the following to your Python script: + +.. code-block:: python + + from suit_generator import envelope + envelope = SuitEnvelope() + envelope.load('input.yaml') + envelope.dump('output.suit') + +To execute the Python script from the command line, run the following: + +.. code-block:: + + python /modules/lib/suit-generator/cli.py create --input-file input.yaml --output-file envelope.suit + +.. _ug_suit_edit_build_artifacts: + +Edit build artifacts +-------------------- + +To take an example of how to edit the build artifacts, we can look at the ``nrf54h_suit_sample`` :file:`/build` directory. +Among other artifacts, there are the following: + +* :file:`./build/hci_rpmsg/zephyr/hci_rpmsg_subimage.yaml` + +* :file:`./build/zephyr/app.yaml` + +* :file:`./build/zephyr/root.yaml` + +* :file:`./build/hci_rpmsg/zephyr/hci_rpmsg_subimage.suit` + +* :file:`./build/zephyr/app.suit` + +* :file:`./build/zephyr/root.suit` + +.. note:: + You must build the sample at least once to make these artifacts available. + +With these files and the **suit-generator**, you can: + +* recreate SUIT files. + +* restore YAML files from a binary SUIT envelope. + +* debug a SUIT envelope, by printing out their parsed content. + +* convert back-and-forth between different SUIT-related file types. + +Recreate SUIT files +------------------- + +To recreate SUIT files, run the following: + +.. code-block:: + + suit-generator create --input-file ./build/zephyr/root.yaml --output-file my_new_root.suit + +Restore YAML files from a binary SUIT envelope +---------------------------------------------- + +To restore a YAML file from a binary SUIT envelope, run the following: + +.. code-block:: + + suit-generator parse --input-file ./build/zephyr/root.suit --output-file my_new_root.yaml + +Debug a SUIT envelope +--------------------- + +To debug the a SUIT envelope, by printing their parsed content to the ``stdout``, run the following: + +.. code-block:: + + suit-generator parse --input-file ./build/zephyr/root.suit + +.. note:: + The previous command can be extended by parsing the dependent manifests by calling: + + .. code-block:: + + suit-generator parse --input-file ./build/zephyr/root.suit --parse-hierarchy + + +Convert between file types +-------------------------- + +All mentioned artifacts can be converted back-and-forth, remembering that calculated and resolved YAML entries like UUIDs or files will be presented as a RAW value in the form of HEX strings. + +For example, if you have an input entry like the following: + +.. code-block:: + + suit-parameter-class-identifier: + RFC4122_UUID: + namespace: nordicsemi.com + name: nRF54H20_sample_app + +This entry will be presented, after parsing, as the following: + +.. code-block:: + + suit-parameter-class-identifier: + raw: 08c1b59955e85fbc9e767bc29ce1b04d + +Reference +========= + +More information about the `suit-generator `__ can be found in the `README.md `__ file and in the **suit-generator** documentation. + +To build the **suit-generator** documentation run the following: + +.. code-block:: + + cd /modules/lib/suit-generator + pip install ./ + pip install -r doc/requirements-doc.txt + sphinx-build -b html doc/source/ doc/build/html + +.. _ug_suit_customize_manifest_quick: + +Tips +==== + +1. How to change the UUID + + Update ``RFC4122_UUID entries`` in the manifest templates + For more information see the :ref:`ug_suit_modify_class_vend_id` section of this document. + +#. How to change the location of the editable manifest templates + + Modify the :kconfig:option:`CONFIG_SUIT_ENVELOPE_EDITABLE_TEMPLATES_LOCATION` Kconfig option. + For more information see the :ref:`ug_suit_change_manifest_location` section. + +#. How to update the manifests + + Build the ``nrf54h_suit_sample`` by calling the ``west build`` command to copy the default Nordic Semiconductor manifest templates and edit editable ``.jinja2`` files stored in the directory configured using :kconfig:option:`CONFIG_SUIT_ENVELOPE_EDITABLE_TEMPLATES_LOCATION`. + For more information, see the example YAML :ref:`file ` in this document. diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_dfu.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_dfu.rst new file mode 100644 index 000000000000..11efb1dc8552 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_dfu.rst @@ -0,0 +1,29 @@ +:orphan: + +.. _ug_nrf54h20_suit_dfu: + +Device Firmware Update using SUIT +################################# + +.. contents:: + :local: + :depth: 2 + +The Software Updates for Internet of Things (SUIT) is a metadata format and procedure for performing device firmware updates (DFU). +SUIT was originally created by the `Internet Engineering Task Force `__. +Nordic Semiconductor has created an implementation of the SUIT procedure that is the newly introduced DFU procedure for the nRF54H Series of System-on-Chip (SoC) and will be the only DFU procedure compatible with the nRF54H Series. + +This SoC features a Secure Domain, which includes Secure Domain Firmware (SDFW) by default. +The Secure Domain will use the SUIT procedure to perform a DFU of the whole system. + +To use Nordic Semiconductor's implementation of the SUIT procedure, see the ``nrf54h_suit_sample`` sample. + +.. toctree:: + :maxdepth: 2 + :caption: Subpages: + + ug_nrf54h20_suit_intro + ug_nrf54h20_suit_manifest_overview.rst + ug_nrf54h20_suit_hierarchical_manifests.rst + ug_nrf54h20_suit_customize_dfu.rst + ug_nrf54h20_suit_components.rst diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_hierarchical_manifests.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_hierarchical_manifests.rst new file mode 100644 index 000000000000..ea941c7bb933 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_hierarchical_manifests.rst @@ -0,0 +1,70 @@ +:orphan: + +.. _ug_nrf54h20_suit_hierarchical_manifests: + +Hierarchical manifests +###################### + +.. contents:: + :local: + :depth: 2 + +The Software Updates for the Internet of Things (SUIT) procedure provides the option to employ a hierarchical manifest system. +In theory the SUIT SFU procedure could be executed with a single manifest however, this approach could lead to certain limitations. +Having multiple, unrelated manifest in the system raises the risk of system inconsistency. +To mitigate this risk, a specific manifest hierarchy has been introduced. + +Additionally, splitting the system into more than one part (each described by a separated manifest) allows for: + +* Assigning different signing authorities per system parts, (a single part is represented by a single SUIT manifest). + +* Assigning different access rights to certain memory locations on the device. + (Due to security reasons, the manifest representing the Radio Domain is not be able to install, alter, read-out images or memory locations assigned to the Application Domain.) + +* Possibility to assign different downgrade prevention or signing verification policies per single domain. + +Manifest topology +***************** + +Manifest are organized in a hierarchy-tree structure consisting of a single root manifest and several dependency manifests: + +.. figure:: images/nrf54h20_suit_manifest_topology.png + :alt: Hierarchical manifest topology + + Hierarchical manifest topology + +Default manifest topology for the nRF54H20 SoC +********************************************** + +The following image shows the default manifest topology for the nRF54H20 SoC: + +.. figure:: images/nrf54h20_suit_default_manifest_topology.png + :alt: Default manifest topology for the nRF54H20 SoC + + Default manifest topology for the nRF54H20 SoC + +Manifest located in the lowest positions of the hierarchy (such as the Application Local, Radio Local, System Controller, SDFW, and SDFW_Recovery manifests) contain a specific updatable image for a specific core/domain of the device. +The Nordic Top manifest coordinates update and invocation logic for its dependencies (System Controller and SDFW). +The root manifest bundles all other manifests together and coordinates the entire DFU process. + +By default, using SUIT’s hierarchical manifest involves using your own generated manifests (OEM-controlled) in combination with manifests provided by Nordic Semiconductor (particularly for the Secure Domain (SecDom) and System Controller). +An example of how this would be implemented includes: + +* OEM-controlled manifests + + * A root manifest that coordinates update and invocation processes on its dependency manifests. + It does not belong to any domain or control any local domain resources. + + * A dependency manifest for each of the domains, such as the Application and Radio Domains. + +* Nordic Semiconductor controlled manifests - for the SecDom, including the System Controller. + They will be released by Nordic Semiconductor and can be incorporated into the firmware update package prepared by the OEM. + +To perform a DFU procedure on the nRF54H20 SoC, you can use manifest templates provided by Nordic Semiconductor and the **suit-generator** to create an update package. +See the :ref:`ug_nrf54h20_suit_customize_dfu` user guide for instructions and example use cases. + +If the manifest templates provided by Nordic Semiconductor do not address your specific needs, you can modify them. +Read the :ref:`ug_suit_modify_manifest_temps` section of the :ref:`ug_nrf54h20_suit_customize_dfu` user guide for instructions. + +Alternatively, you can use the manifest generator (**suit-generator**) to create your own manifests from scratch. +See the :ref:`ug_suit_use_own_manifest` section of the :ref:`ug_nrf54h20_suit_customize_dfu` user guide for instructions. diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_intro.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_intro.rst new file mode 100644 index 000000000000..ff9371372513 --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_intro.rst @@ -0,0 +1,310 @@ +:orphan: + +.. _ug_nrf54h20_suit_intro: + +Introduction to SUIT +#################### + +.. contents:: + :local: + :depth: 2 + +This document explains why the SUIT procedure was selected, gives an overview of SUIT and its characteristics, and gives a comparison to the MCUboot DFU procedure. +See the ``nrf54h_suit_sample`` if you want to try using the SUIT procedure on the nRF54H20 SoC. + +Why SUIT was selected as a DFU procedure +**************************************** + +The nRF54H Series contains multiple CPU cores and images as opposed to other products by Nordic Semiconductor, such as the nRF52 Series. +Multiple CPU cores add more possibilities for development and complexity for operations such as performing a DFU. +This requires a DFU procedure that can address the needs of a single device containing multiple cores and multiple images. + +Therefore, the SUIT procedure was selected due to its features: + +* Script-based systems that allow you to customize the instructions for installation and invocation + +* Dependency management between multiple executable images + +* Support for multiple signing authorities that will be required for each dependency + +* Customization for the allocation of upgradeable elements + +.. note:: + + The term "invocation" is used in this document to mean "booting procedure". + + +Script-based systems +==================== + +SUIT features a script-based system. +This contains high-level instructions collected into *command sequences*. +SUIT's command sequences allow you to express certain sequences for installation and invocation in an imperative way. +This offers flexibility in cases where, for example, you want to minimize the size of a download within the DFU lifecycle to increase flash efficiency. + +This allows for extensive management of dependencies between components, meaning you can execute different logic on different groups of components. +For example, the location of a slot or component does not have to be static and can be changed within the manifest. + +The script-based system also allows you to direct the manifest to download only the necessary, specified data. +You can do this, for example, by checking what is already in the device receiving the DFU or by checking the version number of the existing firmware. +This saves on both transfer cost and memory on the device. + +SUIT topology +============= + +SUIT features a topology which allows for dependency management between multiple executable images. +Additionally, the SUIT topology allows you to provide multiple signing authorities that will be required for each dependency. + +For information on the SUIT topology used by Nordic Semiconductor's implementation of SUIT, see the :ref:`ug_nrf54h20_suit_hierarchical_manifests` page. + +Allocation of components +======================== + +SUIT itself does not decide the component allocation, rather it can be defined in the manifest. +This is because their location is flexible and there are some options available to change the location of a specific image within the manifest. + +See the :ref:`mcuboot_comparison` section for further information on why SUIT was selected for DFU procedures for the nRF54H Series of SoC. + +SUIT overview +************* + +SUIT uses a serialization format based on Concise Binary Object Representation (CBOR), and CBOR object signing and encryption (COSE) to ensure security. +The SUIT procedure features a flexible, script-based system that allows the DFU implementation to be customized, particularly for devices with multiple CPU cores. + +It also features a root manifest that contains the main instructions of the SUIT procedure, as well as local manifests for each of its required dependencies. +The SUIT manifests control the invocation procedure at the same level of detail as the update procedure. +See :ref:`ug_how_suit_manifest_works` to read more about the contents of the manifests. + +The nRF54H Series contains multiple CPUs with one dedicated CPU for the Secure Domain. +The Secure Domain CPU firmware is validated and started by the Secure Domain ROM. +When it starts execution, it continues the SoC boot sequence according to the manifest(s). +The local domain CPU firmware images are validated and started by the Secure Domain as instructed by the manifest. + +Once the invocation process is complete, the SDFW is still active and may serve specific requests from specified domains. +Therefore, unlike in MCUboot, the Application Core and other cores may use the SDFW services. +(See the :ref:`mcuboot_comparison` section for more details and further comparison of the two DFU procedures.) +The bootloader SDFW image provided by Nordic Semiconductor is offered in binary form. +Along with this, you can compose a final image with your own application image that is signed by your own keys. + +.. figure:: images/nrf54h20_suit_example_update_workflow.png + :alt: Example of the anticipated workflow for an Application Domain update using SUIT + +.. _ug_suit_dfu_suit_concepts: + +SUIT-specific concepts +********************** + +Below is a description of SUIT-specific concepts. + +Component +========= + +An updatable logical block of firmware, software, configuration, or data structure. +Components are the elements that SUIT operates on. +They are identified by the ``Component_ID`` in the manifest and are abstractions that map to memory locations on the device. +For example, a memory slot on a device that contains one firmware image is a typical example of a component, though components can be of any size. + +Command sequence +================ + +A set of commands. +Commands include both directives and conditions. +Most commands operate on components. + +Directive +--------- + +An action for the recipient device to perform. +For example, to copy code or a data payload from the source component to the specified destination. + +Condition +--------- + +A test that passes or fails for a specific property of the recipient device or its component(s). +For example, to ensure that the digest of the code or data in a specific component is equal to the expected value. + +Envelope +======== + +An outer container for the manifest that may also contain code or data payloads. +Code or data payloads are optional in the envelope because the manifest can be created so that payload fetching is encoded within the command sequences. + +The SUIT envelope includes: an authentication wrapper, the manifest, severable elements, integrated payloads, and the integrated dependencies. +Below is a description of the contents of the SUIT envelope structure that have not yet been described. + +Authentication wrapper +---------------------- + +Every SUIT envelope contains an authentication wrapper. +The wrapper contains cryptographic information that protects the manifest, and includes one or more authentication blocks. + +The authentication wrapper is important because it checks the authenticity of the manifest, but it is not involved in executing command sequences. + +.. figure:: images/nrf54h20_suit_envelope_structure.png + :alt: SUIT envelope structure + + SUIT envelope structure + +Manifest +-------- + +A bundle of metadata describing one or more pieces of code or data payloads. +This includes instructions on how to obtain those payloads, as well as how to install, verify, and invoke them. +These instructions are encoded in the manifest in the form of command sequences. +See the :ref:`ug_how_suit_manifest_works` for more details about the contents of a manifest. +Each manifest, either the root or dependency manifest, is encased in its own envelope. + +.. note:: + + The manifest is the most important concept within SUIT. + The manifest is represented in a file, as either a YAML or JSON file based on Nordic Semiconductor's implementation, that can be edited to control aspects of the DFU. + +Severable elements +------------------ + +Severable elements are elements that belong to the manifest but are held outside of the manifest. +They can later be deleted when they are no longer needed to save storage space. +To maintain integrity, a digest of the severable element is kept inside the manifest. +These are optional for SUIT envelopes. + +Integrated payloads +------------------- + +Integrated payloads are payloads that are integrated within the envelope of the manifest. +This allows for a one-step update, where everything needed for the update is in one image (the envelope). +These are optional for SUIT envelopes. + +Integrated dependencies +----------------------- + +Integrated dependencies contain the manifests needed for any required dependencies and are encased in their own SUIT envelope structure. +These are optional for SUIT envelopes and only necessary if there are dependencies needed for the DFU. + + +.. _ug_suit_dfu_suit_procedure: + +SUIT procedure +************** + +The SUIT procedure contains a SUIT envelope. +This envelope is a container to transport an update package. + +An update package contains an authentication wrapper, one root manifest within an envelope, severable elements, one or more payloads as well as integrated dependencies. +Payloads can be either: + +* Images + +* Dependency manifests (each in their own envelope) + +* Other data + +Payloads can be distributed individually or embedded in the envelope of the manifest where it is used. +This means that an update package or invocation process can be distributed in one large package or as several small packages. + +.. figure:: images/nrf54h20_suit_example_update_package.png + :alt: Example of an update package + + Example of an update package + +SUIT workflows +============== + +There are two anticipated workflows for the recipient device that is receiving the update: the update procedure and the invocation procedure. + +The update procedure contains the following steps: + +.. figure:: images/nrf54h20_suit_update_workflow.png + :alt: Update procedure workflow + + Update procedure workflow + +The invocation procedure contains the following steps: + +.. figure:: images/nrf54h20_suit_invocation_workflow.png + :alt: Invocation procedure workflow + + Invocation procedure workflow + +To follow these workflows, there are six main sequences in the SUIT procedure that belong to either the update or the invocation procedure. + +The update procedure has three sequences: + +* ``dependency-resolution`` - prepares the system for the update by identifying any missing dependency manifests. + +* ``payload-fetch`` - all non-integrated payloads are requested over the network. + +* ``install`` - the downloaded payloads are copied to their final location. + +The following is an example of `Diagnostic Notation `__ (decoded CBOR) that features the update procedure's ``payload-fetch``: + +.. code-block:: + + / payload-fetch / 16:<< [ + / directive-set-component-index / 12,1 , + / directive-override-parameters / 20,{ + / image-digest / 3:<< [ + / algorithm-id / -16 / "sha256" /, + / digest-bytes / h'0011…76543210' + + ] >>, + / uri / 21:'http://example.com/file.bin', + + } , + / directive-fetch / 21,2 , + / condition-image-match / 3,15 + ] >>, + + / install / 17:<< [ + / directive-set-component-index / 12,0 , + + / directive-override-parameters / 20,{ + / source-component / 22:1 / [h'02'] /, + + } , + / directive-copy / 22,2 , + / condition-image-match / 3,15 + ] >>, + + +The invocation procedure has three sequences, although not all of them are needed for every use case. +They are as follows: + +* ``validate`` - calculates the digest and checks that it matches the expected digest to ensure that a secure invocation process can take place. + +* ``load`` - is used in special cases when the firmware needs to be moved before invoking it. + +* ``invoke`` - hands over execution to the firmware. + +.. _mcuboot_comparison: + +MCUboot and SUIT comparison +*************************** + +The Nordic Semiconductor implementation of the SUIT procedure provides a more flexible and tailored DFU experience compared to the MCUboot procedure to better fit the needs of the SoC's multiple cores and transports. +See the diagram and comparison table below for further comparison. + +.. figure:: images/nrf54h20_suit_mcuboot_comparison.png + :alt: MCUboot and SUIT architecture comparison + + MCUboot and SUIT architecture comparison + ++----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +| Action | MCUboot characteristics | SUIT characteristics | ++======================+=======================================================================================================================================================+===========================================================================================================================================+ +| Customization | Built by users, where partitions are customized using Kconfig in the source code and becomes static. | SDFW built by Nordic Semiconductor and will be delivered in binary form. | +| | | SDFW behavior can be customized by users by using configuration data written to the IC register (xICR) and logic in the SUIT manifest(s). | ++----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +| Slot management | Follows a "symmetrical" primary and secondary slot style, where there is a secondary slot for each update candidate and a corresponding primary slot. | Contains a single DFU partition, where components act as slots and the DFU partition copies images to the designated component(s). | +| | The DFU is copied and swapped between the slots accordingly: | Additionally: | +| | | | +| | * Primary slot is where the system is executed from. | * The DFU partition size can be located anywhere in the non-volatile memory, accessible in the application core | +| | * Secondary slot is the destination for the DFU. | * Information about location of the DFU is thus not hardcoded in the SDFW and can be changed between updates in the system | +| | | * The DFU partition is where the update candidate is stored for the purpose of a system update | ++----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +| Slot characteristics | Has the same amount and size of primary and secondary slots (a one-to-one match). | Has a single DFU partition and multiple components where their sizes can be customized. | +| | This leads to high non-volatile memory overhead due to the secondary slots. | This allows for non-volatile memory overhead to be minimized (especially for multi-component devices, such as IP-connected devices). | ++----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +| Slot definition | Definition of slots (their location and size) is statically compiled into MCUboot, making it difficult to change for devices deployed to the field. | There is a technical possibility to change the definition of components (the location and size) between each update. | ++----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +| Invocation process | Behavior of the invocation process instrumentation abilities are limited through the image's metadata. | Behavior of the invocation process can be relatively deeply instrumented within the manifest. | ++----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_manifest_overview.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_manifest_overview.rst new file mode 100644 index 000000000000..e9e3fa98cc9d --- /dev/null +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_manifest_overview.rst @@ -0,0 +1,191 @@ +:orphan: + +.. _ug_nrf54h20_suit_manifest_overview: + +SUIT manifest overview +###################### + +The SUIT DFU procedure features manifests, which are encased in a SUIT envelope. +The SUIT manifest contains components, which is the main element that the SUIT DFU procedure operates on. + +Out-of-the-box, Nordic Semiconductor's implementation of SUIT features a standard hierarchical manifest topology. +This includes the following: + +* A root manifest that contains the main execution instructions for the DFU within the different Domains. + +* Two local manifests, one for the Application Domain, another for the Radio Domain. + +* Manifests for the SecDom, which are controlled by Nordic Semiconductor and cannot be modified. + This includes a Nordic "Top" manifest, one specifically for the SecDom firmware (SDFW), and the System Controller. + +You can read more about manifest topology in the :ref:`ug_nrf54h20_suit_hierarchical_manifests` page. + +Manifest templates are provided by Nordic Semiconductor, and automatically generated when you build the ``nrf54h_suit_sample`` sample. +These templates work out-of-the-box for development and testing purposes. + +This document describes the contents of a SUIT manifest. +If you want to modify elements of the manifest template, see the :ref:`ug_nrf54h20_suit_customize_dfu` user guide. + +.. _ug_how_suit_manifest_works: + +How ``SUIT_Manifest`` works +*************************** + +The ``SUIT_Manifest``, found within root and local manifests, contains several sequences. +These sequences are data structures that can contain directives and conditions. + +.. _ug_suit_dfu_suit_manifest_elements: + +Manifest elements +================= + +``SUIT_Manifest`` contains contains metadata elements and command sequences (a kind of "scripts") within its structure. +These scripts contain the commands that will be executed at certain stages of the update process. +Additionally, they provide a shortcut when a component's information, or other data, needs to be repeated throughout the manifest. + +.. caution:: + + Sequences will be provided within the SUIT manifest templates for typical use cases. + These sequences can be customized, but with caution. + This is only recommended for advanced use cases. + +The SUIT manifest contains the following elements: + +``suit-manifest-version`` +------------------------- + +Checks and compares the version number of the manifest format, or, in other words, the serialization format. +If the SUIT processor receives a manifest and sees a version number it does not recognize, it will fail due to incompatibility. + +``suit-manifest-sequence-number`` +--------------------------------- + +This is a SUIT-specific version number of the software that is contained in this manifest. +It is compared against the existing sequence number to verify that the update is newer than the current software. +The sequence number does not have to match the official version number of the software, it only needs to increase for each update. + +.. _ug_suit_dfu_suit_common: + +``suit-common`` +--------------- + +This element contains two subsections: + +* ``suit-components`` - a data field that contains all declared components to be targeted in the manifest. + + Components are identified by ``SUIT_Component_Identifier``, which is introduced by Nordic Semiconductor's implementation of the SUIT procedure. + For a list of available components, see the :ref:`ug_nrf54h20_suit_components` page. + +* ``suit-shared-sequence`` - a sequence that executes before the other sequences. + + It supports only a few directives and conditions. + + For example, when performing a DFU, the SUIT processor may be instructed to run ``suit-payload-fetch``, but first ``suit-shared-sequence`` runs before each sequence to save memory space. + This is done by declaring items, such as the vendor ID, in ``suit-shared-sequence`` once rather than declaring them separately for each update or invocation procedure. + +.. _ug_suit_dfu_suit_concepts_sequences: + +Sequences +--------- + +SUIT manifest contains the following command sequences: + +* ``suit-payload-fetch`` - obtains the needed payloads. + +* ``suit-install`` - installs payloads. + + Typical actions may include: verifying a payload stored in temporary storage, coping a staged payload from temporary storage, and unpacking a payload. + +* ``suit-validate`` - validates that the state of the device is correct and okay for booting. + + Typically involves image validation. + +* ``suit-load`` - prepares payload(s) for execution. + + A typical action of this sequence is to copy an image from the permanent storage into the RAM. + +* ``suit-invoke`` - invokes (boots) image(s). + +* ``suit-dependency-resolution`` - prepares the system for the update by identifying and fetching any missing dependency manifests. + +.. _ug_suit_dfu_suit_directives: + +Directives +========== + +The SUIT procedure defines the following directives: + +* ``set-component-index`` - defines the component(s) to which successive directives and conditions will apply. + +* ``override-parameters`` - allows the manifest to configure the behavior of future directives or conditions by changing (as in, setting or modifying) parameters that are read by those directives or conditions. + +* ``fetch`` - retrieves the payload from a specified Uniform Resource Identifier (URI) and stores it in the destination component. + A URI is provided in the ``override-parameters`` directive. + The URI may indicate an external source, for example, HTTP or FTP, or the envelope (as a fragment-only reference as defined in `RFC3986 `__, such as ``"#app_image.bin"``). + +* ``copy`` - transfers the image from the source component to the destination component. + The source component is provided in the ``override-parameters`` directive. + +* ``write`` - works similarly to ``copy``, except that the source image is embedded in the manifest. + This directive is best for small blocks of data due to manifest size limitations. + +* ``invoke`` - starts the firmware. (In other words, "boots" the firmware.) + +* ``try-each`` - runs multiple ``SUIT_Command_Sequence`` instances, trying each one in succession. + It stops when one succeeds or continues to the next if one fails, making it valuable for handling alternative scenarios. + +* ``run-sequence`` - runs a single ``SUIT_Command_Sequence``. + +.. _ug_suit_dfu_suit_conditions: + +Conditions +========== + +The SUIT procedure defines the following conditions: + +* ``class-identifier``, ``vendor-identifier``, and ``device-identifier`` - these conditions make sure that the manifest procedure is working with the correct device. + The correct UUIDs (16 bytes) must be given. + + .. note:: + + Although not required, it is strongly recommended to change the values for ``class-identifier`` and ``vendor-identifier`` in the provided manifest templates. + Read the :ref:`ug_suit_modify_class_vend_id` section of the :ref:`ug_nrf54h20_suit_customize_dfu` user guide for instructions. + +* ``image-match`` - checks the digest of an image. + The expected digest and corresponding component are set here. + It goes into the component and calculates the digest of the component, then checks it against the expected digest. + +* ``component-slot`` - checks which component slot is currently active, if a component consists of multiple slots. + Slots are alternative locations for a component, where only one is considered "active" at one time. + + It also checks which component, or memory location, is unoccupied so you can download the new image to the unoccupied slot. + After reboot, the unoccupied component now has the new image, and the active image is not overridden. + This follows an A/B slot system. + +* ``check-content`` - a special case of image matching that matches directly with expected data, not a digest. + For use with small components where the overhead of digest checking is not wanted. Typically used when you want the manifest to check something other than the firmware. + + As opposed to ``image-match``, the specified component is checked against binary data that is embedded in the manifest with what is already installed in another component. + +* ``abort`` - if you want the procedure to fail. + +A sample description of ``SUIT_Manifest`` in CDDL is shown below. +Note that optional elements are preceded by a ``?``. +For more information about CDDL's syntax, see the IETF's `RFC 8610 `__. + +.. code:: + + SUIT_Manifest = { + suit-manifest-version => 1, + suit-manifest-sequence-number => uint, + suit-common => bstr .cbor SUIT_Common, + + ? suit-validate => bstr .cbor SUIT_Command_Sequence, + ? suit-load => bstr .cbor SUIT_Command_Sequence, + ? suit-invoke => bstr .cbor SUIT_Command_Sequence, + ? suit-payload-fetch => bstr .cbor SUIT_Command_Sequence, + ? suit-install => bstr .cbor SUIT_Command_Sequence, + ? suit-text => bstr .cbor SUIT_Text_Map + + * $$SUIT_Manifest_Extensions, + } diff --git a/doc/nrf/links.txt b/doc/nrf/links.txt index 79b3a93c8ffd..6ecffae065a9 100644 --- a/doc/nrf/links.txt +++ b/doc/nrf/links.txt @@ -1376,3 +1376,58 @@ .. _`nRF Connect Board Configurator`: https://docs.nordicsemi.com/bundle/nrf-connect-board-configurator/page/index.html .. _`HTTPie`: https://httpie.io/ + +.. ### Temp: nRF54H and nRF54L related links, repositories, and documents + +.. _`nrf-regtool`: https://github.com/nrfconnect/nrf-regtool/ +.. _`UICR overlay`: https://github.com/nrfconnect/sdk-nrf-next/tree/haltium-ncs/applications/machine_learning/configuration/nrf54h20dk_nrf54h20_cpuapp%40soc1/uicr +.. _`nRF54H20 common SoC files`: https://github.com/nrfconnect/sdk-ic-next/tree/haltium/soc +.. _`ARM cores configuration files`: https://github.com/nrfconnect/sdk-ic-next/tree/haltium/boards/arm/nrf54h20dk_nrf54h20 +.. _`Risc-V cores configuration files`: https://github.com/nrfconnect/sdk-ic-next/tree/haltium/boards/riscv/nrf54h20dk_nrf54h20 +.. _`nRF54H20 Objective Product Specification 0.3`: https://res.developer.nordicsemi.com/res/nrf54H20/OPS/nRF54H20_OPS_v0.3.pdf +.. _`nRF54H20 Objective Product Specification 0.3.1`: https://res.developer.nordicsemi.com/res/nrf54H20/OPS/nRF54H20_OPS_v0.3.1.pdf + +.. _`Introduction to nRF54H20`: https://res.developer.nordicsemi.com/res/nrf54H20/intro/Introduction%20to%20nRF54H20%20v1_0_1.pdf +.. _`nRF54H20 prototype difference`: https://res.developer.nordicsemi.com/res/nrf54H20/other/nRF54H20_proto_diff.pdf + +.. _`nRF54L15 PDK schematic and PCB 0.2`: https://res.developer.nordicsemi.com/res/nRF54L15/schematics/pca10156_schematic_and_pcb.pdf +.. _`nRF54L15 PDK schematic and PCB 0.2.1`: https://res.developer.nordicsemi.com/res/nRF54L15/schematics/pca10156_schematic_and_pcb_0.2.1_2023_09_28.pdf + +.. _`nRF54L15 Objective Product Specification 0.5b`: https://res.developer.nordicsemi.com/res/nRF54L15/OPS/nRF54L15_OPS_v0.5b_Confidential.pdf +.. _`nRF54L15 prototype difference`: https://res.developer.nordicsemi.com/res/nRF54L15/protodiff/nRF54L15_prototype_differences_v1.0_nwp_051.pdf + +.. _`BICR register's PDF file`: https://res.developer.nordicsemi.com/res/nrf54H20/BICR/nRF54H20_BICR_0_11_0.pdf +.. _`nRF Command Line Tools 10.22.1`: https://www.nordicsemi.com/Products/Development-tools/nrf-command-line-tools/download + +.. _`documentation page on Github Authentication`: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-authentication-to-github +.. _`documentation page on authentication methods`: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-authentication-to-github +.. _`ssh-agent`: https://www.ssh.com/ssh/agent +.. _`Connecting to GitHub with SSH`: https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh +.. _`SSH-based authentication`: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent +.. _`git-credential-store`: https://git-scm.com/docs/git-credential-store#_examples +.. _`git-credential-cache`: https://git-scm.com/docs/git-credential-cache +.. _`personal access token`: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token +.. _`Git Credential Manager`: https://github.com/git-ecosystem/git-credential-manager +.. _`Personal Access Token (PAT)`: https://github.com/settings/tokens +.. _`Homebrew`: https://brew.sh/ +.. _`sdk-find-my-next repository`: https://github.com/nrfconnect/sdk-find-my-next + +.. _`Serial Terminal from nRF Connect for Desktop`: https://infocenter.nordicsemi.com/topic/ug_serial_terminal/UG/serial_terminal/intro.html + +.. _`10.23.3_ec 64-bit Windows, executable`: https://res.developer.nordicsemi.com/res/nrf-command-line-tools-10.23.3/nRF-Command-Line-Tools-10.23.3-x64.exe + +.. _`10.23.3_ec x86 system, deb format`: https://res.developer.nordicsemi.com/res/nrf-command-line-tools-10.23.3/nrf-command-line-tools_10.23.3_amd64.deb +.. _`10.23.3_ec x86 system, RPM`: https://res.developer.nordicsemi.com/res/nrf-command-line-tools-10.23.3/nrf-command-line-tools-10.23.3-1.x86_64.rpm +.. _`10.23.3_ec x86 system, tar archive`: https://res.developer.nordicsemi.com/res/nrf-command-line-tools-10.23.3/nrf-command-line-tools-10.23.3_Linux-amd64.tar.gz + +.. _`10.23.3_ec ARM64 system, deb format`: https://res.developer.nordicsemi.com/res/nrf-command-line-tools-10.23.3/nrf-command-line-tools_10.23.3_arm64.deb +.. _`10.23.3_ec ARM64 system, RPM`: https://res.developer.nordicsemi.com/res/nrf-command-line-tools-10.23.3/nrf-command-line-tools-10.23.3-1.arm64.rpm +.. _`10.23.3_ec ARM64 system, tar archive`: https://res.developer.nordicsemi.com/res/nrf-command-line-tools-10.23.3/nrf-command-line-tools-10.23.3_Linux-arm64.tar.gz + +.. _`10.23.3_ec ARMHF system, zip archive`: https://res.developer.nordicsemi.com/res/nrf-command-line-tools-10.23.3/nrf-command-line-tools-10.23.3-armhf-linux.zip + +.. _`10.23.3_ec macOS, zip archive`: https://res.developer.nordicsemi.com/res/nrf-command-line-tools-10.23.3/nrf-command-line-tools-10.23.3-osx.zip + +.. _`nRF Sniffer for Bluetooth LE`: https://infocenter.nordicsemi.com/index.jsp?topic=%2Fug_sniffer_ble%2FUG%2Fsniffer_ble%2Fintro.html +.. _`Git for Windows`: https://git-scm.com/download/win +.. _`nRF Terminal documentation`: https://nrfconnect.github.io/vscode-nrf-connect/terminal/nrfterminal.html