services/storage/flash_map/flash_map.html · services/storage/flash_map/flash_map.rst 공식 원문 ↗

Zephyr 3.7.0 · Storage · Flash Partitions

Flash Map

Flash partition을 전역 ID와 안전한 area descriptor로 연결합니다.

Official pathservices/storage/flash_map/flash_map.html
Source fileservices/storage/flash_map/flash_map.rst
Source versionZephyr 3.7.0
TranslationFull · reviewed

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

Part 1

요약·해설

DTS fixed-partitions에서 flash map이 생성되는 과정, area open과 compile-time macro, partition 경계가 확인되는 I/O를 설명합니다.

Source

Devicetree partitions

Identity

Area ID · label

Access

Bounded flash I/O

Part 2

접을 수 있는 영어 원문 전체

영어 원문 전체 펼치기
원문 SHA-256 EC082038AB8CAD03654E8308B5727163DCF812BA260BBFEC3606BEB27F90F9F6
.. _flash_map_api:

Flash map
#########

The ``<zephyr/storage/flash_map.h>`` API allows accessing information about device
flash partitions via :c:struct:`flash_area` structures.

Each :c:struct:`flash_area` describes a flash partition. The API provides access
to a "flash map", which contains predefined flash areas accessible via globally
unique ID numbers. The map is created from "fixed-partition" compatible entries
in DTS file. Users may also create :c:struct:`flash_area` objects at runtime
for application-specific purposes.

This documentation uses "flash area" when referencing single "fixed-partition"
entities.

The :c:struct:`flash_area` contains a pointer to a :c:struct:`device`,
which can be used to access the flash device an area is placed on directly
with the :ref:`flash API <flash_api>`.
Each flash area is characterized by a device it is placed on, offset
from the beginning of the device and size on the device.
An additional identifier parameter is used by the :c:func:`flash_area_open`
function to find flash area in flash map.

The flash_map.h API provides functions for operating on a :c:struct:`flash_area`.
The main examples are :c:func:`flash_area_read` and :c:func:`flash_area_write`.
These functions are basically wrappers around the flash API with additional
offset and size checks, to limit flash operations to a predefined area.

Most ``<zephyr/storage/flash_map.h>`` API functions require a :c:struct:`flash_area` object pointer
characterizing the flash area they will be working on. There are two possible
methods to obtain such a pointer:

 * obtain it using `flash_area_open`;

 * defining a :c:struct:`flash_area` type object, which requires providing
   a valid :c:struct:`device` object pointer with offset and size of the area
   within the flash device.

:c:func:`flash_area_open` uses numeric identifiers to search flash map for
:c:struct:`flash_area` objects and returns, if found, a pointer to an object
representing area with given ID.
The ID number for a flash area can be obtained from a fixed-partition
DTS node label using :c:macro:`FIXED_PARTITION_ID()`; these labels are obtained
from the devicetree as described below.

Relationship with Devicetree
****************************

The flash_map.h API uses data generated from the :ref:`devicetree_api`, in
particular its :ref:`devicetree-flash-api`. Zephyr additionally has some
partitioning conventions used for :ref:`dfu` via the MCUboot bootloader, as
well as defining partitions usable by :ref:`file systems <file_system_api>` or
other nonvolatile :ref:`storage <storage_reference>`.

Here is an example devicetree fragment which uses fixed flash partitions for
both MCUboot and a storage partition. Some details were left out for clarity.

.. literalinclude:: ../../../../../services/storage/flash_map/example_fragment.dts
   :language: DTS
   :start-after: start-after-here

Partition offset shall be expressed in relation to the flash memory beginning
address, to which the partition belongs to.

The ``boot_partition``, ``slot0_partition``, ``slot1_partition``, and
``scratch_partition`` node labels are defined for MCUboot, though not all MCUboot
configurations require all of them to be defined. See the `MCUboot
documentation`_ for more details.

The ``storage_partition`` node is defined for use by a file system or other
nonvolatile storage API.

.. _MCUboot documentation: https://docs.mcuboot.com

Numeric flash area ID is obtained by passing DTS node label to
:c:macro:`FIXED_PARTITION_ID()`; for example to obtain ID number
for ``slot0_partition``, user would invoke ``FIXED_PARTITION_ID(slot0_partition)``.

All :c:macro:`FIXED_PARTITION_` macros take DTS node labels as partition
identifiers.

Users do not have to obtain a :c:struct:`flash_area` object pointer
using :c:func:`flash_map_open` to get information on flash area size, offset
or device, if such area is defined in DTS file. Knowing the DTS node label
of an area, users may use :c:macro:`FIXED_PARTITION_OFFSET()`,
:c:macro:`FIXED_PARTITION_SIZE()` or :c:macro:`FIXED_PARTITION_DEVICE()`
respectively to obtain such information directly from DTS node definition.
For example to obtain offset of ``storage_partition`` it is enough to
invoke ``FIXED_PARTITION_OFFSET(storage_partition)``.

