Part 1
요약·해설
MCUboot와 application의 공통 devicetree, Kconfig backend, lookup 함수와 blinfo/ settings key를 설명합니다.
Retention area
MCUboot
Lookup · Settings
Part 2
접을 수 있는 영어 원문 전체
영어 원문 전체 펼치기
990F067C0E8B84BD5C793D5630D814F5F11A947FA2BA944AC0C747566D7619D3
.. _blinfo_api:
Bootloader Information
######################
The bootloader information (abbreviated to blinfo) subsystem is an extension of
the :ref:`retention_api` which allows for reading shared data from a bootloader
and allowing applications to query it. It has an optional feature of organising
the information retrieved from the bootloader and storing it in the
:ref:`settings_api` with the ``blinfo/`` prefix.
Devicetree setup
****************
To use the bootloader information subsystem, a retention area needs to be
created which has a retained data section as its parent, generally non-init RAM
is used for this purpose. See the following example (examples in this guide are
based on the :ref:`nrf52840dk_nrf52840` board and memory layout):
.. code-block:: devicetree
/ {
sram@2003F000 {
compatible = "zephyr,memory-region", "mmio-sram";
reg = <0x2003F000 DT_SIZE_K(1)>;
zephyr,memory-region = "RetainedMem";
status = "okay";
retainedmem {
compatible = "zephyr,retained-ram";
status = "okay";
#address-cells = <1>;
#size-cells = <1>;
boot_info0: boot_info@0 {
compatible = "zephyr,retention";
status = "okay";
reg = <0x0 0x100>;
};
};
};
chosen {
zephyr,bootloader-info = &boot_info0;
};
};
/* Reduce SRAM0 usage by 1KB to account for non-init area */
&sram0 {
reg = <0x20000000 DT_SIZE_K(255)>;
};
Note that this configuration needs to be applied on both the bootloader
(MCUboot) and application to be usable. It can be combined with other retention
system APIs such as the :ref:`boot_mode_api`
MCUboot setup
*************
Once the above devicetree configuration is applied, MCUboot needs to be
configured to store the shared data in this area, the following Kconfigs need
to be set for this:
* :kconfig:option:`CONFIG_RETAINED_MEM` - Enables retained memory driver
* :kconfig:option:`CONFIG_RETENTION` - Enables retention system
* :kconfig:option:`CONFIG_BOOT_SHARE_DATA` - Enables shared data
* :kconfig:option:`CONFIG_BOOT_SHARE_DATA_BOOTINFO` - Enables boot information
shared data type
* :kconfig:option:`CONFIG_BOOT_SHARE_BACKEND_RETENTION` - Stores shared data
using retention/blinfo subsystem
Application setup
*****************
The application must enable the following base Kconfig options for the
bootloader information subsystem to function:
* :kconfig:option:`CONFIG_RETAINED_MEM`
* :kconfig:option:`CONFIG_RETENTION`
* :kconfig:option:`CONFIG_RETENTION_BOOTLOADER_INFO`
* :kconfig:option:`CONFIG_RETENTION_BOOTLOADER_INFO_TYPE_MCUBOOT`
The following include is needed to use the bootloader information subsystem:
.. code-block:: C
#include <zephyr/retention/blinfo.h>
By default, only the lookup function is provided: :c:func:`blinfo_lookup`, the
application can call this to query the information from the bootloader. This
function is enabled by default with
:kconfig:option:`CONFIG_RETENTION_BOOTLOADER_INFO_OUTPUT_FUNCTION`, however,
applications can optionally choose to use the settings storage feature instead.
In this mode, the bootloader information can be queries by using settings keys,
the following Kconfig options need to be enabled for this mode:
* :kconfig:option:`CONFIG_SETTINGS`
* :kconfig:option:`CONFIG_SETTINGS_RUNTIME`
* :kconfig:option:`CONFIG_RETENTION_BOOTLOADER_INFO_OUTPUT_SETTINGS`
This allows the information to be queried via the
:c:func:`settings_runtime_get` function with the following keys:
* ``blinfo/mode`` The mode that MCUboot is configured for
(``enum mcuboot_mode`` value)
* ``blinfo/signature_type`` The signature type MCUboot is configured for
(``enum mcuboot_signature_type`` value)
* ``blinfo/recovery`` The recovery type enabled in MCUboot
(``enum mcuboot_recovery_mode`` value)
* ``blinfo/running_slot`` The running slot, useful for direct-XIP mode to know
which slot to use for an update
* ``blinfo/bootloader_version`` Version of the bootloader
(``struct image_version`` object)
* ``blinfo/max_application_size`` Maximum size of an application (in bytes)
that can be loaded
In addition to the previous include, the following includes are required for
this mode:
.. code-block:: C
#include <bootutil/boot_status.h>
#include <bootutil/image.h>
#include <zephyr/mcuboot_version.h>
#include <zephyr/settings/settings.h>
API Reference
*************
Bootloader information API
==========================
.. doxygengroup:: bootloader_info_interface
Part 3
한국어 전문 번역
Bootloader Information, 줄여서 blinfo subsystem은 Retention System의 extension입니다. Bootloader가 공유한 data를 읽고 application이 query할 수 있으며, optional 기능으로 정보를 정리해 blinfo/ prefix의 Settings key로 저장합니다.
Devicetree setup
Bootloader information용 retention area는 retained data section의 child로 만들며 일반적으로 non-init RAM을 사용합니다. 다음 예는 nRF52840 DK memory layout에서 1 KiB를 예약하고 zephyr,bootloader-info chosen node로 연결합니다.
/ {
sram@2003F000 {
compatible = "zephyr,memory-region", "mmio-sram";
reg = <0x2003F000 DT_SIZE_K(1)>;
zephyr,memory-region = "RetainedMem";
status = "okay";
retainedmem {
compatible = "zephyr,retained-ram";
status = "okay";
#address-cells = <1>;
#size-cells = <1>;
boot_info0: boot_info@0 {
compatible = "zephyr,retention";
status = "okay";
reg = <0x0 0x100>;
};
};
};
chosen {
zephyr,bootloader-info = &boot_info0;
};
};
/* Reduce SRAM0 usage by 1KB to account for non-init area */
&sram0 {
reg = <0x20000000 DT_SIZE_K(255)>;
};
MCUboot setup
MCUboot가 이 area에 shared boot information을 저장하려면 다음 Kconfig를 활성화합니다.
CONFIG_RETAINED_MEM: retained memory driverCONFIG_RETENTION: retention systemCONFIG_BOOT_SHARE_DATA: shared dataCONFIG_BOOT_SHARE_DATA_BOOTINFO: boot information shared-data typeCONFIG_BOOT_SHARE_BACKEND_RETENTION: retention/blinfo backend
Application setup
Application은 CONFIG_RETAINED_MEM, CONFIG_RETENTION, CONFIG_RETENTION_BOOTLOADER_INFO, CONFIG_RETENTION_BOOTLOADER_INFO_TYPE_MCUBOOT을 활성화하고 다음 header를 include합니다.
#include <zephyr/retention/blinfo.h>
기본 output은 CONFIG_RETENTION_BOOTLOADER_INFO_OUTPUT_FUNCTION이 제공하는 blinfo_lookup()입니다. 대신 Settings storage를 사용하려면 CONFIG_SETTINGS, CONFIG_SETTINGS_RUNTIME, CONFIG_RETENTION_BOOTLOADER_INFO_OUTPUT_SETTINGS을 활성화합니다.
Settings mode에서는 settings_runtime_get()으로 다음 key를 조회합니다.
blinfo/mode: MCUboot mode,enum mcuboot_modeblinfo/signature_type: signature type,enum mcuboot_signature_typeblinfo/recovery: enabled recovery type,enum mcuboot_recovery_modeblinfo/running_slot: direct-XIP update에 필요한 현재 slotblinfo/bootloader_version:struct image_versionbootloader versionblinfo/max_application_size: load 가능한 application 최대 byte 크기
Settings mode에는 boot status, image, MCUboot version과 settings header도 필요합니다.
#include <bootutil/boot_status.h>
#include <bootutil/image.h>
#include <zephyr/mcuboot_version.h>
#include <zephyr/settings/settings.h>
API Reference
Bootloader information API
blinfo_lookup(type, data, size)- Bootloader가 retention area에 공유한 boot information type을 찾아 caller buffer로 반환합니다. Requested type, destination과 size contract를 지켜야 합니다.
Source
출처
영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.