samples: dfu: Extend A/B sample documentation

This commit extends the A/B sample documentation with
more in-depth description of the A/B feature.

Signed-off-by: Artur Hadasz <[email protected]>

Author: ahasztag

samples/dfu/ab/README.rst

@@ -42,6 +42,67 @@ The sample supports the following MCUmgr transports by default:
 * Bluetooth
 * Serial (UART)
 
+A/B functionality
+=================
+
+When the A/B functionality is used, the device has two slots for the application: slot A and slot B.
+The slots are equivalent, and the device can boot from either of them.
+In case of MCUBoot this is achieved by using the Direct XIP feature.
+Thus, note that the terms slot 0/primary slot/slot A and slot 1/secondary slot/slot B are used interchangeably in the documentation.
+This configuration allows for performing a background update of the non-active slot while the application runs from the active slot.
+After the update is complete, the device can quickly switch to the updated slot on the next reboot.
+
+The following conditions decide which slot will be booted (active) on the next reboot:
+
+1. If one of the slots is not valid the other slot is selected as active.
+2. If both slots are valid, the slot marked as "preferred" is selected as active.
+3. If both slots are valid and none is marked as "preferred", the slot with the higher version number is selected as active.
+4. If none of the above conditions is met, slot A is selected as active.
+
+Setting the preffered slot can be done using the ``boot_request_set_preferred_slot`` function.
+Currently, this only allows for setting the boot preference for a single reboot.
+
+Getting the currently running slot
+----------------------------------
+
+If the project uses the Partition Manager, the currently running slot can be identified by checking if ``CONFIG_NCS_IS_VARIANT_IMAGE`` is defined.
+If it is, the application is running from slot B.
+Otherwise, it is running from slot A.
+
+If the project does not use the Partition Manager (configuration currently only supported on nRF54H20), the currently running slot can be identified by comparing the address pointed `zephyr,code-partition` to specific node addresses defined in the device tree.
+The following node partitions are used by default:
+
+* ``slot0_partition`` - application core slot A
+* ``slot1_partition`` - application core slot B
+* ``cpurad_slot0_partition`` - radio core slot A
+* ``cpurad_slot1_partition`` - radio core slot B
+
+For example, verifying that the application is running from slot A can be done by using the following macro:
+
+.. code-block:: c
+
+    #define IS_RUNNING_FROM_SLOT_A \
+        (FIXED_PARTITION_NODE_OFFSET(DT_CHOSEN(zephyr_code_partition)) == \
+         FIXED_PARTITION_OFFSET(slot0_partition))
+
+.. _ab_build_files:
+
+Build files
+-----------
+
+If building with nRF54H20, the merge slot feature is used when Direct XIP is enabled.
+This means that for both slot A and slot B the application image and the radio image are merged and treated as a single image by MCUboot.
+In this case the following files should be sent to the device when performing an update:
+
+* :file:`build/zephyr/zephyr_secondary_app.merged.bin` contains slot B image, should be uploaded to the secondary slot when running from slot A.
+* :file:`build/zephyr/zephyr.merged.bin` contains slot A image, should be uploaded to the primary slot when running from slot B.
+
+If building on other supported platforms, where there is no separate radio core, only the application core is updated.
+In this case the mcuboot files for the application image are used:
+
+* :file:`build/mcuboot_secondary_app/zephyr/zephyr.signed.bin` contains slot B image, should be uploaded to the secondary slot when running from slot A.
+* :file:`build/ab/zephyr/zephyr.signed.bin` contains slot A image, should be uploaded to the primary slot when running from slot B.
+
 User interface
 **************
 
@@ -106,6 +167,9 @@ To perform DFU using the `nRF Connect Device Manager`_ mobile app, complete the
    :start-after: fota_upgrades_over_ble_nrfcdm_common_dfu_steps_start
    :end-before: fota_upgrades_over_ble_nrfcdm_common_dfu_steps_end
 
+Instead of using the ``dfu_application.zip`` file, you can also send the appropriate binary file directly as described in :ref:`ab_build_files`.
+Make sure to select the correct file based on the currently running slot.
+
 Dependencies
 ************