Below example shows how to obtain a :c:struct:`flash_area` object pointer
using :c:func:`flash_area_open` and DTS node label:

.. code-block:: c

   const struct flash_area *my_area;
   int err = flash_area_open(FIXED_PARTITION_ID(slot0_partition), &my_area);

   if (err != 0) {
   	handle_the_error(err);
   } else {
   	flash_area_read(my_area, ...);
   }

API Reference
*************

.. doxygengroup:: flash_area_api

Part 3

한국어 전문 번역

<zephyr/storage/flash_map.h> API는 flash_area 구조체를 통해 device flash partition 정보를 조회하고 partition 경계 안에서 I/O를 수행하게 합니다.

각 flash_area는 flash partition 하나를 설명합니다. Flash map은 미리 정의된 area를 전역 고유 숫자 ID와 연결하며, DTS의 fixed-partitions compatible entry에서 생성됩니다. Application 전용 목적이라면 runtime에 직접 flash_area 객체를 만들 수도 있습니다.

이 문서에서 flash area는 fixed-partition entity 하나를 뜻합니다. Descriptor는 backing device pointer, device 시작점 기준 offset, area size와 식별자를 가집니다. Device pointer를 얻으면 일반 Flash API로 장치에 직접 접근할 수도 있습니다.

flash_area_read()와 flash_area_write() 같은 함수는 일반 Flash API를 감싸면서 offset과 length가 area 밖으로 벗어나지 않는지 추가로 검사합니다. Partition 경계는 보호하지만 장치 자체의 read·write·erase alignment 제약까지 없애지는 않습니다.

대부분의 함수에는 대상 flash_area *가 필요합니다. 이를 얻는 방법은 두 가지입니다. flash_area_open()에 ID를 넘겨 map에서 찾거나, 유효한 device pointer·offset·size를 채워 application이 descriptor를 직접 정의합니다.

flash_area_open()은 숫자 ID를 검색합니다. DTS node label에서 ID를 만들 때는 FIXED_PARTITION_ID(label)을 사용합니다.

Devicetree에서 flash area access까지
fixed-partitionslabel · offset · size를 DTS에 선언
build-time 생성
Flash map전역 고유 ID와 flash_area를 연결
flash_area_open(ID)
flash_areadevice · offset · size 경계를 보유
checked wrapper
Flash driverread · write · erase를 실제 장치에 수행

Relationship with Devicetree

Flash Map API는 Devicetree API, 특히 flash partition 정의에서 생성된 정보를 사용합니다. 같은 partition 체계는 MCUboot를 통한 DFU, filesystem, settings나 기타 nonvolatile storage에도 쓰입니다.

다음 DTS fragment는 한 flash 장치를 MCUboot boot·slot·scratch partition과 일반 storage partition으로 나눕니다. 생략된 세부 사항을 제외한 공식 원문 코드 그대로입니다.

/ {
	soc {
		flashctrl: flash-controller@deadbeef {
			flash0: flash@0 {
				compatible = "soc-nv-flash";
				reg = <0x0 0x100000>;

				partitions {
					compatible = "fixed-partitions";
					#address-cells = <0x1>;
					#size-cells = <0x1>;

					boot_partition: partition@0 {
						reg = <0x0 0x10000>;
						read-only;
					};
					storage_partition: partition@1e000 {
						reg = <0x1e000 0x2000>;
					};
					slot0_partition: partition@20000 {
						reg = <0x20000 0x60000>;
					};
					slot1_partition: partition@80000 {
						reg = <0x80000 0x60000>;
					};
					scratch_partition: partition@e0000 {
						reg = <0xe0000 0x20000>;
					};
				};
			};
		};
	};
};

Partition offset은 그 partition이 속한 flash memory의 시작 주소를 기준으로 표현해야 합니다. 예를 들어 partition@20000의 reg = <0x20000 0x60000>은 device 시작점에서 0x20000 떨어진 곳부터 0x60000 byte를 차지한다는 뜻입니다.

boot_partition, slot0_partition, slot1_partition, scratch_partition label은 MCUboot 관례입니다. 모든 MCUboot 설정이 네 partition을 전부 요구하는 것은 아닙니다. storage_partition은 filesystem이나 다른 nonvolatile storage API가 쓰도록 정의한 영역입니다.

숫자 flash area ID는 FIXED_PARTITION_ID(slot0_partition)처럼 DTS node label을 넘겨 얻습니다. FIXED_PARTITION_* macro는 모두 partition identifier로 DTS node label을 받습니다.

DTS에 정의된 area의 정보만 필요하다면 flash_area_open()을 부를 필요가 없습니다. FIXED_PARTITION_OFFSET(), FIXED_PARTITION_SIZE(), FIXED_PARTITION_DEVICE()로 offset, size, device를 build time에 직접 얻을 수 있습니다.

다음 예제는 label에서 ID를 만들고 area를 열어 읽습니다. 오류가 아니면 반환된 descriptor를 I/O 함수에 전달합니다.

const struct flash_area *my_area;
int err = flash_area_open(FIXED_PARTITION_ID(slot0_partition), &my_area);

if (err != 0) {
     handle_the_error(err);
} else {
     flash_area_read(my_area, ...);
}

API Reference

Macro와 구조체는 compile-time partition 정보를 표현하고, function은 map 조회와 경계 검사된 I/O를 제공합니다.

SOC_FLASH_0_ID
MCUboot 호환을 위해 제공되는 SoC flash area 식별자입니다.
SPI_FLASH_0_ID
MCUboot 호환을 위해 제공되는 SPI flash area 식별자입니다.
FIXED_PARTITION_EXISTS
주어진 DTS node label의 fixed-partition이 존재하고 enabled인지 build time에 검사합니다.
FIXED_PARTITION_ID
Partition node label을 flash map의 숫자 area ID로 변환합니다.
FIXED_PARTITION_OFFSET
DTS node label로 partition의 device-relative offset을 얻습니다.
FIXED_PARTITION_NODE_OFFSET
Devicetree node identifier로 partition offset을 얻습니다.
FIXED_PARTITION_SIZE
DTS node label로 partition 크기를 얻습니다.
FIXED_PARTITION_NODE_SIZE
Devicetree node identifier로 partition 크기를 얻습니다.
FLASH_AREA_DEVICE
해당 area 또는 partition이 놓인 flash device의 const struct device *를 얻습니다.
FIXED_PARTITION_DEVICE
Partition label이 속한 flash device pointer를 얻습니다.
FIXED_PARTITION_NODE_DEVICE
Partition node가 속한 flash device pointer를 얻습니다.
flash_area_cb_t
flash_area_foreach()가 각 flash area와 user data를 전달할 때 사용하는 callback type입니다.
flash_area_open
8-bit area ID로 flash map을 검색해 flash_area pointer를 돌려줍니다. Map 없음은 -EACCES, ID 없음은 -ENOENT, driver 없음은 -ENODEV입니다.
flash_area_close
Flash area를 닫는 호환 API입니다. Zephyr 3.7에서는 future use를 위해 예약된 no-op입니다.
flash_area_read
Area 시작 기준 offset에서 읽습니다. 요청 경계를 먼저 검사하며 underlying driver의 read alignment 제약은 그대로 적용됩니다.
flash_area_write
Area 시작 기준 offset에 씁니다. Partition 밖 write를 차단하지만 driver의 write-block alignment 제약은 호출자가 지켜야 합니다.
flash_area_erase
Area 안의 지정 범위를 erase합니다. 경계 검사와 함께 erase-block alignment·size 제약이 적용됩니다.
flash_area_flatten
Program-erase 장치에서는 erase하고, erase가 필요 없는 RAM형 비휘발 장치에서는 callback 또는 erase value write로 범위를 평탄화합니다. Emulated erase도 endurance를 소비할 수 있습니다.
flash_area_align
이 flash area가 요구하는 write block alignment를 byte 단위로 반환합니다.
flash_area_get_sectors
Area 안 sector 정보를 caller array에 채웁니다. 배열 capacity가 부족하면 -ENOMEM을 반환합니다.
flash_area_foreach
Flash map의 모든 area를 순회하며 user callback을 호출합니다.
flash_area_has_driver
Area를 지원하는 flash driver가 연결됐는지 확인합니다. 있으면 1, 없으면 -ENODEV입니다.
flash_area_get_device
Area를 담당하는 device driver pointer를 반환합니다.
flash_area_erased_val
Erase된 flash byte를 읽었을 때 기대되는 값을 반환하며 MCUboot porting layer와 호환됩니다.
flash_area
한 partition의 ID, device-relative offset, size와 backing device를 묶는 descriptor입니다.
flash_area.fa_id
Flash map 안에서 area를 찾는 전역 고유 ID입니다.
flash_area.fa_off
Backing flash device 시작점에서 area 시작점까지의 byte offset입니다.
flash_area.fa_size
Area가 차지하는 byte 크기이며 wrapper의 경계 검사에 사용됩니다.
flash_area.fa_dev
실제 read·write·erase 요청을 받는 flash device pointer입니다.
flash_sector
Flash area 내부 한 sector의 offset과 size를 표현합니다.
flash_sector.fs_off
Area 시작을 기준으로 한 sector offset입니다.
flash_sector.fs_size
해당 sector의 byte 크기입니다.

Source

출처

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