mail archive of the barebox mailing list
 help / color / mirror / Atom feed
From: Sascha Hauer <s.hauer@pengutronix.de>
To: Barebox List <barebox@lists.infradead.org>
Subject: [PATCH 23/42] state: backend: Add some documentation
Date: Fri, 31 Mar 2017 09:03:27 +0200	[thread overview]
Message-ID: <20170331070346.26878-24-s.hauer@pengutronix.de> (raw)
In-Reply-To: <20170331070346.26878-1-s.hauer@pengutronix.de>

Write some sentences to make the concepts clearer.

Signed-off-by: Sascha Hauer <s.hauer@pengutronix.de>
---
 common/state/backend_bucket_circular.c | 16 +++++++++++++++-
 common/state/backend_storage.c         | 22 ++++++++++++++++++++++
 2 files changed, 37 insertions(+), 1 deletion(-)

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;
 
 /**
-- 
2.11.0


_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

  parent reply	other threads:[~2017-03-31  7:04 UTC|newest]

Thread overview: 52+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-03-31  7:03 State patches Sascha Hauer
2017-03-31  7:03 ` [PATCH 01/42] state: Make pointing to the backend using a phandle the only supported method Sascha Hauer
2017-05-15  9:18   ` Jan Remmet
2017-05-15 10:14     ` Jan Remmet
2017-05-16  5:33       ` Sascha Hauer
2017-05-17  9:13         ` Jan Remmet
2017-03-31  7:03 ` [PATCH 02/42] state: Use positive logic Sascha Hauer
2017-03-31  7:03 ` [PATCH 03/42] state: backend: remove .get_packed_len Sascha Hauer
2017-03-31  7:03 ` [PATCH 04/42] state: backend: remove len_hint argument from state_storage_read Sascha Hauer
2017-03-31  7:03 ` [PATCH 05/42] state: Drop backend as extra struct type Sascha Hauer
2017-03-31  7:03 ` [PATCH 06/42] state: merge backend.c into state.c Sascha Hauer
2017-03-31  7:03 ` [PATCH 07/42] state: open code state_backend_init in caller Sascha Hauer
2017-03-31  7:03 ` [PATCH 08/42] state: remove unnecessary argument from state_format_init Sascha Hauer
2017-03-31  7:03 ` [PATCH 09/42] state: pass struct state * to storage functions Sascha Hauer
2017-03-31  7:03 ` [PATCH 10/42] state: storage: initialize variable once outside loop Sascha Hauer
2017-03-31  7:03 ` [PATCH 11/42] state: backend_circular: Read whole PEB Sascha Hauer
2017-04-15  8:40   ` Sam Ravnborg
2017-03-31  7:03 ` [PATCH 12/42] state: drop lazy_init Sascha Hauer
2017-03-31  7:03 ` [PATCH 13/42] state: simplify direct backend Sascha Hauer
2017-03-31  7:03 ` [PATCH 14/42] state: replace len_hint logic Sascha Hauer
2017-03-31  7:03 ` [PATCH 15/42] state: Convert all bufs to void * Sascha Hauer
2017-03-31  7:03 ` [PATCH 16/42] state: Drop cache bucket Sascha Hauer
2017-04-15  8:53   ` Sam Ravnborg
2017-04-19  8:22     ` Sascha Hauer
2017-03-31  7:03 ` [PATCH 17/42] state: backend-direct: Fix max_size Sascha Hauer
2017-03-31  7:03 ` [PATCH 18/42] state: bucket: Make output more informative Sascha Hauer
2017-03-31  7:03 ` [PATCH 19/42] state: backend_bucket_direct: max_size is always given Sascha Hauer
2017-03-31  7:03 ` [PATCH 20/42] state: backend: Add more fields to struct state_backend_storage Sascha Hauer
2017-03-31  7:03 ` [PATCH 21/42] state: backend_circular: remove unnecessary warning Sascha Hauer
2017-03-31  7:03 ` [PATCH 22/42] state: storage: direct: do not close file that is not opened Sascha Hauer
2017-03-31  7:03 ` Sascha Hauer [this message]
2017-03-31  7:03 ` [PATCH 24/42] state: backend_circular: default to circular storage Sascha Hauer
2017-03-31  7:03 ` [PATCH 25/42] state: backend_circular: rewrite function doc Sascha Hauer
2017-03-31  7:03 ` [PATCH 26/42] state: backend_storage: Rename variable nr_copies to n_buckets Sascha Hauer
2017-03-31  7:03 ` [PATCH 27/42] state: backend_storage: Rename variable desired_copies to desired_buckets Sascha Hauer
2017-03-31  7:03 ` [PATCH 28/42] state: backend_storage: rewrite function doc Sascha Hauer
2017-03-31  7:03 ` [PATCH 29/42] state: backend_storage: make locally used variable static Sascha Hauer
2017-03-31  7:03 ` [PATCH 30/42] state: backend_storage: rename more variables Sascha Hauer
2017-03-31  7:03 ` [PATCH 31/42] keystore: implement forgetting secrets Sascha Hauer
2017-03-31  7:03 ` [PATCH 32/42] commands: implement keystore command Sascha Hauer
2017-03-31  7:03 ` [PATCH 33/42] commands: state: allow loading state with -l Sascha Hauer
2017-03-31  7:03 ` [PATCH 34/42] crypto: digest: initialize earlier Sascha Hauer
2017-03-31  7:03 ` [PATCH 35/42] state: backend_raw: alloc digest only when needed Sascha Hauer
2017-03-31  7:03 ` [PATCH 36/42] state: backend_circular: Set minumum writesize to 8 Sascha Hauer
2017-03-31  7:03 ` [PATCH 37/42] state: backend bucket circular: Explain metadata Sascha Hauer
2017-03-31  7:03 ` [PATCH 38/42] state: Allow to load without authentification Sascha Hauer
2017-03-31  7:03 ` [PATCH 39/42] state: Update documentation Sascha Hauer
2017-03-31  7:03 ` [PATCH 40/42] state: Do not load state during state_new_from_node Sascha Hauer
2017-03-31  7:03 ` [PATCH 41/42] state: Remove -EUCLEAN check from userspace tool Sascha Hauer
2017-03-31  7:03 ` [PATCH 42/42] state: find device node from device path, not from device node path Sascha Hauer
2017-04-03 20:15 ` State patches Sam Ravnborg
2017-04-04  6:19   ` Sascha Hauer

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20170331070346.26878-24-s.hauer@pengutronix.de \
    --to=s.hauer@pengutronix.de \
    --cc=barebox@lists.infradead.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body. 
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox