Part 1
요약·해설
FCB entry layout과 incomplete-write detection, append·finish·walk·getnext·rotate 수명주기를 설명합니다.
Append · finish
Walk · getnext
Sector rotate
Part 2
접을 수 있는 영어 원문 전체
영어 원문 전체 펼치기
7533866D4FD8F2779DFA9D872BA9901FF8BB95235DDD43D72559732D141F688F
.. _fcb_api:
Flash Circular Buffer (FCB)
###########################
Flash circular buffer provides an abstraction through which you can treat
flash like a FIFO. You append entries to the end, and read data from the
beginning.
.. note::
As of Zephyr release 2.1 the :ref:`NVS <nvs_api>` storage API is
recommended over FCB for use as a back-end for the :ref:`settings API
<settings_api>`.
Description
***********
Entries in the flash contain the length of the entry, the data within
the entry, and checksum over the entry contents.
Storage of entries in flash is done in a FIFO fashion. When you
request space for the next entry, space is located at the end of the
used area. When you start reading, the first entry served is the
oldest entry in flash.
Entries can be appended to the end of the area until storage space is
exhausted. You have control over what happens next; either erase oldest
block of data, thereby freeing up some space, or stop writing new data
until existing data has been collected. FCB treats underlying storage as
an array of flash sectors; when it erases old data, it does this a
sector at a time.
Entries in the flash are checksummed. That is how FCB detects whether
writing entry to flash completed ok. It will skip over entries which
don't have a valid checksum.
Usage
*****
To add an entry to circular buffer:
- Call :c:func:`fcb_append` to get the location where data can be written. If
this fails due to lack of space, you can call :c:func:`fcb_rotate` to erase
the oldest sector which will make the space. And then call
:c:func:`fcb_append` again.
- Use :c:func:`flash_area_write` to write entry contents.
- Call :c:func:`fcb_append_finish` when done. This completes the writing of the
entry by calculating the checksum.
To read contents of the circular buffer:
- Call :c:func:`fcb_walk` with a pointer to your callback function.
- Within callback function copy in data from the entry using
:c:func:`flash_area_read`. You can tell when all data from within a sector
has been read by monitoring the returned entry's area pointer. Then you
can call :c:func:`fcb_rotate`, if you're done with that data.
Alternatively:
- Call :c:func:`fcb_getnext` with 0 in entry offset to get the pointer to
the oldest entry.
- Use :c:func:`flash_area_read` to read entry contents.
- Call :c:func:`fcb_getnext` with pointer to current entry to get the next one.
And so on.
API Reference
*************
The FCB subsystem APIs are provided by ``fcb.h``:
Data structures
===============
.. doxygengroup:: fcb_data_structures
API functions
=============
.. doxygengroup:: fcb_api
Part 3
한국어 전문 번역
Flash Circular Buffer(FCB)는 flash를 FIFO처럼 다루는 abstraction입니다. Entry를 끝에 append하고 시작의 oldest entry부터 읽습니다. Settings backend에는 Zephyr 2.1부터 FCB보다 NVS가 권장됩니다.
Description
각 flash entry에는 length, payload data와 entry content checksum이 들어갑니다. 새 entry 공간은 used area 끝에서 찾고 read는 flash에서 가장 오래된 entry부터 반환합니다.
공간이 다 차면 application policy에 따라 oldest data block을 erase해 공간을 만들거나, 기존 data를 수집할 때까지 새 write를 중지할 수 있습니다. FCB는 storage를 flash sector array로 보고 old data를 sector 단위로 지웁니다.
Checksum은 power loss 등으로 entry write가 끝까지 완료됐는지 판별합니다. Valid checksum이 없는 incomplete entry는 scan에서 건너뜁니다.
Usage
Entry 추가 순서는 다음과 같습니다.
fcb_append()로 write location을 얻습니다. 공간 부족이면fcb_rotate()로 oldest sector를 erase하고 append를 다시 시도합니다.flash_area_write()로 payload를 씁니다.fcb_append_finish()으로 checksum을 계산·기록해 entry를 완료합니다.
Read는 두 방식입니다. fcb_walk() callback에서 flash_area_read()로 data를 복사하고 area pointer가 바뀌는 시점에 sector 끝을 감지해 처리 완료 sector를 rotate할 수 있습니다.
또는 entry offset 0으로 fcb_getnext()를 호출해 oldest entry를 얻고, 읽은 뒤 현재 entry pointer로 다시 호출해 다음 entry를 순차 탐색합니다.
API Reference
FCB API는 fcb.h가 제공합니다.
Data structures
Entry location, walk context와 circular sector state입니다.
API functions
FCB_MAX_LEN- FCB entry data가 가질 수 있는 최대 길이입니다.
FCB_ENTRY_FA_DATA_OFF- Entry location에서 payload data의 flash-area offset을 계산합니다.
FCB_FLAGS_CRC_DISABLED- Entry CRC/checksum 검증을 비활성화하는 configuration flag입니다.
fcb_entry- 한 record의 sector, element offset, data offset과 data 길이를 표현합니다.
fcb_entry.fe_sector- Entry가 저장된 flash sector descriptor입니다.
fcb_entry.fe_elem_off- Sector 안 entry header의 byte offset입니다.
fcb_entry.fe_data_off- Sector 안 payload data의 byte offset입니다.
fcb_entry.fe_data_len- Payload data 길이입니다.
fcb_entry_ctx- Walk 중 entry와 해당 flash-area pointer를 함께 전달하는 context입니다.
fcb_entry_ctx.loc- 현재 FCB entry location입니다.
fcb_entry_ctx.fap- Entry가 속한 open flash-area pointer입니다.
fcb- Sector ring, magic/version, oldest·active pointer와 flash geometry를 가진 FCB instance입니다.
fcb.f_magic- Valid FCB entry를 식별하는 magic value입니다.
fcb.f_version- Stored entry format version입니다.
fcb.f_sector_cnt- Ring을 구성하는 flash sector 수입니다.
fcb.f_scratch_cnt- Rotation에 사용할 scratch sector 수입니다.
fcb.f_sectors- Flash sector descriptor array입니다.
fcb.f_mtx- Concurrent FCB operation을 보호하는 mutex입니다.
fcb.f_oldest- 가장 오래된 valid data가 있는 sector입니다.
fcb.f_active- 새 entry를 append하는 active sector입니다.
fcb.f_active_id- Active sector generation identifier입니다.
fcb.f_align- Underlying flash write alignment입니다.
fcb.fap- FCB가 사용하는 flash-area descriptor입니다.
fcb.f_erase_value- Erased flash byte가 갖는 value입니다.
fcb_walk_cb- Walk 중 각 valid entry를 전달받는 callback type입니다.
fcb_init- Sector metadata를 scan해 oldest와 active 위치를 복원합니다.
fcb_append- 새 record를 위한 flash location을 예약합니다.
fcb_append_finish- Payload write 뒤 checksum을 기록해 entry를 commit합니다.
fcb_walk- Oldest부터 valid entry를 순회하며 callback을 호출합니다.
fcb_getnext- 주어진 entry 다음 valid entry 또는 offset 0에서 oldest entry를 찾습니다.
fcb_rotate- Oldest sector를 erase해 free sector로 회수합니다.
fcb_append_to_scratch- Rotation 또는 copy 과정에서 scratch sector에 entry를 append합니다.
fcb_free_sector_cnt- 현재 비어 있는 sector 수를 반환합니다.
fcb_is_empty- FCB에 valid entry가 하나도 없는지 확인합니다.
fcb_offset_last_n- 끝에서 N번째 entry 위치를 찾습니다.
fcb_clear- FCB sector를 erase하고 empty state로 초기화합니다.
Source
출처
영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.