From b5eeaea7c9591a5e7406bbdf5578d29d62149f38 Mon Sep 17 00:00:00 2001 From: Sascha Hauer Date: Thu, 23 Mar 2017 16:30:28 +0100 Subject: state: backend: Add some documentation Write some sentences to make the concepts clearer. Signed-off-by: Sascha Hauer --- common/state/backend_bucket_circular.c | 16 +++++++++++++++- common/state/backend_storage.c | 22 ++++++++++++++++++++++ 2 files changed, 37 insertions(+), 1 deletion(-) (limited to 'common') diff --git a/common/state/backend_bucket_circular.c b/common/state/backend_bucket_circular.c index 53ee0c3f57..58fffd18e3 100644 --- a/common/state/backend_bucket_circular.c +++ b/common/state/backend_bucket_circular.c @@ -25,7 +25,21 @@ #include "state.h" - +/* + * The circular backend bucket code. The circular backend bucket is intended + * for mtd devices which need an erase operation. + * + * Erasing blocks is an operation that should be avoided. On NOR flashes erasing + * blocks is very time consuming and on NAND flashes each block only has a limited + * number of erase cycles allowed. For this reason we continuously write more data + * into each eraseblock and only erase it when no more free space is available. + * Don't confuse these multiple writes into a single eraseblock with buckets. A bucket + * is the whole eraseblock, we just happen to reuse the same bucket for storing + * new data. + * + * If your device is a mtd device, but does not have eraseblocks, like MRAMs, then + * the direct bucket is used instead. + */ struct state_backend_storage_bucket_circular { struct state_backend_storage_bucket bucket; diff --git a/common/state/backend_storage.c b/common/state/backend_storage.c index deae9c325b..f9e8151670 100644 --- a/common/state/backend_storage.c +++ b/common/state/backend_storage.c @@ -25,6 +25,28 @@ #include "state.h" +/* + * The state framework stores data in so called buckets. A bucket is + * exactly one copy of the state we want to store. On flash type media + * a bucket corresponds to a single eraseblock. On media which do not + * need an erase operation a bucket corresponds to a storage area of + * @stridesize bytes. + * + * For redundancy and to make sure that we have valid data on the storage + * device at any time the state framework stores multiple buckets. The strategy + * is as follows: + * + * When loading the state from the storage we iterate over the buckets. We + * take the first one we find which has valid crcs. The next step is to + * restore consistency between the different buckets. This means rewriting + * a bucket when it signalled it needs refresh (i.e. returned -EUCLEAN) + * or when contains data different from the bucket we use. + * + * When the state backend initialized successfully we already restored + * consistency which means all buckets contain the same data. This means + * when storing a new state we can just write all buckets in order. + */ + const unsigned int min_copies_written = 1; /** -- cgit v1.2.3