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 39/42] state: Update documentation
Date: Fri, 31 Mar 2017 09:03:43 +0200	[thread overview]
Message-ID: <20170331070346.26878-40-s.hauer@pengutronix.de> (raw)
In-Reply-To: <20170331070346.26878-1-s.hauer@pengutronix.de>

- explain what buckets are
- rework text about storage backends
- explain redundancy concept

Signed-off-by: Sascha Hauer <s.hauer@pengutronix.de>
---
 Documentation/user/state.rst | 33 ++++++++++++++++++++++++++-------
 1 file changed, 26 insertions(+), 7 deletions(-)

diff --git a/Documentation/user/state.rst b/Documentation/user/state.rst
index 5dd5c486e2..73c4be8159 100644
--- a/Documentation/user/state.rst
+++ b/Documentation/user/state.rst
@@ -23,16 +23,35 @@ available, ``raw`` and ``dtb``. Both format the state data differently.
 Basically these are serializers. The raw serializer additionally supports a
 HMAC algorithm to detect manipulations.
 
+The data is always stored in a logical unit called ``bucket``. A ``bucket`` has
+its own size depending on some external contraints. These contraints are listed
+in more detail below depending on the used memory type and storage backend. A
+``bucket`` stores exactly one state. A default number of three buckets is used
+to store data redundantely.
+
+Redundancy
+----------
+
+The state framework is safe against powerfailures during write operations. To
+archieve that multiple buckets are stored to disk. When writing all buckets are
+written in order. When reading, the buckets are read in order and the first
+one found that passes CRC tests is used. When all data is read the buckets
+containing invalid or outdated data are written with the data just read. Also
+NAND blocks need cleanup due to excessive bitflips are rewritten in this step.
+With this it is made sure that after successful initialization of a state the
+data on the storage device is consistent and redundant.
+
 Storage Backends
 ----------------
 
-The serialized data can be stored to different backends which are automatically
-selected depending on the defined backend in the devicetree. Currently two
-implementations exist, ``circular`` and ``direct``. ``circular`` writes the
-data sequentially on the backend storage device. Each save is appended until
-the storage area is full. It then erases the block and starts from offset 0.
-``circular`` is used for MTD devices with erase functionality. ``direct``
-writes the data directly to the file without erasing.
+The serialized data can be stored to different backends. Currently two
+implementations exist, ``circular`` and ``direct``. The state framework automatically
+selects the correct backend depending on the storage medium. Media requiring
+erase operations (NAND, NOR flash) use the ``circular`` backend, others use the ``direct``
+backend. The purpose of the ``circular`` backend is to save erase cycles which may
+wear out the flash blocks. It continuously fills eraseblocks with updated data
+and only when an eraseblock if fully written erases it and starts over writing
+new data to the same eraseblock again.
 
 For all backends multiple copies are written to handle read errors.
 
-- 
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 ` [PATCH 23/42] state: backend: Add some documentation Sascha Hauer
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 ` Sascha Hauer [this message]
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-40-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