You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by ad...@apache.org on 2016/07/05 21:02:26 UTC
[2/5] incubator-mynewt-site git commit: FCB;
first take on module documentation.
FCB; first take on module documentation.
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/32d14b57
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/32d14b57
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/32d14b57
Branch: refs/heads/develop
Commit: 32d14b57cc5329a6005bf87540d1f0283335db8f
Parents: 12e0c2e
Author: Marko Kiiskila <ma...@runtime.io>
Authored: Fri Jul 1 19:20:20 2016 -0700
Committer: Marko Kiiskila <ma...@runtime.io>
Committed: Fri Jul 1 19:20:20 2016 -0700
----------------------------------------------------------------------
docs/os/modules/fcb/fcb.md | 98 +++++++++++++++++++++++
docs/os/modules/fcb/fcb_append.md | 29 +++++++
docs/os/modules/fcb/fcb_append_finish.md | 25 ++++++
docs/os/modules/fcb/fcb_append_to_scratch.md | 23 ++++++
docs/os/modules/fcb/fcb_clear.md | 23 ++++++
docs/os/modules/fcb/fcb_getnext.md | 28 +++++++
docs/os/modules/fcb/fcb_init.md | 25 ++++++
docs/os/modules/fcb/fcb_is_empty.md | 23 ++++++
docs/os/modules/fcb/fcb_offset_last_n.md | 28 +++++++
docs/os/modules/fcb/fcb_rotate.md | 22 +++++
docs/os/modules/fcb/fcb_walk.md | 32 ++++++++
mkdocs.yml | 13 +++
12 files changed, 369 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32d14b57/docs/os/modules/fcb/fcb.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/fcb/fcb.md b/docs/os/modules/fcb/fcb.md
new file mode 100644
index 0000000..a442f28
--- /dev/null
+++ b/docs/os/modules/fcb/fcb.md
@@ -0,0 +1,98 @@
+# Flash Circular Buffer (FCB)
+
+Flash circular buffer provides an abstration through which you can treat flash like a FIFO. You append entries to the end, and read data from the beginning.
+
+###Description
+
+Elements in the flash contain the lenght of the element, the data within the element, and checksum over the element contents.
+
+Storage of elements in flash is done in a FIFO fashion. When user requests space for the next element, space is located at the end of the used area. When user starts reading, the first element served is the oldest element in flash.
+
+Elements can be appended to the of the area until storage space is exhausted. User has 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.
+
+Elements in the flash are checksummed. That is how FCB detects whether writing element to flash completed ok. It will skip over entries which don't have a valid checksum.
+
+### Usage
+
+To add an element 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 make some. And then call fcb_append() again.
+* Use flash_area_write() to write element contents.
+* Call fcb_append_finish() when done. This completes 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 element using flash_area_read(). You can tell when all data from within a sector has been read by monitoring returned element's area pointer. Then you can call fcb_rotate(), if you're done with that data.
+
+Alternatively:
+* Call fcb_getnext() with 0 in element offset to get the pointer to oldest element.
+* Use flash_area_read() to read element contents.
+* Call fcb_getnext() with pointer to current element to get the next one. And so on.
+
+###Data structures
+
+This data structure describes the element location in the flash. You would use it figure out what parameters to pass to flash_area_read() to read element contents. Or to flash_area_write() when adding a new element.
+
+```c
+struct fcb_entry {
+ struct flash_area *fe_area;
+ uint32_t fe_elem_off;
+ uint32_t fe_data_off;
+ uint16_t fe_data_len;
+};
+```
+
+| Element | Description |
+|---------|-------------|
+| fe_area | Pointer to info about the flash sector. Pass this to flash_area_xx() routines. |
+| fe_elem_off | Byte offset from the start of the sector to beginning of element. |
+| fe_data_off | Byte offset from start of the sector to beginning of element data. Pass this to to flash_area_xx() routines. |
+| fe_data_len | Number of bytes in the element. |
+
+
+The following data structure describes the FCB itself. First part should be filled in by the user before calling fcb_init(). The second part is used by FCB for it's internal bookkeeping.
+```c
+struct fcb {
+ /* Caller of fcb_init fills this in */
+ uint32_t f_magic; /* As placed on the disk */
+ uint8_t f_version; /* Current version number of the data */
+ uint8_t f_sector_cnt; /* Number of elements in sector array */
+ uint8_t f_scratch_cnt; /* How many sectors should be kept empty */
+ struct flash_area *f_sectors; /* Array of sectors, must be contiguous */
+
+ /* Flash circular buffer internal state */
+ struct os_mutex f_mtx; /* Locking for accessing the FCB data */
+ struct flash_area *f_oldest;
+ struct fcb_entry f_active;
+ uint16_t f_active_id;
+ uint8_t f_align; /* writes to flash have to aligned to this */
+};
+```
+
+| Element | Description |
+|---------|-------------|
+| f_magic | Magic number in the beginning of FCB flash sector. FCB uses this when determining whether sector contains valid data or not. |
+| f_version | Current version number of the data. Also stored in flash sector header. |
+| f_sector_cnt | Number of elements it the f_sectors array. |
+| f_scratch_cnt | Number of sectors to keep empty. This can be used if you need to have scratch space for garbage collecting when FCB fills up. |
+| f_sectors | Array of entries describing flash sectors to use. |
+| f_mtx | Lock protecting access to FCBs internal data. |
+| f_oldest | Pointer to flash sector containing the oldest data. This is where data is served when read is started. |
+| f_active | Flash location where the newest data is. This is used by fcb_append() to figure out where the data should go to. |
+| f_active_id | Flash sectors are assigned ever-increasing serial number. This is how FCB figures out where oldest data is on system restart. |
+| f_align | Some flashes have restrictions on alignment for writes. FCB keeps a copy of this number for the flash here. |
+
+###List of Functions
+
+The functions available in this OS feature are:
+
+* [fcb_init](fcb_init.md)
+* [fcb_append](fcb_append.md)
+* [fcb_append_finish](fcb_append_finish.md)
+* [fcb_walk](fcb_walk.md)
+* [fcb_getnext](fcb_getnext.md)
+* [fcb_rotate](fcb_rotate.md)
+* [fcb_append_to_scratch](fcb_append_to_scratch.md)
+* [fcb_is_empty](fcb_is_empty.md)
+* [fcb_offset_last_n](fcb_offset_last_n.md)
+* [fcb_clear](fcb_clear.md)
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32d14b57/docs/os/modules/fcb/fcb_append.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/fcb/fcb_append.md b/docs/os/modules/fcb/fcb_append.md
new file mode 100644
index 0000000..b79e75a
--- /dev/null
+++ b/docs/os/modules/fcb/fcb_append.md
@@ -0,0 +1,29 @@
+## <font color="F2853F" style="font-size:24pt">fcb_append</font>
+
+```no-highlight
+int fcb_append(struct fcb *fcb, uint16_t len, struct fcb_entry *append_loc);
+```
+
+Start writing a new element to flash. This routine reserves the space in the flash by writing out the element header.
+
+When writing the contents for the entry, use append_loc->fl_area and append_loc->fl_data_off as arguments to flash_area_write(). When finished, call fcb_append_finish() with append_loc as argument.
+
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| fcb | Points to FCB where data is written to. |
+| len | Number of bytes to reserve for the element. |
+| loc | Pointer to fcb_entry. fcb_append() will fill this with info about where the element can be written to. |
+
+#### Returned values
+
+Returns 0 on success; nonzero on failure.
+FCB_ERR_NOSPACE is returned if FCB is full.
+
+#### Notes
+
+If FCB is full, you need to make more space. This can be done by calling fcb_rotate(). Or if you've reserved scratch sectors, you can take those into use by calling fcb_append_to_scratch().
+
+#### Example
+
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32d14b57/docs/os/modules/fcb/fcb_append_finish.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/fcb/fcb_append_finish.md b/docs/os/modules/fcb/fcb_append_finish.md
new file mode 100644
index 0000000..ab44e3a
--- /dev/null
+++ b/docs/os/modules/fcb/fcb_append_finish.md
@@ -0,0 +1,25 @@
+## <font color="F2853F" style="font-size:24pt">fcb_append_finish</font>
+
+```no-highlight
+int fcb_append_finish(struct fcb *fcb, struct fcb_entry *append_loc);
+```
+
+Finalizes the write of new element. FCB computes the checksum over the element and updates it in flash.
+
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| fcb | Points to FCB where data is written to. |
+| append_loc | Pointer to fcb_entry. Use the fcb_entry returned by fcb_append(). |
+
+#### Returned values
+
+Returns 0 on success; nonzero on failure.
+
+#### Notes
+
+You need to call fcb_append_finish() after writing the element contents. Otherwise FCB will consider this entry to be invalid, and skips over it when reading.
+
+#### Example
+
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32d14b57/docs/os/modules/fcb/fcb_append_to_scratch.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/fcb/fcb_append_to_scratch.md b/docs/os/modules/fcb/fcb_append_to_scratch.md
new file mode 100644
index 0000000..d23fdc1
--- /dev/null
+++ b/docs/os/modules/fcb/fcb_append_to_scratch.md
@@ -0,0 +1,23 @@
+## <font color="F2853F" style="font-size:24pt">fcb_append_to_scratch</font>
+
+```no-highlight
+int fcb_append_to_scratch(struct fcb *fcb);
+```
+
+This can be used if FCB created to have scratch block(s). Once FCB fills up with data, fcb_append() will fail. This routine can be called to start using the reserve block.
+
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| fcb | Points to FCB. |
+
+
+#### Returned values
+
+Returns 0 on success; nonzero on failure.
+
+#### Notes
+
+#### Example
+
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32d14b57/docs/os/modules/fcb/fcb_clear.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/fcb/fcb_clear.md b/docs/os/modules/fcb/fcb_clear.md
new file mode 100644
index 0000000..9e15b28
--- /dev/null
+++ b/docs/os/modules/fcb/fcb_clear.md
@@ -0,0 +1,23 @@
+## <font color="F2853F" style="font-size:24pt">fcb_clear</font>
+
+```no-highlight
+int fcb_clear(struct fcb *fcb);
+```
+
+Wipes out all data in FCB.
+
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| fcb | Points to FCB. |
+
+
+#### Returned values
+
+Returns 0 on success; non-zero otherwise.
+
+#### Notes
+
+#### Example
+
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32d14b57/docs/os/modules/fcb/fcb_getnext.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/fcb/fcb_getnext.md b/docs/os/modules/fcb/fcb_getnext.md
new file mode 100644
index 0000000..bd2b8c0
--- /dev/null
+++ b/docs/os/modules/fcb/fcb_getnext.md
@@ -0,0 +1,28 @@
+## <font color="F2853F" style="font-size:24pt">fcb_getnext</font>
+
+```no-highlight
+int fcb_getnext(struct fcb *, struct fcb_entry *loc);
+```
+
+Given element in location in loc, return with loc filled in with information about next element.
+
+If loc->le_elem_off is set to 0, fcb_getnext() will return info about the oldest element in FCB.
+
+Entry data can be read within the callback using flash_area_read(), using loc->fe_area, loc->fe_data_off, and loc->fe_data_len as arguments.
+
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| fcb | Points to FCB where data is written to. |
+| loc | Info about element. On successful call
+
+#### Returned values
+
+Returns 0 on success; nonzero on failure.
+Returns FCB_ERR_NOVAR when there are no more elements left.
+
+#### Notes
+
+#### Example
+
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32d14b57/docs/os/modules/fcb/fcb_init.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/fcb/fcb_init.md b/docs/os/modules/fcb/fcb_init.md
new file mode 100644
index 0000000..7ad76d5
--- /dev/null
+++ b/docs/os/modules/fcb/fcb_init.md
@@ -0,0 +1,25 @@
+## <font color="F2853F" style="font-size:24pt">fcb_init</font>
+
+```no-highlight
+int fcb_init(struct fcb *);
+```
+
+Initializes FCB. This function walks through the given sectors, finding out how much data already exists in the flash.
+After calling this, you can start reading/writing data from FCB.
+
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| fcb | Structure describing the FCB. |
+
+#### Returned values
+
+Returns 0 on success; nonzero on failure.
+
+#### Notes
+
+User should fill in their portion of fcb before calling this function.
+
+#### Example
+
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32d14b57/docs/os/modules/fcb/fcb_is_empty.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/fcb/fcb_is_empty.md b/docs/os/modules/fcb/fcb_is_empty.md
new file mode 100644
index 0000000..b18a598
--- /dev/null
+++ b/docs/os/modules/fcb/fcb_is_empty.md
@@ -0,0 +1,23 @@
+## <font color="F2853F" style="font-size:24pt">fcb_is_empty</font>
+
+```no-highlight
+int fcb_is_empty(struct fcb *fcb);
+```
+
+Returns 1 if there are no elements stored in FCB, otherwise returns 0.
+
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| fcb | Points to FCB. |
+
+
+#### Returned values
+
+See description.
+
+#### Notes
+
+#### Example
+
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32d14b57/docs/os/modules/fcb/fcb_offset_last_n.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/fcb/fcb_offset_last_n.md b/docs/os/modules/fcb/fcb_offset_last_n.md
new file mode 100644
index 0000000..8eebb59
--- /dev/null
+++ b/docs/os/modules/fcb/fcb_offset_last_n.md
@@ -0,0 +1,28 @@
+## <font color="F2853F" style="font-size:24pt">fcb_offset_last_n</font>
+
+```no-highlight
+int fcb_offset_last_n(struct fcb *fcb, uint8_t entries, uint32_t *last_n_off);
+```
+
+Returns the offset of n-th last element.
+
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| fcb | Points to FCB. |
+| entries | How many entries to leave. |
+| last_n_off | Returned offset. |
+
+
+#### Returned values
+
+0 on success; non-zero on failure.
+
+#### Notes
+
+Returned offset is relative to beginning of the sector where the element is.
+Therefore, n-th last element must be found within the last sector of FCB.
+
+#### Example
+
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32d14b57/docs/os/modules/fcb/fcb_rotate.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/fcb/fcb_rotate.md b/docs/os/modules/fcb/fcb_rotate.md
new file mode 100644
index 0000000..2aebbea
--- /dev/null
+++ b/docs/os/modules/fcb/fcb_rotate.md
@@ -0,0 +1,22 @@
+## <font color="F2853F" style="font-size:24pt">fcb_rotate</font>
+
+```no-highlight
+int fcb_rotate(struct fcb *fcb);
+```
+
+Erase the oldest sector in FCB.
+
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| fcb | Points to FCB. |
+
+#### Returned values
+
+Returns 0 on success; nonzero on failure.
+
+#### Notes
+
+#### Example
+
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32d14b57/docs/os/modules/fcb/fcb_walk.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/fcb/fcb_walk.md b/docs/os/modules/fcb/fcb_walk.md
new file mode 100644
index 0000000..949c6f2
--- /dev/null
+++ b/docs/os/modules/fcb/fcb_walk.md
@@ -0,0 +1,32 @@
+## <font color="F2853F" style="font-size:24pt">fcb_walk</font>
+
+```no-highlight
+typedef int (*fcb_walk_cb)(struct fcb_entry *loc, void *arg);
+
+int fcb_walk(struct fcb *fcb, struct flash_area *area, fcb_walk_cb cb,
+ void *cb_arg);
+```
+
+Walks over all log entries in FCB. Callback function cb gets called for every entry. If cb wants to stop the walk, it should return a non-zero value.
+
+If specific flash_area is specified, only entries within that sector are walked over.
+
+Entry data can be read within the callback using flash_area_read(), using loc->fe_area, loc->fe_data_off, and loc->fe_data_len as arguments.
+
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| fcb | Points to FCB where data is written to. |
+| area | Optional. Pointer to specific entry in fcb's array of sectors. |
+| cb | Callback function which gets called for every valid entry fcb_walk encounters. |
+| cb_arg | Optional. Parameter which gets passed to callback function.
+
+#### Returned values
+
+Returns 0 on success; nonzero on failure.
+
+#### Notes
+
+#### Example
+
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32d14b57/mkdocs.yml
----------------------------------------------------------------------
diff --git a/mkdocs.yml b/mkdocs.yml
index fb5261d..e361cdf 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -314,6 +314,19 @@ pages:
- 'json_encode_object_key': 'os/modules/json/json_encode_object_key.md'
- 'json_encode_object_start': 'os/modules/json/json_encode_object_start.md'
- 'json_read_object': 'os/modules/json/json_read_object.md'
+ - Flash Circular Buffer:
+ - toc: 'os/modules/fcb/fcb.md'
+ - 'Functions':
+ - 'fcb_init': 'os/modules/fcb/fcb_init.md'
+ - 'fcb_append': 'os/modules/fcb/fcb_append.md'
+ - 'fcb_append_finish': 'os/modules/fcb/fcb_append_finish.md'
+ - 'fcb_walk': 'os/modules/fcb/fcb_walk.md'
+ - 'fcb_getnext': 'os/modules/fcb/fcb_getnext.md'
+ - 'fcb_rotate': 'os/modules/fcb/fcb_rotate.md'
+ - 'fcb_append_to_scratch': 'os/modules/fcb/fcb_append_to_scratch.md'
+ - 'fcb_is_empty': 'os/modules/fcb/fcb_is_empty.md'
+ - 'fcb_offset_last_n': 'os/modules/fcb/fcb_offset_last_n.md'
+ - 'fcb_clear': 'os/modules/fcb/fcb_clear.md'
- Stats:
- toc: 'os/modules/stats/stats.md'
- Logs: