Part 1
요약·해설
DTS fixed-partitions에서 flash map이 생성되는 과정, area open과 compile-time macro, partition 경계가 확인되는 I/O를 설명합니다.
Devicetree partitions
Area ID · label
Bounded flash I/O
Part 2
접을 수 있는 영어 원문 전체
영어 원문 전체 펼치기
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)을 사용합니다.
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_tflash_area_foreach()가 각 flash area와 user data를 전달할 때 사용하는 callback type입니다.flash_area_open- 8-bit area ID로 flash map을 검색해
flash_areapointer를 돌려줍니다. 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
출처
영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.