diff --git a/doc/reference/storage/fcb/fcb.rst b/doc/reference/storage/fcb/fcb.rst new file mode 100644 index 00000000000..bb42bdd731e --- /dev/null +++ b/doc/reference/storage/fcb/fcb.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 diff --git a/doc/reference/storage/index.rst b/doc/reference/storage/index.rst index 602ea3d8b0c..b4db38b6457 100644 --- a/doc/reference/storage/index.rst +++ b/doc/reference/storage/index.rst @@ -10,3 +10,4 @@ Storage nvs/nvs.rst disk/sdhc.rst flash_map/flash_map.rst + fcb/fcb.rst