services/retention/blinfo.html · services/retention/blinfo.rst 공식 원문 ↗

Zephyr 3.7.0 · OS Services · Retention

Bootloader Information

Bootloader가 남긴 mode, signature, recovery, slot과 version 정보를 application에서 조회합니다.

Official pathservices/retention/blinfo.html
Source fileservices/retention/blinfo.rst
Source versionZephyr 3.7.0
TranslationFull · reviewed

본문 기준: Zephyr 3.7.0 LTS3 · 이후 유지보수 패치는 별도입니다.

Part 1

요약·해설

MCUboot와 application의 공통 devicetree, Kconfig backend, lookup 함수와 blinfo/ settings key를 설명합니다.

Transport

Retention area

Producer

MCUboot

Outputs

Lookup · Settings

Part 2

접을 수 있는 영어 원문 전체

영어 원문 전체 펼치기
원문 SHA-256 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 driver
  • CONFIG_RETENTION: retention system
  • CONFIG_BOOT_SHARE_DATA: shared data
  • CONFIG_BOOT_SHARE_DATA_BOOTINFO: boot information shared-data type
  • CONFIG_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_mode
  • blinfo/signature_type: signature type, enum mcuboot_signature_type
  • blinfo/recovery: enabled recovery type, enum mcuboot_recovery_mode
  • blinfo/running_slot: direct-XIP update에 필요한 현재 slot
  • blinfo/bootloader_version: struct image_version bootloader version
  • blinfo/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

출처

영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.