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

Zephyr 3.7.0 · Storage · Append Log

Flash Circular Buffer

Flash sector를 순환하며 append-only entry를 oldest-first로 읽습니다.

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

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

Part 1

요약·해설

FCB entry layout과 incomplete-write detection, append·finish·walk·getnext·rotate 수명주기를 설명합니다.

Write

Append · finish

Read

Walk · getnext

Reclaim

Sector rotate

Part 2

접을 수 있는 영어 원문 전체

영어 원문 전체 펼치기
원문 SHA-256 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에서 건너뜁니다.

FCB append와 reclaim
fcb_appendactive sector 끝에서 entry location 예약
flash_area_write
Payloadlength · data를 flash에 기록
fcb_append_finish
Valid entrychecksum으로 완료 여부 확정
공간 부족
fcb_rotateoldest sector 단위 erase 후 재시도

Usage

Entry 추가 순서는 다음과 같습니다.

  1. fcb_append()로 write location을 얻습니다. 공간 부족이면 fcb_rotate()로 oldest sector를 erase하고 append를 다시 시도합니다.
  2. flash_area_write()로 payload를 씁니다.
  3. 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

출처

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