1.. _dfu:
2
3Device Firmware Upgrade
4#######################
5
6Overview
7********
8
9The Device Firmware Upgrade subsystem provides the necessary frameworks to
10upgrade the image of a Zephyr-based application at run time. It currently
11consists of two different modules:
12
13* :zephyr_file:`subsys/dfu/boot/`: Interface code to bootloaders
14* :zephyr_file:`subsys/dfu/img_util/`: Image management code
15
16The DFU subsystem deals with image management, but not with the transport
17or management protocols themselves required to send the image to the target
18device. For information on these protocols and frameworks please refer to the
19:ref:`device_mgmt` section.
20
21.. _flash_img_api:
22
23Flash Image
24===========
25
26The flash image API as part of the Device Firmware Upgrade (DFU) subsystem
27provides an abstraction on top of Flash Stream to simplify writing firmware
28image chunks to flash.
29
30API Reference
31-------------
32
33.. doxygengroup:: flash_img_api
34
35.. _mcuboot_api:
36
37MCUBoot API
38===========
39
40The MCUboot API is provided to get version information and boot status of
41application images. It allows to select application image and boot type
42for the next boot.
43
44API Reference
45-------------
46
47.. doxygengroup:: mcuboot_api
48
49Bootloaders
50***********
51
52.. _mcuboot:
53
54MCUboot
55=======
56
57Zephyr is directly compatible with the open source, cross-RTOS
58`MCUboot boot loader`_. It interfaces with MCUboot and is aware of the image
59format required by it, so that Device Firmware Upgrade is available when MCUboot
60is the boot loader used with Zephyr. The source code itself is hosted in the
61`MCUboot GitHub Project`_ page.
62
63In order to use MCUboot with Zephyr you need to take the following into account:
64
651. You will need to define the flash partitions required by MCUboot; see
66   :ref:`flash_map_api` for details.
672. You will have to specify your flash partition as the chosen code partition
68
69.. code-block:: devicetree
70
71   / {
72      chosen {
73         zephyr,code-partition = &slot0_partition;
74      };
75   };
76
773. Your application's :file:`.conf` file needs to enable the
78   :kconfig:option:`CONFIG_BOOTLOADER_MCUBOOT` Kconfig option in order for Zephyr to
79   be built in an MCUboot-compatible manner
804. You need to build and flash MCUboot itself on your device
815. You might need to take precautions to avoid mass erasing the flash and also
82   to flash the Zephyr application image at the correct offset (right after the
83   bootloader)
84
85More detailed information regarding the use of MCUboot with Zephyr  can be found
86in the `MCUboot with Zephyr`_ documentation page on the MCUboot website.
87
88.. _MCUboot boot loader: https://mcuboot.com/
89.. _MCUboot with Zephyr: https://docs.mcuboot.com/readme-zephyr
90.. _MCUboot GitHub Project: https://github.com/runtimeco/mcuboot
91