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>
This commit is contained in:
parent
a6d44f6c8f
commit
c1864b4428
2 changed files with 75 additions and 0 deletions
74
doc/reference/storage/fcb/fcb.rst
Normal file
74
doc/reference/storage/fcb/fcb.rst
Normal file
|
@ -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
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue