doc/app_dev_dfu: doc on entering the firmware mode

Documented mechanism-es for entering the firmware loader mode

Signed-off-by: Andrzej Puzdrowski <[email protected]>

Author: nvlsianpu

doc/nrf-bm/app_dev/dfu/entering_dfu.rst

@@ -0,0 +1,36 @@
+.. _entering_dfu_single_bank:
+
+Entering Single-Bank Device Firmware Update (DFU) mode
+######################################################
+
+|BMlong| supports a single-bank DFU mechanism. The device normally executes the application which can't update itself nor firmware elements it's depends on.
+This mean that the device running the application must be switched to the DFU mode so it will run the firmware loader.
+The firmware loader is the physically separated firmware entity, which provides services for supporting the firmware download to the single Bank.
+Decision on entering the firmware loader is made by the MCUboot.
+The available entering schemes are listed bellow:
+
+Entering on GPIO state
+**********************
+
+Firmware loader will be entered when the active state of a GPIO pin will be asserted during early device startup.
+The SoC must be rebooted, for instance by the board power toggling for performing this action.
+Use the :kconfig:option:`SB_CONFIG_BM_BOOTLOADER_MCUBOOT_FIRMWARE_LOADER_ENTRANCE_GPIO` sysbuild Kconfig option to use this mode.
+The GPIO PIN is configured by the definition of `BOARD_PIN_BTN_0` of the board in its :file:`include/board-config.h` file.
+
+Entering on reset by PIN
+************************
+
+Firmware loader will be entered when the SoC reset will be triggered by the reset pin.
+Use the :kconfig:option:`SB_CONFIG_BM_BOOTLOADER_MCUBOOT_FIRMWARE_LOADER_ENTRANCE_PIN_RESET` sysbuild Kconfig option to use this mode.
+
+Buttonless entering
+*******************
+
+Firmware loader will be entered when the MCUboot detects such request delivered to the retained memory area by the application.
+The application must triggered the SoC reset for making MCUboot to performing this action.
+Use boot mode API: :c:func:`bootmode_set` and :c:enum:`BOOT_MODE_TYPE_BOOTLOADER` to set the retention boot mode value.
+Use the :kconfig:option:`SB_CONFIG_BM_BOOTLOADER_MCUBOOT_FIRMWARE_LOADER_ENTRANCE_BOOT_MODE` sysbuild Kconfig option to use this mode.
+
+The SoC's GPREGRET1 register is used as the retained memory area for that purpose. The board DTS must describe this register and it assignment to the :devicetree:`chosen/zephyr,boot-mode` chosen property.
+
+This mode is integrated with the MCUmgr OS reset command when the :kconfig:option:`CONFIG_MCUMGR_GRP_OS_RESET_BOOT_MODE` Kconfig option is enabled.

doc/nrf-bm/app_dev/dfu/index.rst

@@ -14,3 +14,4 @@ This chapter provides an overview of the Device Firmware Update (DFU) capabiliti
    bootloader_keys
    ug_dfu
    dfu_name
+   entering_dfu