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>

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

doc/reference/storage/index.rst

@@ -10,3 +10,4 @@ Storage
    nvs/nvs.rst
    disk/sdhc.rst
    flash_map/flash_map.rst
+   fcb/fcb.rst