Skip to content
Permalink
Browse files

doc/reference: add FCB page

Added page for description FCB subsystem.
Content was ported from MyNewt.

Signed-off-by: Andrzej Puzdrowski <andrzej.puzdrowski@nordicsemi.no>
  • Loading branch information...
nvlsianpu authored and MaureenHelm committed Jul 9, 2019
1 parent a6d44f6 commit c1864b442875abd789ee2a01248336991a44eb54
Showing with 75 additions and 0 deletions.
  1. +74 −0 doc/reference/storage/fcb/fcb.rst
  2. +1 −0 doc/reference/storage/index.rst
@@ -0,0 +1,74 @@
.. _fcb-manual:

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.

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 `fcb_append` to get the location where data can be written. If
this fails due to lack of space, you can call `fcb_rotate` to erase
the oldest sector which will make the space. And then call `fcb_append`
again.
- Use `flash_area_write` to write entry contents.
- Call `fcb_append_finish` when done. This completes the writing of the
entry by calculating the checksum.

To read contents of the circular buffer:

- Call `fcb_walk` with a pointer to your callback function.
- Within callback function copy in data from the entry using
`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 `fcb_rotate`, if you're done with that data.

Alternatively:

- Call `fcb_getnext` with 0 in entry offset to get the pointer to
the oldest entry.
- Use `flash_area_read` to read entry contents.
- Call `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
:project: Zephyr

API functions
=============
.. doxygengroup:: fcb_api
:project: Zephyr
@@ -10,3 +10,4 @@ Storage
nvs/nvs.rst
disk/sdhc.rst
flash_map/flash_map.rst
fcb/fcb.rst

0 comments on commit c1864b4

Please sign in to comment.
You can’t perform that action at this time.