Part 1
요약·해설
Non-init RAM 예약, mutex 보호, boot mode와 17개 retention·bootmode API 심볼을 설명합니다.
Prefix · checksum
Partitioned retained RAM
Mode handoff
Part 2
접을 수 있는 영어 원문 전체
영어 원문 전체 펼치기
A08F5DA123764433936D032787C1145C3E5890EB82B101BE0F88BD9A53EC672D
.. _retention_api:
Retention System
################
The retention system provides an API which allows applications to read and
write data from and to memory areas or devices that retain the data while the
device is powered. This allows for sharing information between different
applications or within a single application without losing state information
when a device reboots. The stored data should not persist in the event of a
power failure (or during some low-power modes on some devices) nor should it be
stored to a non-volatile storage like :ref:`flash_api`, :ref:`eeprom_api`, or
battery-backed RAM.
The retention system builds on top of the retained data driver, and adds
additional software-level features to it for ensuring the validity of data.
Optionally, a magic header can be used to check if the front of
the retained data memory section contains this specific value, and an optional
checksum (1, 2, or 4-bytes in size) of the stored data can be appended to the
end of the data. Additionally, the retention system API allows partitioning of
the retained data sections into multiple distinct areas. For example, a 64-byte
retained data area could be split up into 4 bytes for a boot mode, 16 bytes for
a timestamp, 44 bytes for a last log message. All of these sections can be
accessed or updated independently. The prefix and checksum can be set
per-instance using devicetree.
Devicetree setup
****************
To use the retention system, a retained data driver must be setup for the board
you are using, there is a zephyr driver which can be used which will use some
RAM as non-init for this purpose. The retention system is then initialised as a
child node of this device 1 or more times - note that the memory region will
need to be decremented to account for this reserved portion of RAM. See the
following example (examples in this guide are based on the
:ref:`nrf52840dk_nrf52840` board and memory layout):
.. code-block:: devicetree
/ {
sram@2003FC00 {
compatible = "zephyr,memory-region", "mmio-sram";
reg = <0x2003FC00 DT_SIZE_K(1)>;
zephyr,memory-region = "RetainedMem";
status = "okay";
retainedmem {
compatible = "zephyr,retained-ram";
status = "okay";
#address-cells = <1>;
#size-cells = <1>;
/* This creates a 256-byte partition */
retention0: retention@0 {
compatible = "zephyr,retention";
status = "okay";
/* The total size of this area is 256
* bytes which includes the prefix and
* checksum, this means that the usable
* data storage area is 256 - 3 = 253
* bytes
*/
reg = <0x0 0x100>;
/* This is the prefix which must appear
* at the front of the data
*/
prefix = [08 04];
/* This uses a 1-byte checksum */
checksum = <1>;
};
/* This creates a 768-byte partition */
retention1: retention@100 {
compatible = "zephyr,retention";
status = "okay";
/* Start position must be after the end
* of the previous partition. The total
* size of this area is 768 bytes which
* includes the prefix and checksum,
* this means that the usable data
* storage area is 768 - 6 = 762 bytes
*/
reg = <0x100 0x300>;
/* This is the prefix which must appear
* at the front of the data
*/
prefix = [00 11 55 88 fa bc];
/* If omitted, there will be no
* checksum
*/
};
};
};
};
/* Reduce SRAM0 usage by 1KB to account for non-init area */
&sram0 {
reg = <0x20000000 DT_SIZE_K(255)>;
};
The retention areas can then be accessed using the data retention API (once
enabled with :kconfig:option:`CONFIG_RETENTION`, which requires that
:kconfig:option:`CONFIG_RETAINED_MEM` be enabled) by getting the device by
using:
.. code-block:: C
#include <zephyr/device.h>
#include <zephyr/retention/retention.h>
const struct device *retention1 = DEVICE_DT_GET(DT_NODELABEL(retention1));
const struct device *retention2 = DEVICE_DT_GET(DT_NODELABEL(retention2));
When the write function is called, the magic header and checksum (if enabled)
will be set on the area, and it will be marked as valid from that point
onwards.
Mutex protection
****************
Mutex protection of retention areas is enabled by default when applications are
compiled with multithreading support. This means that different threads can
safely call the retention functions without clashing with other concurrent
thread function usage, but means that retention functions cannot be used from
ISRs. It is possible to disable mutex protection globally on all retention
areas by enabling :kconfig:option:`CONFIG_RETENTION_MUTEX_FORCE_DISABLE` -
users are then responsible for ensuring that the function calls do not conflict
with each other. Note that to use this, retention driver mutex support must
also be disabled by enabling
:kconfig:option:`CONFIG_RETAINED_MEM_MUTEX_FORCE_DISABLE`.
.. _boot_mode_api:
Boot mode
*********
An addition to the retention subsystem is a boot mode interface, this can be
used to dynamically change the state of an application or run a different
application with a minimal set of functions when a device is rebooted (an
example is to have a buttonless way of entering mcuboot's serial recovery
feature from the main application).
To use the boot mode feature, a data retention entry must exist in the device
tree, which is dedicated for use as the boot mode selection (the user area data
size only needs to be a single byte), and this area be assigned to the chosen
node of ``zephyr,boot-mode``. See the following example:
.. code-block:: devicetree
/ {
sram@2003FFFF {
compatible = "zephyr,memory-region", "mmio-sram";
reg = <0x2003FFFF 0x1>;
zephyr,memory-region = "RetainedMem";
status = "okay";
retainedmem {
compatible = "zephyr,retained-ram";
status = "okay";
#address-cells = <1>;
#size-cells = <1>;
retention0: retention@0 {
compatible = "zephyr,retention";
status = "okay";
reg = <0x0 0x1>;
};
};
};
chosen {
zephyr,boot-mode = &retention0;
};
};
/* Reduce SRAM0 usage by 1 byte to account for non-init area */
&sram0 {
reg = <0x20000000 0x3FFFF>;
};
The boot mode interface can be enabled with
:kconfig:option:`CONFIG_RETENTION_BOOT_MODE` and then accessed by using the
boot mode functions. If using mcuboot with serial recovery, it can be built
with ``CONFIG_MCUBOOT_SERIAL`` and ``CONFIG_BOOT_SERIAL_BOOT_MODE`` enabled
which will allow rebooting directly into the serial recovery mode by using:
.. code-block:: C
#include <zephyr/retention/bootmode.h>
#include <zephyr/sys/reboot.h>
bootmode_set(BOOT_MODE_TYPE_BOOTLOADER);
sys_reboot(0);
Retention system modules
************************
Modules can expand the functionality of the retention system by using it as a
transport (e.g. between a bootloader and application).
.. toctree::
:maxdepth: 1
blinfo.rst
API Reference
*************
Retention system API
====================
.. doxygengroup:: retention_api
Boot mode interface
===================
.. doxygengroup:: boot_mode_interface
Part 3
한국어 전문 번역
Retention system은 device에 전력이 유지되는 동안 data를 보존하는 memory area 또는 device를 application이 읽고 쓰게 합니다. Reboot 사이에 application끼리 또는 한 application 내부에서 state를 공유할 수 있지만 power failure, 일부 low-power mode에서는 유지되지 않을 수 있습니다. Flash, EEPROM, battery-backed RAM 같은 non-volatile storage에 저장하는 기능은 아닙니다.
Retained data driver 위에 magic prefix와 optional checksum으로 data validity를 검사하는 software layer를 더합니다. Checksum은 1·2·4 byte를 지원하고 retained area를 여러 독립 partition으로 나눌 수 있습니다. 예를 들어 64 byte를 boot mode 4 byte, timestamp 16 byte, 마지막 log 44 byte로 나눠 각각 접근할 수 있으며 prefix와 checksum은 devicetree instance별로 설정합니다.
Devicetree setup
Board에 retained data driver가 필요합니다. Zephyr의 retained-RAM driver는 RAM 일부를 non-init 영역으로 사용할 수 있고, retention instance는 그 device의 child node로 하나 이상 정의합니다. Reserved RAM만큼 일반 memory region 크기도 줄여야 합니다.
/ {
sram@2003FC00 {
compatible = "zephyr,memory-region", "mmio-sram";
reg = <0x2003FC00 DT_SIZE_K(1)>;
zephyr,memory-region = "RetainedMem";
status = "okay";
retainedmem {
compatible = "zephyr,retained-ram";
status = "okay";
#address-cells = <1>;
#size-cells = <1>;
/* This creates a 256-byte partition */
retention0: retention@0 {
compatible = "zephyr,retention";
status = "okay";
/* The total size of this area is 256
* bytes which includes the prefix and
* checksum, this means that the usable
* data storage area is 256 - 3 = 253
* bytes
*/
reg = <0x0 0x100>;
/* This is the prefix which must appear
* at the front of the data
*/
prefix = [08 04];
/* This uses a 1-byte checksum */
checksum = <1>;
};
/* This creates a 768-byte partition */
retention1: retention@100 {
compatible = "zephyr,retention";
status = "okay";
/* Start position must be after the end
* of the previous partition. The total
* size of this area is 768 bytes which
* includes the prefix and checksum,
* this means that the usable data
* storage area is 768 - 6 = 762 bytes
*/
reg = <0x100 0x300>;
/* This is the prefix which must appear
* at the front of the data
*/
prefix = [00 11 55 88 fa bc];
/* If omitted, there will be no
* checksum
*/
};
};
};
};
/* Reduce SRAM0 usage by 1KB to account for non-init area */
&sram0 {
reg = <0x20000000 DT_SIZE_K(255)>;
};
예제의 retention0은 256 byte partition이며 2-byte prefix와 1-byte checksum을 제외한 253 byte가 user data입니다. retention1은 offset 0x100부터 768 byte를 사용하고 6-byte prefix만 있어 762 byte를 사용할 수 있습니다.
CONFIG_RETENTION과 그 dependency인 CONFIG_RETAINED_MEM을 활성화한 뒤 device pointer를 devicetree label로 얻습니다.
#include <zephyr/device.h>
#include <zephyr/retention/retention.h>
const struct device *retention1 = DEVICE_DT_GET(DT_NODELABEL(retention1));
const struct device *retention2 = DEVICE_DT_GET(DT_NODELABEL(retention2));
Write가 성공하면 magic header와 enabled checksum이 저장되고 해당 area는 이후 retention_is_valid()에서 valid로 판정됩니다.
Mutex protection
Multithreading build에서는 retention area mutex protection이 기본 활성화돼 여러 thread가 동시에 API를 안전하게 호출할 수 있지만 ISR에서는 사용할 수 없습니다. CONFIG_RETENTION_MUTEX_FORCE_DISABLE로 모든 retention mutex를 끌 수 있으며 이때 caller가 충돌을 직접 방지해야 합니다. Underlying driver mutex도 CONFIG_RETAINED_MEM_MUTEX_FORCE_DISABLE로 함께 꺼야 합니다.
Boot mode
Boot mode interface는 reboot 뒤 같은 application의 실행 상태를 바꾸거나 최소 function 집합의 다른 application을 실행하도록 선택합니다. 대표적으로 main application에서 button 없이 MCUboot serial recovery로 진입할 수 있습니다.
Boot mode 전용 retention entry는 user data 1 byte면 충분하며 chosen node의 zephyr,boot-mode가 해당 area를 가리켜야 합니다.
/ {
sram@2003FFFF {
compatible = "zephyr,memory-region", "mmio-sram";
reg = <0x2003FFFF 0x1>;
zephyr,memory-region = "RetainedMem";
status = "okay";
retainedmem {
compatible = "zephyr,retained-ram";
status = "okay";
#address-cells = <1>;
#size-cells = <1>;
retention0: retention@0 {
compatible = "zephyr,retention";
status = "okay";
reg = <0x0 0x1>;
};
};
};
chosen {
zephyr,boot-mode = &retention0;
};
};
/* Reduce SRAM0 usage by 1 byte to account for non-init area */
&sram0 {
reg = <0x20000000 0x3FFFF>;
};
CONFIG_RETENTION_BOOT_MODE로 interface를 켭니다. MCUboot serial recovery를 사용한다면 CONFIG_MCUBOOT_SERIAL과 CONFIG_BOOT_SERIAL_BOOT_MODE를 활성화하고 다음처럼 bootloader mode를 기록한 뒤 reboot합니다.
#include <zephyr/retention/bootmode.h>
#include <zephyr/sys/reboot.h>
bootmode_set(BOOT_MODE_TYPE_BOOTLOADER);
sys_reboot(0);
Retention system modules
Module은 retention system을 bootloader와 application 사이 transport로 사용해 기능을 확장할 수 있습니다. Bootloader shared data는 Bootloader Information module에서 설명합니다.
API Reference
Retention system API
retention_size_api(dev)- Driver가 제공하는 retention area 크기를 반환하는 function-pointer type입니다.
retention_is_valid_api(dev)- Underlying retained data가 prefix와 checksum 기준으로 valid한지 확인하는 driver callback type입니다.
retention_read_api(dev, offset, size, data)- Retention area의 지정 offset에서 data를 읽는 driver callback type입니다.
retention_write_api(dev, offset, size, data)- Retention area에 data를 쓰고 validity metadata를 갱신하는 driver callback type입니다.
retention_clear_api(dev)- Retention area 전체를 0으로 지우는 driver callback type입니다.
retention_size(dev)- Application이 사용할 수 있는 retention data area 크기를 byte 단위로 반환합니다.
retention_is_valid(dev)- 현재 retained data가 magic prefix·checksum 검사를 통과하는지 확인합니다.
retention_read(dev, offset, size, data)- Valid retention area의 범위 안에서 data를 읽습니다.
retention_write(dev, offset, size, data)- 사전 clear 없이 data를 쓰며 성공하면
retention_is_valid()에서 valid로 분류됩니다. retention_clear(dev)- Area의 모든 data를 0으로 만들고 기존 retained state를 제거합니다.
struct retention_api- Retention driver가 size, validity, read, write와 clear callback을 제공하는 API vtable입니다.
Boot mode interface
enum BOOT_MODE_TYPES- Retention byte에 기록할 boot mode 값 집합입니다.
BOOT_MODE_TYPE_NORMAL- 기본 normal boot로 user application을 실행합니다.
BOOT_MODE_TYPE_BOOTLOADER- MCUboot serial recovery 같은 bootloader mode로 진입합니다.
bootmode_check(mode)- 현재 retained boot mode가 지정 값인지 확인합니다.
bootmode_set(mode)- 다음 reboot에서 사용할 boot mode를 기록합니다.
bootmode_clear()- Boot mode 값을 0으로 지워
BOOT_MODE_TYPE_NORMAL로 되돌립니다.
Source
출처
영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.