doc: Add SUIT IPUC documentation

Add extensive documentation for the SUIT In-Place Update Components.

Ref: NCSDK-32516

Signed-off-by: Tomasz Chyrowicz <[email protected]>

Author: tomchy

CODEOWNERS

@@ -98,6 +98,8 @@
 /doc/nrf/drivers/bme68x_iaq.rst           @nrfconnect/ncs-cia-doc
 /doc/nrf/drivers/entropy_cc3xx.rst        @nrfconnect/ncs-aegir-doc
 /doc/nrf/drivers/eth_rtt.rst              @nrfconnect/ncs-si-muffin-doc
+/doc/nrf/drivers/suit_flash_ipuc.rst      @nrfconnect/ncs-charon-doc
+/doc/nrf/drivers/images/flash_ipuc/*      @nrfconnect/ncs-charon-doc
 /doc/nrf/drivers/hw_cc3xx.rst             @nrfconnect/ncs-aegir-doc
 /doc/nrf/drivers/paw3212.rst              @nrfconnect/ncs-si-bluebagel-doc
 /doc/nrf/drivers/pmw3360.rst              @nrfconnect/ncs-si-bluebagel-doc

doc/nrf/app_dev/device_guides/nrf54h/images/suit_ipuc/ipuc_fetch_cache_preinit.png

@@ -0,0 +1,29 @@
+@startuml
+autonumber
+participant suit_dfu_cache
+participant memory_layout
+participant flash_ipuc
+
+--> suit_dfu_cache ++ : preinitialize()
+suit_dfu_cache -> memory_layout ++ : suit_memory_sdfw_update_area_info_get(&min_address, &size)
+deactivate memory_layout
+
+suit_dfu_cache -> flash_ipuc ++ : flash_cache_ipuc_create(min_address)
+flash_ipuc -> flash_sdfw_cache_ipuc_dev ** : get_free_dev()
+flash_ipuc -> flash_ipuc ++ : read_access_check(ipuc[i].role)
+deactivate flash_ipuc
+deactivate flash_ipuc
+
+suit_dfu_cache -> flash_ipuc ++ : flash_cache_ipuc_create(min_address)
+flash_ipuc -> flash_app_cache_ipuc_dev ** : get_free_dev()
+flash_ipuc -> flash_ipuc ++ : read_access_check(ipuc[i].role)
+deactivate flash_ipuc
+deactivate flash_ipuc
+
+deactivate suit_dfu_cache
+
+rnote over flash_ipuc
+  Cache IPUCs are never released.
+end note
+
+@enduml

doc/nrf/app_dev/device_guides/nrf54h/images/suit_ipuc/ipuc_fetch_cache_preinit.txt

@@ -0,0 +1,82 @@
+@startuml
+autonumber
+participant suit_plat_fetch
+participant suit_fetch_app_specific
+' participant suit_utils
+
+participant suit_fetch_source_mgr
+participant suit_flash_sink
+participant suit_flash_sink_entry
+participant memory_layout
+participant flash_ipuc
+
+--> suit_plat_fetch ++ : suit_plat_fetch(\n    handle,\n    uri,\n    mfst_id,\n    enc_info\n)
+
+' suit_plat_fetch -> suit_fetch_app_specific : suit_plat_fetch_domain_specific_is_type_supported(type)
+suit_plat_fetch -> suit_fetch_app_specific ++ : suit_plat_fetch_domain_specific(\n    handle,\n    type,\n    uri,\n    mfst_id,\n    enc_info\n)
+
+opt SUIT_COMPONENT_TYPE_MEM
+
+' suit_fetch_app_specific -> suit_utils : suit_plat_component_id_get(handle)
+' suit_fetch_app_specific -> suit_utils : suit_plat_decode_address_size(component_id)
+suit_fetch_app_specific -> flash_ipuc ++ : flash_component_ipuc_check(component_id)
+deactivate flash_ipuc
+
+suit_fetch_app_specific -> flash_ipuc ++ : flash_component_ipuc_create(mfst_id, enc_info, comp_info)
+flash_ipuc -> flash_ipuc_dev ** : get_free_dev()
+deactivate flash_ipuc
+
+suit_fetch_app_specific -> suit_flash_sink ++ : suit_flash_sink_is_address_supported(address)
+suit_flash_sink -> memory_layout ++ : suit_memory_global_address_is_in_nvm(address)
+memory_layout -> flash_ipuc ++ : flash_ipuc_find(address, 0)
+note right
+  Returns the newly created IPUC device.
+end note
+deactivate flash_ipuc
+deactivate memory_layout
+deactivate suit_flash_sink
+
+suit_fetch_app_specific -> suit_flash_sink ++ : suit_flash_sink_get(address, size)
+
+suit_flash_sink -> suit_flash_sink_entry ** : new_ctx_get()
+suit_flash_sink -> memory_layout ++ : suit_memory_global_address_to_nvm_address(address, size)
+memory_layout -> flash_ipuc ++ : flash_ipuc_find(address, size)
+deactivate flash_ipuc
+deactivate memory_layout
+
+suit_flash_sink -> memory_layout ++ : suit_memory_global_address_range_is_in_nvm(address, size)
+memory_layout -> flash_ipuc ++ : flash_ipuc_find(address, size)
+deactivate flash_ipuc
+deactivate memory_layout
+deactivate suit_flash_sink
+
+suit_fetch_app_specific -> suit_fetch_source_mgr ++ : suit_fetch_source_stream(uri, flash_sink)
+suit_fetch_source_mgr -> suit_flash_sink_entry ++ : write(buf, size)
+note right
+  Flash IPUC driver uses single-byte read block size
+  to avoid memory readback in unaligned write requests.
+end note
+suit_flash_sink_entry -> flash_ipuc_dev ++ : write(offset, buf, size)
+deactivate flash_ipuc_dev
+deactivate suit_flash_sink_entry
+deactivate suit_fetch_source_mgr
+
+suit_fetch_app_specific -> suit_flash_sink_entry ++ : flush()
+suit_flash_sink_entry -> flash_ipuc_dev ++ : write(offset, NULL, 0)
+deactivate flash_ipuc_dev
+deactivate suit_flash_sink_entry
+
+suit_fetch_app_specific -> suit_flash_sink_entry : release()
+destroy suit_flash_sink_entry
+
+suit_fetch_app_specific -> flash_ipuc ++ : flash_ipuc_release()
+flash_ipuc -> flash_ipuc_dev ++ : release()
+destroy flash_ipuc_dev
+deactivate flash_ipuc
+
+end
+
+deactivate suit_fetch_app_specific
+deactivate suit_plat_fetch
+
+@enduml

doc/nrf/app_dev/device_guides/nrf54h/images/suit_ipuc/ipuc_fetch_mem.png

@@ -0,0 +1,22 @@
+@startuml
+autonumber
+participant suitfu
+participant suit_dfu_cache
+participant flash_cache_ipuc_dev
+
+--> suitfu ++ : suitfu_mgmt_suit_cache_raw_upload(id)
+suitfu -> suit_dfu_cache ++ : suit_dfu_cache_rw_device_info_get(id)
+deactivate suit_dfu_cache
+
+suitfu -> flash_cache_ipuc_dev ++ : erase(ipuc_dev, size)
+deactivate flash_cache_ipuc_dev
+suitfu -> flash_cache_ipuc_dev ++ : write(ipuc_dev, offset, size)
+deactivate flash_cache_ipuc_dev
+
+deactivate suitfu
+
+rnote over flash_cache_ipuc_dev
+  Cache IPUCs are never released.
+end note
+
+@enduml

doc/nrf/app_dev/device_guides/nrf54h/images/suit_ipuc/ipuc_fetch_mem.txt

@@ -0,0 +1,33 @@
+@startuml
+autonumber
+participant suitfu
+participant suit_dfu_cache
+participant flash_ipuc
+participant flash_ipuc_dev
+
+--> suitfu ++ : suitfu_mgmt_suit_cache_raw_upload(id)
+suitfu -> flash_ipuc ++ : flash_image_ipuc_create(id)
+flash_ipuc -> flash_ipuc_dev ** : get_free_dev()
+flash_ipuc -> devicetree ++ : << find dfu_target_id >>
+deactivate devicetree
+deactivate flash_ipuc
+
+suitfu -> flash_ipuc_dev ++ : erase(ipuc_dev, size)
+deactivate flash_ipuc_dev
+
+suitfu -> flash_ipuc_dev ++ : write(ipuc_dev, offset, size)
+deactivate flash_ipuc_dev
+
+suitfu -> flash_ipuc ++ : flash_image_ipuc_release(ipuc_dev)
+
+flash_ipuc -> flash_ipuc_dev ++ : write(ipuc_dev, 0, 0)
+deactivate flash_ipuc_dev
+
+flash_ipuc -> flash_ipuc_dev : release()
+destroy flash_ipuc_dev
+deactivate flash_ipuc
+
+deactivate suitfu
+
+
+@enduml

doc/nrf/app_dev/device_guides/nrf54h/images/suit_ipuc/ipuc_push_raw_cache.png

@@ -37,3 +37,4 @@ For a list of available SUIT samples, see the :ref:`suit_samples` page.
    ug_nrf54h20_suit_soc_binaries
    ug_nrf54h20_suit_recovery
    ug_nrf54h20_suit_sdfw_sdrfw_update
+   ug_nrf54h20_suit_ipuc