1.. _fcb_api:
2
3Flash Circular Buffer (FCB)
4###########################
5
6Flash circular buffer provides an abstraction through which you can treat
7flash like a FIFO. You append entries to the end, and read data from the
8beginning.
9
10.. note::
11
12   As of Zephyr release 2.1 the :ref:`NVS <nvs_api>` storage API is
13   recommended over FCB for use as a back-end for the :ref:`settings API
14   <settings_api>`.
15
16Description
17***********
18
19Entries in the flash contain the length of the entry, the data within
20the entry, and checksum over the entry contents.
21
22Storage of entries in flash is done in a FIFO fashion. When you
23request space for the next entry, space is located at the end of the
24used area. When you start reading, the first entry served is the
25oldest entry in flash.
26
27Entries can be appended to the end of the area until storage space is
28exhausted. You have control over what happens next; either erase oldest
29block of data, thereby freeing up some space, or stop writing new data
30until existing data has been collected. FCB treats underlying storage as
31an array of flash sectors; when it erases old data, it does this a
32sector at a time.
33
34Entries in the flash are checksummed. That is how FCB detects whether
35writing entry to flash completed ok. It will skip over entries which
36don't have a valid checksum.
37
38Usage
39*****
40
41To add an entry to circular buffer:
42
43- Call :c:func:`fcb_append` to get the location where data can be written. If
44  this fails due to lack of space, you can call :c:func:`fcb_rotate` to erase
45  the oldest sector which will make the space. And then call
46  :c:func:`fcb_append` again.
47- Use :c:func:`flash_area_write` to write entry contents.
48- Call :c:func:`fcb_append_finish` when done. This completes the writing of the
49  entry by calculating the checksum.
50
51To read contents of the circular buffer:
52
53- Call :c:func:`fcb_walk` with a pointer to your callback function.
54- Within callback function copy in data from the entry using
55  :c:func:`flash_area_read`. You can tell when all data from within a sector
56  has been read by monitoring the returned entry's area pointer. Then you
57  can call :c:func:`fcb_rotate`, if you're done with that data.
58
59Alternatively:
60
61- Call :c:func:`fcb_getnext` with 0 in entry offset to get the pointer to
62  the oldest entry.
63- Use :c:func:`flash_area_read` to read entry contents.
64- Call :c:func:`fcb_getnext` with pointer to current entry to get the next one.
65  And so on.
66
67API Reference
68*************
69
70The FCB subsystem APIs are provided by ``fcb.h``:
71
72Data structures
73===============
74.. doxygengroup:: fcb_data_structures
75
76API functions
77=============
78.. doxygengroup:: fcb_api
79