1.. _blinfo_api:
2
3Bootloader Information
4######################
5
6The bootloader information (abbreviated to blinfo) subsystem is an extension of
7the :ref:`retention_api` which allows for reading shared data from a bootloader
8and allowing applications to query it. It has an optional feature of organising
9the information retrieved from the bootloader and storing it in the
10:ref:`settings_api` with the ``blinfo/`` prefix.
11
12Devicetree setup
13****************
14
15To use the bootloader information subsystem, a retention area needs to be
16created which has a retained data section as its parent, generally non-init RAM
17is used for this purpose. See the following example (examples in this guide are
18based on the :ref:`nrf52840dk_nrf52840` board and memory layout):
19
20.. code-block:: devicetree
21
22	/ {
23		sram@2003FC00 {
24			compatible = "zephyr,memory-region", "mmio-sram";
25			reg = <0x2003FC00 DT_SIZE_K(1)>;
26			zephyr,memory-region = "RetainedMem";
27			status = "okay";
28
29			retainedmem {
30				compatible = "zephyr,retained-ram";
31				status = "okay";
32				#address-cells = <1>;
33				#size-cells = <1>;
34
35				boot_info0: boot_info@0 {
36					compatible = "zephyr,retention";
37					status = "okay";
38					reg = <0x0 0x100>;
39				};
40			};
41		};
42
43		chosen {
44			zephyr,bootloader-info = &boot_info0;
45		};
46	};
47
48
49	/* Reduce SRAM0 usage by 1KB to account for non-init area */
50	&sram0 {
51		reg = <0x20000000 DT_SIZE_K(255)>;
52	};
53
54Note that this configuration needs to be applied on both the bootloader
55(MCUboot) and application to be usable. It can be combined with other retention
56system APIs such as the :ref:`boot_mode_api`
57
58MCUboot setup
59*************
60
61Once the above devicetree configuration is applied, MCUboot needs to be
62configured to store the shared data in this area, the following Kconfigs need
63to be set for this:
64
65* :kconfig:option:`CONFIG_RETAINED_MEM` - Enables retained memory driver
66* :kconfig:option:`CONFIG_RETENTION` - Enables retention system
67* :kconfig:option:`CONFIG_BOOT_SHARE_DATA` - Enables shared data
68* :kconfig:option:`CONFIG_BOOT_SHARE_DATA_BOOTINFO` - Enables boot information
69  shared data type
70* :kconfig:option:`CONFIG_BOOT_SHARE_BACKEND_RETENTION` - Stores shared data
71  using retention/blinfo subsystem
72
73Application setup
74*****************
75
76The application must enable the following base Kconfig options for the
77bootloader information subsystem to function:
78
79* :kconfig:option:`CONFIG_RETAINED_MEM`
80* :kconfig:option:`CONFIG_RETENTION`
81* :kconfig:option:`CONFIG_RETENTION_BOOTLOADER_INFO`
82* :kconfig:option:`CONFIG_RETENTION_BOOTLOADER_INFO_TYPE_MCUBOOT`
83
84The following include is needed to use the bootloader information subsystem:
85
86.. code-block:: C
87
88	#include <zephyr/retention/blinfo.h>
89
90By default, only the lookup function is provided: :c:func:`blinfo_lookup`, the
91application can call this to query the information from the bootloader. This
92function is enabled by default with
93:kconfig:option:`CONFIG_RETENTION_BOOTLOADER_INFO_OUTPUT_FUNCTION`, however,
94applications can optionally choose to use the settings storage feature instead.
95In this mode, the bootloader information can be queries by using settings keys,
96the following Kconfig options need to be enabled for this mode:
97
98* :kconfig:option:`CONFIG_SETTINGS`
99* :kconfig:option:`CONFIG_SETTINGS_RUNTIME`
100* :kconfig:option:`CONFIG_RETENTION_BOOTLOADER_INFO_OUTPUT_SETTINGS`
101
102This allows the information to be queried via the
103:c:func:`settings_runtime_get` function with the following keys:
104
105* ``blinfo/mode`` The mode that MCUboot is configured for
106  (``enum mcuboot_mode`` value)
107* ``blinfo/signature_type`` The signature type MCUboot is configured for
108  (``enum mcuboot_signature_type`` value)
109* ``blinfo/recovery`` The recovery type enabled in MCUboot
110  (``enum mcuboot_recovery_mode`` value)
111* ``blinfo/running_slot`` The running slot, useful for direct-XIP mode to know
112  which slot to use for an update
113* ``blinfo/bootloader_version`` Version of the bootloader
114  (``struct image_version`` object)
115* ``blinfo/max_application_size`` Maximum size of an application (in bytes)
116  that can be loaded
117
118In addition to the previous include, the following includes are required for
119this mode:
120
121.. code-block:: C
122
123	#include <bootutil/boot_status.h>
124	#include <bootutil/image.h>
125	#include <zephyr/mcuboot_version.h>
126	#include <zephyr/settings/settings.h>
127
128API Reference
129*************
130
131Bootloader information API
132==========================
133
134.. doxygengroup:: bootloader_info_interface
135