docs: rework and extend the 'state' and 'bootchooser' documentation

Many links between sections and examples were added to give the developer
the help to get it work.

Signed-off-by: Juergen Borleis <jbe@pengutronix.de>
Signed-off-by: Sascha Hauer <s.hauer@pengutronix.de>

3 files changed, 1204 insertions, 317 deletions

diff --git a/Documentation/devicetree/bindings/barebox/barebox,state.rst b/Documentation/devicetree/bindings/barebox/barebox,state.rst
index 40d7bc2e6f..4b1aade662 100644
--- a/Documentation/devicetree/bindings/barebox/barebox,state.rst
+++ b/Documentation/devicetree/bindings/barebox/barebox,state.rst
@@ -1,55 +1,89 @@
 .. _barebox,state:
 
-barebox state
+Barebox state
 =============
 
-Overview
---------
+A *state* variable set can be fully described as a devicetree based *state* node.
+This *state* node could be part of the regular platform's devicetree blob or it
+could be an extra devicetree solely for the *state*.
 
+Devicetree *state* Node
+-----------------------
 
-Boards often have the need to store variables in persistent memory.
-The constraints are often different from what the regular environment
-can do:
+A *state* node contains a description of a set of variables along with a
+place where the variable set gets stored.
 
-* compact binary format to make it suitable for small EEPROMs/MRAMs
-* atomic save/restore of the whole variable set
-* redundancy
+Required Properties
+###################
 
-``barebox,state`` is a framework to describe, access, store and
-restore a set of variables. A state variable set can be fully
-described in a devicetree node. This node could be part of the regular
-devicetree blob or it could be an extra devicetree solely for the
-state. The state variable set contains variables of different types
-and a place to store the variable set.
+* ``compatible``: should be ``barebox,state``
+* ``magic``: a 32bit number
+* ``backend``: phandle to persistent memory
+* ``backend-type``: defines the *state* variable set storage format
+* additionally a *state* node must have an alias in the ``/aliases`` node pointing
+  to it.
 
-A state node contains a description of a set of variables along with a
-place where the variables are stored.
+.. _barebox,state_magic:
 
-Required properties:
+The ``magic`` property is a unique number which identifies the *state* variable
+set's variable types and their layout. It should be kept stable as long as the
+variable types and the layout are kept stable. It should also be kept stable
+if new trailing variables are added to the existing layout to be backward
+compatible. Only if the *state* variable set's variable types and/or their layout
+change, the ``magic`` property's number must be changed to be unique again
+with the new *state* variable set's content.
 
-* ``compatible``: should be ``barebox,state``;
-* ``magic``: A 32bit number used as a magic to identify the state
-* ``backend``: contains a phandle to the device/partition which holds the
-  actual state data.
-* ``backend-type``: should be ``raw`` or ``dtb``.
-* additionally a state node must have an alias in the /aliases/ node pointing
-  to it.
+.. important:: You should not use the values 0x2354fdf3 and 0x14fa2d02 for your
+   magic value. They're already reserved by the ``direct`` and ``circular``
+   storage backends.
 
-Optional properties:
+The ``backend`` property uses the *phandle* mechanism to link the *state* to
+a real persistent memory. Refer :ref:`Backend <state_framework,backends>` for
+supported persistent memories.
 
-* ``algo``: A HMAC algorithm used to detect manipulation of the data
-  or header, sensible values follow this pattern ``hmac(<HASH>)``,
-  e.g. ``hmac(sha256)``. Only used for ``raw``.
-* ``backend-stridesize``: Maximum size per copy of the data. Only important for
-  non-MTD devices
-* ``backend-storage-type``: Normally the correct storage type is detected auto-
-  matically. The circular backend supports the option ``noncircular`` to fall
-  back to an old storage format.
+The ``backend-type`` should be ``raw`` or ``dtb``. Refer
+:ref:`Backend Types <state_framework,backend_types>` for further details.
 
-Variable nodes
---------------
+Optional Properties
+###################
 
-These are subnodes of a state node each describing a single
+* ``backend-stridesize``: stride counted in bytes. See note below.
+* ``backend-storage-type``: Defines the backend storage type to ``direct`` or
+  ``circular``. Defaults to ``circular`` for media which requires erase cycles.
+* ``algo``: A HMAC algorithm used to detect manipulation of the data
+  or header, sensible values follow this pattern ``hmac(<HASH>)``,
+  e.g. ``hmac(sha256)``. Only available for the ``backend-type`` ``raw``.
+
+.. note:: For the ``backend-storage-type`` the keyword ``noncircular`` is still
+   supported as a fall back to an old storage format. Recommendation is to not
+   use this type anymore.
+
+.. _barebox,state_backend_stridesize:
+
+The ``backend-stridesize`` is still optional but required whenever the
+underlaying backend doesn't provide an information how to pad an instance of a
+*state* variable set. This is valid for all underlaying backends which supports
+writes on a byte-by-byte manner or don't have eraseblocks (EEPROM, SRAM and NOR
+type flash backends).
+The ``backend-stridesize`` value is used by the ``direct`` backend storage type
+to place the redundant *state* variable set copies side by side in the backend.
+And it's used by the ``circular`` backend storage type to place the *state*
+variable set copies side by side into the eraseblock.
+You should calculate the ``backend-stridesize`` value very carefully based on
+the used ``backend-type``, the size of the used backend (e.g. partition size
+for example) and its eraseblock size. Refer
+:ref:`Backend Types <state_framework,backend_types>`.
+
+.. note:: It might be useful to add some spare space to the
+   ``backend-stridesize`` to ensure the ability to extend the *state* variable
+   set later on.
+
+.. _barebox,state_variable:
+
+Variable Subnodes
+-----------------
+
+These are subnodes of a *state* node each describing a single
 variable. The node name may end with ``@<ADDRESS>``, but the suffix is
 stripped from the variable name.
 
@@ -57,105 +91,161 @@ State variables have a type. Currenty supported types are: ``uint8``,
 ``uint32``, ``enum32``, ``mac`` address or ``string`` (fixed length string).
 Variable length strings are not planned.
 
-Required properties:
+Required Properties
+###################
 
 * ``reg``: Standard ``reg`` property with ``#address-cells = <1>`` and
   ``#size-cells = <1>``. Defines the ``offset`` and ``size`` of the
-  variable in the ``raw`` backend. ``size`` must fit the node
+  variable in the ``raw`` backend. ``size`` **must fit** the node
   ``type``. Variables are not allowed to overlap.
-* ``type``: Should be ``uint8``, ``uint32``, ``int32``. ``enum32``, ``mac``
+* ``type``: Should be ``uint8``, ``uint32``, ``enum32``, ``mac``
   or ``string`` for the type of the variable
-* ``names``: For ``enum32`` values only, this specifies the values
-  possible for ``enum32``.
-
-Optional properties:
-
-* ``default``: The default value if the variable cannot be read from
-  storage. For ``enum32`` values it is an integer representing an
-  offset into the names array.
-
-Example::
-
-  /aliases {
-  	state = &state;
-  };
-
-  state: state {
-  	magic = <0x27031977>;
-  	compatible = "barebox,state";
-  	backend-type = "raw";
-  	backend = <&state_part>;
-
-  	foo {
-  		reg = <0x00 0x4>;
-  		type = "uint32";
-  		default = <0x0>;
-  	};
-
-  	bar {
-  		reg = <0x10 0x4>;
-  		type = "enum32";
-  		names = "baz", "qux";
-  		default = <1>;
-  	};
-  };
-
-  &nand_flash {
-  	partitions {
-  		compatible = "fixed-partitions";
-  		#address-cells = <1>;
-  		#size-cells = <1>;
-  		state_part: state@10000 {
-  			label = "state";
-  			reg = <0x10000 0x10000>;
-  		};
-  	};
-  };
-
-Variable Types
---------------
-
-* ``uint8``:
-* ``uint32``:
-* ``int32``:
-* ``enum32``: The ``default`` value is an integer representing an
-  offset into the names array.
-* ``mac``:
-* ``string``: The length of the string excluding the trailing 0 is
-  determined by the length given in the ``reg`` property.
-
-Backends
---------
-
-Currently two backends exist. The raw backend is a very compact format
-consisting of a magic value for identification, the raw values and a
-CRC. Two copies are maintained for making sure that during update the
-storage device still contains a valid state. The dtb backend stores
-the state as a devicetree binary blob. This is exactly the original
-devicetree description of the state itself, but additionally contains
-the actual values of the variables. Unlike the raw state backend the
-dtb state backend can describe itself.
+* ``names``: For ``enum32`` values only, this specifies the possible values for
+  ``enum32``.
+
+Optional Properties
+###################
+
+* ``default``: The default value if the variable's content cannot be read from
+  the backend. For ``enum32`` values it is an integer representing an offset
+  into the names array.
+
+.. note:: Since the ``default`` property is optional, keep in mind you may need
+   a valid default value if other instances (like the bootchooser for example)
+   depends on it. Due to this, a ``default`` might be a required property instead.
+
+Variable Examples
+#################
+
+``uint8``:
+
+.. code-block:: text
+
+   uint8_example@0 {
+       reg = <0x0 0x1>;
+       type = "uint8";
+       default = <0x00>;
+   };
+
+``uint32``:
+
+.. code-block:: text
+
+   uint32_example@0 {
+       reg = <0x0 0x4>;
+       type = "uint32";
+       default = <100>;
+   };
+
+``enum32``:
+
+.. code-block:: text
+
+   enum_example@0 {
+       reg = <0x0 0x4>;
+       type = "enum32";
+       names = "value#1", "value#2";
+       default = <1>; /* selects "value#2" as the default */
+   };
+
+``mac``:
+
+.. code-block:: text
+
+   mac_example@0 {
+       reg = <0x0 0x6>;
+       type = "mac";
+   };
+
+Since a 'MAC' is a unique system identifier it makes no sense for a default
+value here. It must be set individually at run-time instead.
+
+``string``:
+
+.. code-block:: text
+
+   name {
+       reg = <0x0 0x10>;
+       type = "string";
+   };
+
+In this example the length of the string is limited to 16 characters.
+
+.. _barebox,state_hmac:
 
 HMAC
 ----
 
-With the optional property ``algo = "hmac(<HASH>)";`` a HMAC algorithm
-can be defined to detect unauthorized modification of the state's
+With the optional property ``algo = "hmac(<HASH>)";`` an HMAC algorithm
+can be defined to detect unauthorized modification of the state's variable set
 header and/or data. For this to work the HMAC and the selected hash
 algorithm have to be compiled into barebox.
 
 The shared secret for the HMAC is requested via
 ``keystore_get_secret()``, using the state's name, from the barebox
 simple keystore. It's up to the developer to populate the keystore via
-``keystore_set_secret()`` in beforehand.
+``keystore_set_secret()`` in beforehand. Refer :ref:`command_keystore` for
+further details.
+
+.. _barebox,state_setup:
+
+Configuring the *state* variable set
+------------------------------------
+
+Since the *state* variable set is intended to be shared between the bootloader
+and the kernel, the view to the *state* variable set must be the same in both
+worlds.
+
+This can be achieved by defining all *state* variable set related definitions
+inside the barebox's devicetree only. It's **not** required to keep and maintain
+the same information inside the Linux kernel's devicetree again.
+
+When barebox is instructed to load and forward a devicetree to a Linux kernel
+to be started, it "silently" copies all *state* variable set related definitions
+from its own devicetree into the Linux kernel devicetree. This way both worlds
+behave the same when *state* variable sets should be read or modified.
+
+In order to enable barebox to copy the required information to a dedicated
+location inside the Linux kernel devicetree the name of the memory node to
+store the *state* variable set must be the same in the barebox's devicetree
+and the operating system's devicetree.
+
+With this "interconnection" barebox extends the operating system's devicetree
+with:
+
+- the layout and variable definition of the *state* variable set (in case of
+  the ``raw`` backend-type)
+- the store definition (backend type, backend storage type and so on)
+- partitioning information for the persistent memory in question (on demand)
+- the connection between the backend and the memory (device, partition)
+
+Example:
+
+Lets assume the barebox's devicetree uses the name ``persistent_state_memory@01``
+to define its own *state* variable set backend.
+
+Barebox's devicetree defines:
+
+.. code-block:: text
+
+   persistent_state_memory@01 {
+       compatible = "somevalue";
+       reg = <1>;
+
+       #address-cells = <1>;
+       #size-cells = <1>;
+
+       state: partition@0 {
+            label = "state";
+            reg = <0x0 0x100>;
+       };
+   };
 
-Frontend
---------
+The operating system's devicetree defines instead:
 
-As frontend a state instance is a regular barebox device which has
-device parameters for the state variables. With this the variables can
-be accessed like normal shell variables. The ``state`` command is used
-to save/restore a state to the backend device.
+.. code-block:: text
 
-After initializing the variable can be accessed with ``$state.foo``.
-``state -s`` stores the state to eeprom.
+   persistent_state_memory@01 {
+       compatible = "somevalue";
+       reg = <1>;
+   };
diff --git a/Documentation/user/bootchooser.rst b/Documentation/user/bootchooser.rst
index cef1d4abb0..3d473b5969 100644
--- a/Documentation/user/bootchooser.rst
+++ b/Documentation/user/bootchooser.rst
@@ -1,178 +1,217 @@
+.. _bootchooser:
+
 Barebox Bootchooser
 ===================
 
 In many cases embedded systems are layed out redundantly with multiple
-kernels and multiple root file systems. The bootchooser framework provides
+kernels and multiple root file systems. The *bootchooser* framework provides
 the building blocks to model different use cases without the need to start
 from scratch over and over again.
 
-The bootchooser works on abstract boot targets, each with a set of properties
+The *bootchooser* works on abstract boot targets, each with a set of properties
 and implements an algorithm which selects the highest priority target to boot.
 
 Bootchooser Targets
 -------------------
 
-A bootchooser target represents one target that barebox can boot. It consists
+A *bootchooser* boot target represents one target that barebox can boot. It consists
 of a set of variables in the ``global.bootchooser.<targetname>`` namespace. The
-following configuration variables are needed to describe a bootchooser target:
+following configuration variables are needed to describe a *bootchooser* boot target:
 
 ``global.bootchooser.<targetname>.boot``
-  This controls what barebox actually boots for this target. This string can contain
-  anything that the :ref:`boot <command_boot>` command understands.
+  This controls what barebox actually boots for this boot target. This string can
+  contain anything that the :ref:`boot <command_boot>` command understands.
 
 ``global.bootchooser.<targetname>.default_attempts``
-  The default number of attempts that a target shall be tried starting.
+  The default number of attempts that a boot target shall be tried before skipping it.
 ``global.bootchooser.<targetname>.default_priority``
-  The default priority of a target.
+  The default priority of a boot target.
 
 
-Additionally the following runtime variables are needed. Unlinke the configuration
-variables these are automatically changed by the bootchooser algorithm:
+Additionally the following run-time variables are needed. Unlike the configuration
+variables their values are automatically updated by the *bootchooser* algorithm:
 
 ``global.bootchooser.<targetname>.priority``
-  The current priority of the target. Higher numbers have higher priorities. A priority
-  of 0 means the target is disabled and won't be started.
+  The current ``priority`` of the boot target. Higher numbers have higher priorities.
+  A ``priority`` of 0 means the boot target is disabled and won't be started.
 ``global.bootchooser.<targetname>.remaining_attempts``
-  The remaining_attempts counter. Only targets with a remaining_attempts counter > 0
-  are started.
+  The ``remaining_attempts`` counter. Only boot targets with a ``remaining_attempts``
+  counter > 0 are started.
+
+The *bootchooser* algorithm generally only starts boot targets that have a ``priority``
+> 0 and a ``remaining_attempts`` counter > 0.
 
-The bootchooser algorithm generally only starts targets that have a priority
-> 0 and a remaining_attempts counter > 0.
+.. _bootchooser,algorithm:
 
 The Bootchooser Algorithm
 -------------------------
 
-The bootchooser algorithm is very simple. It works with two variables per target
-and some optional flags. The variables are the remaining_attempts counter that
-tells how many times the target will be started. The other variable is the priority,
-the target with the highest priority will be used first, a zero priority means
-the target is disabled.
-
-When booting, bootchooser starts the target with the highest priority that has a
-nonzero remaining_attempts counter. With every start of a target the remaining
-attempts counter of this target is decremented by one. This means every targets
-remaining_attempts counter reaches zero sooner or later and the target won't be
-booted anymore. To prevent that, the remaining_attempts counter must be reset to
-its default. There are different flags in the bootchooser which control resetting
-the remaining_attempts counter, controlled by the ``global.bootchooser.reset_attempts``
-variable. It holds a list of space separated flags. Possible values are:
-
-- ``power-on``: The remaining_attempts counters of all enabled targets are reset
-  after a power-on reset (``$global.system.reset="POR"``). This means after a power
-  cycle all targets will be tried again for the configured number of retries
-- ``all-zero``: The remaining_attempts counters of all enabled targets are reset
-  when none of them has any remaining_attempts left.
-
-Additionally the remaining_attempts counter can be reset manually using the
-:ref:`command_bootchooser` command. This allows for custom conditions under which
-a system is marked as good.
+The *bootchooser* algorithm is very simple. It works with two variables per boot target
+and some optional flags. The variables are the ``remaining_attempts`` counter that
+tells how many times the boot target will be started. The other variable is the ``priority``,
+the boot target with the highest ``priority`` will be used first, a zero ``priority``
+means the boot target is disabled.
+
+When booting, *bootchooser* starts the boot target with the highest ``priority`` that
+has a non-zero ``remaining_attempts`` counter. With every start of a boot target the
+``remaining_attempts`` counter of this boot target is decremented by one. This means
+every boot target's ``remaining_attempts`` counter reaches zero sooner or later and
+the boot target won't be booted anymore. To prevent that, the ``remaining_attempts``
+counter must be reset to its default. There are different flags in the
+*bootchooser* which control resetting the ``remaining_attempts`` counter,
+controlled by the ``global.bootchooser.reset_attempts`` variable. It holds a
+list of space separated flags. Possible values are:
+
+- empty: counters will never be reset
+- ``power-on``: The ``remaining_attempts`` counters of all enabled boot targets are reset
+  after a ``power-on`` reset (``$global.system.reset="POR"``). This means after a power
+  cycle all boot targets will be tried again for the configured number of retries.
+- ``all-zero``: The ``remaining_attempts`` counters of all enabled boot targets are
+  reset when none of them has any ``remaining_attempts`` left.
+
+Additionally the ``remaining_attempts`` counter can be reset manually using the
+:ref:`bootchoser command <command_bootchooser>`. This allows for custom conditions
+under which a system is marked as good.
 In case only the booted system itself knows when it is in a good state, the
-barebox-state tool from the dt-utils_ package can be used to reset the remaining_attempts
-counter from the currently running system.
+barebox-state tool from the dt-utils_ package can be used to reset the
+``remaining_attempts`` counter from the running system.
 
 .. _dt-utils: http://git.pengutronix.de/?p=tools/dt-utils.git;a=summary
 
-Bootchooser General Options
+General Bootchooser Options
 ---------------------------
 
-Additionally to the target options described above, bootchooser has some general
-options not specific to any target.
+In addition to the boot target options described above, *bootchooser* has some general
+options not specific to any boot target.
 
 ``global.bootchooser.disable_on_zero_attempts``
-  Boolean flag. If set to 1, bootchooser disables a target (sets priority to 0) whenever
-  the remaining attempts counter reaches 0.
+  Boolean flag. If set to 1, *bootchooser* disables a boot target (sets priority
+  to 0) whenever the remaining attempts counter reaches 0.
 ``global.bootchooser.default_attempts``
-  The default number of attempts that a target shall be tried starting, used when not
-  overwritten with the target specific variable of the same name.
+  The default number of attempts that a boot target shall be tried before skipping
+  it, used when not overwritten with the boot target specific variable of the same
+  name.
 ``global.bootchooser.default_priority``
-  The default priority of a target when not overwritten with the target specific variable
-  of the same name.
+  The default priority of a boot target when not overwritten with the target
+  specific variable of the same name.
 ``global.bootchooser.reset_attempts``
-  A space separated list of events that cause bootchooser to reset the
-  remaining_attempts counters of each target that has a non zero priority. Possible values:
-
-  * empty: counters will never be reset``
-  * power-on: counters will be reset after power-on-reset
-  * all-zero: counters will be reset when all targets have zero remaining attempts
+  Already described in :ref:`Bootchooser Algorithm <bootchooser,algorithm>`
 ``global.bootchooser.reset_priorities``
-  A space separated list of events that cause bootchooser to reset the priorities of
-  all targets. Possible values:
+  A space separated list of events that cause *bootchooser* to reset the priorities of
+  all boot targets. Possible values:
 
   * empty: priorities will never be reset
-  * all-zero: priorities will be reset when all targets have zero priority
+  * ``all-zero``: priorities will be reset when all targets have zero priority
 ``global.bootchooser.retry``
-  If set to 1, bootchooser retries booting until one succeeds or no more valid targets
-  exist.
+  If set to 1, *bootchooser* retries booting until one succeeds or no more valid
+  boot targets exist.
+  Otherwise the ``boot`` command will return with an error after the first failed
+  boot target.
 ``global.bootchooser.state_prefix``
-  Variable prefix when bootchooser is used with the state framework as backend for storing
-  runtime data, see below.
+  Variable prefix when *bootchooser* is used with the *state* framework as backend
+  for storing run-time data, see below.
 ``global.bootchooser.targets``
-  Space separated list of targets that are used. For each entry in the list a corresponding
+  Space separated list of boot targets that are used. For each entry in the list
+  a corresponding
   set of ``global.bootchooser.<targetname>.<variablename>`` variables must exist.
 ``global.bootchooser.last_chosen``
-  bootchooser sets this to the target that was chosen on last boot (index).
-
-Using the State Framework as Backend for Runtime Variable Data
---------------------------------------------------------------
-
-Normally the data that is modified by the bootchooser during runtime is stored
-in global variables (backed with NV). Alternatively the :ref:`state_framework`
-can be used for this data, which allows to store this data redundantly
-and in small EEPROM spaces. See :ref:`state_framework` to setup the state framework.
-During barebox runtime each state instance will create a device
-(usually named 'state' when only one is used) with a set of parameters. Set
-``global.bootchooser.state_prefix`` to the name of the device and optionally the
-namespace inside this device. For example when your state device is called 'state'
-and inside that the 'bootchooser' namespace is used for describing the targets,
-then set ``global.bootchooser.state_prefix`` to ``state.bootchooser``.
+  *bootchooser* sets this to the boot target that was chosen on last boot (index).
 
-Example
--------
+.. _bootchooser,setup_example:
+
+Setup Example
+-------------
+
+We want to set up a redundant machine with two bootable systems within one shared
+memory, here a NAND type flash memory with a UBI partition. We have a 512 MiB NAND
+type flash, to be used only for the root filesystem. The devicetree doesn't
+define any partition, because we want to run one UBI partition with two volumens
+for the redundant root filesystems on this flash memory.
+
+.. code-block:: text
 
-The following example shows how to initialize two targets, 'system0' and 'system1'.
-Both boot from an UBIFS on nand0, the former has a priority of 21 and boots from
-the volume 'system0' whereas the latter has a priority of 20 and boots from
-the volume 'system1'.
+   nand@0 {
+      [...]
+   };
+
+In order to configure this machine the following steps can be used:
 
 .. code-block:: sh
 
-  # initialize target 'system0'
-  nv bootchooser.system0.boot=nand0.ubi.system0
-  nv bootchooser.system0.default_attempts=3
-  nv bootchooser.system0.default_priority=21
+   ubiformat /dev/nand0 -y
+   ubiattach /dev/nand0
+   ubimkvol /dev/nand0.ubi root_filesystem_1 256MiB
+   ubimkvol /dev/nand0.ubi root_filesystem_2 0
+
+The last command creates a volume which fills the remaining available space
+on the NAND type flash memory, which will be most of the time smaller than
+256 MiB due to factory bad blocks and lost data blocks for UBI's management.
+
+After this preparation we can find two devices in ``/dev``:
+
+- ``nand0.ubi.root_filesystem_1``
+- ``nand0.ubi.root_filesystem_2``
+
+These two devices can now be populated with their filesystem content. In our
+example here we additionally assume, that these root filesystems contain a Linux
+kernel with its corresponding devicetree via boot spec (refer to
+:ref:`Bootloader Spec <bootloader_spec>` for further details).
+
+Either device can be booted with the :ref:`boot <command_boot>` command command,
+and thus can be used by the *bootchooser* and we can start to configure the
+*bootchooser* variables.
+
+The following example shows how to initialize two boot targets, ``system1`` and
+``system2``. Both boot from a UBIFS on ``nand0``, the former has a priority of
+21 and boots from the volume ``root_filesystem_1`` whereas the latter has a
+priority of 20 and boots from the volume ``root_filesystem_2``.
+
+.. code-block:: sh
 
   # initialize target 'system1'
-  nv bootchooser.system1.boot=nand0.ubi.system1
+  nv bootchooser.system1.boot=nand0.ubi.root_filesystem_1
   nv bootchooser.system1.default_attempts=3
-  nv bootchooser.system1.default_priority=20
+  nv bootchooser.system1.default_priority=21
+
+  # initialize target 'system2'
+  nv bootchooser.system2.boot=nand0.ubi.root_filesystem_2
+  nv bootchooser.system2.default_attempts=3
+  nv bootchooser.system2.default_priority=20
 
   # make targets known
-  nv bootchooser.targets="system0 system1"
+  nv bootchooser.targets="system1 system2"
 
   # retry until one target succeeds
-  nv bootchooser.retry="true"
+  nv bootchooser.retry=1
 
   # First try bootchooser, when no targets remain boot from network
   nv boot.default="bootchooser net"
 
-Note that this example is for testing, normally the NV variables would be
-initialized directly by files in the default environment, not with a script.
+.. note:: This example is for testing only, normally the NV variables would be
+   initialized directly by files in the default environment, not with a script.
+
+The run-time values are stored in environment variables as well. Alternatively,
+they can be stored in a *state* variable set instead. Refer to
+:ref:`using the state framework <bootchooser,state_framework>` for further
+details.
 
 Scenarios
 ---------
 
-This section describes some scenarios that can be solved with bootchooser. All
-scenarios assume multiple slots that can be booted, where 'multiple' is anything
-higher than one.
+This section describes some scenarios that can be handled by bootchooser. All
+scenarios assume multiple boot targets that can be booted, where 'multiple' is
+anything higher than one.
 
 Scenario 1
 ##########
 
-A system that shall always boot without user interaction. Staying in the bootloader
-is not an option. In this scenario a target is started for the configured number
-of remaining attempts. If it cannot successfully be started, the next target is chosen.
-This happens until no targets are left to start, then all remaining attempts are
-reset to their defaults and the first target is tried again.
+- a system that shall always boot without user interaction
+- staying in the bootloader is not an option.
+
+In this scenario a boot target is started for the configured number of remaining
+attempts. If it cannot be started successfully, the next boot target is chosen.
+This repeats until no boot targets are left to start, then all remaining attempts
+are reset to their defaults and the first boot target is tried again.
 
 Settings
 ^^^^^^^^
@@ -186,22 +225,26 @@ Settings
 Deployment
 ^^^^^^^^^^
 
-#. barebox or flash robot fills all slots with valid systems.
-#. The all-zero settings will lead to automatically enabling the slots, no
-   default settings are needed here.
+#. barebox or flash robot fills all boot targets with valid systems.
+#. The all-zero settings will lead to automatically enabling the boot targets,
+   no default settings are needed here.
 
 Recovery
 ^^^^^^^^
 
-Recovery will only be called when all targets are not startable (That is, no valid
-Kernel found or read failure). Once a target is startable (A valid kernel is found
-and started) Bootchooser will never fall through to the recovery target.
+Recovery will only be called when all boot targets are not startable (That is,
+no valid kernel found or read failure). Once a boot target is startable (a
+valid kernel is found and started) *bootchooser* will never fall through to
+the recovery boot target.
 
 Scenario 2
 ##########
 
-A system with multiple slots, a slot that was booted three times without success
-shall never be booted again (except after update or user interaction).
+- a system with multiple boot targets
+- one recovery system
+
+A boot target that was booted three times without success shall never be booted
+again (except after update or user interaction).
 
 Settings
 ^^^^^^^^
@@ -216,23 +259,27 @@ Settings
 Deployment
 ^^^^^^^^^^
 
-#. barebox or flash robot fills all slots with valid systems.
-#. barebox or flash robot marks slots as good or state contains non zero
+#. barebox or flash robot fills all boot targets with valid systems.
+#. barebox or flash robot marks boot targets as good or *state* contains non zero
    defaults for the remaining_attempts/priorities.
 
 Recovery
 ^^^^^^^^
-done by 'recovery' boot target which is booted after the bootchooser falls through due to
-the lack of bootable targets. This target can be:
 
-- A system that will be booted as recovery.
-- A barebox script that will be started.
+Done by 'recovery' boot target which is booted after the *bootchooser* falls
+through due to the lack of bootable targets. This boot target can be:
+
+- a system that will be booted as recovery.
+- a barebox script that will be started.
 
 Scenario 3
 ##########
 
-A system with multiple slots and one recovery system. Booting a slot three times
-without success disables it. A power cycle shall not be counted as failed boot.
+- a system with multiple boot targets
+- one recovery system
+- a power cycle shall not be counted as failed boot.
+
+Booting a boot target three times without success disables it.
 
 Settings
 ^^^^^^^^
@@ -247,33 +294,205 @@ Settings
 Deployment
 ^^^^^^^^^^
 
-#. barebox or flash robot fills all slots with valid systems.
-#. barebox or flash robot marks slots as good.
+#. barebox or flash robot fills all boot targets with valid systems.
+#. barebox or flash robot marks boot targets as good.
 
 Recovery
 ^^^^^^^^
 
-Done by 'recovery' boot target which is booted after the bootchooser falls through
-due to the lack of bootable targets. This target can be:
+Done by 'recovery' boot target which is booted after the *bootchooser* falls
+through due to the lack of bootable targets. This target can be:
+
+- a system that will be booted as recovery.
+- a barebox script that will be started.
 
-- A system that will be booted as recovery.
-- A barebox script that will be started.
+.. _bootchooser,state_framework:
+
+Using the *State* Framework as Backend for Run-Time Variable Data
+-----------------------------------------------------------------
+
+Usually the *bootchooser* modifies its data in global variables which are
+connected to :ref:`non volatile variables <config_device>`.
+
+Alternatively the :ref:`state_framework` can be used for this data, which
+allows to store this data redundantly in some kind of persistent memory.
+
+In order to let the *bootchooser* use the *state* framework for its storage
+backend, configure the ``bootchooser.state_prefix`` variable with the *state*
+variable set instance name.
+
+Usually a generic *state* variable set in the devicetree is defined like this
+(refer to :ref:`barebox,state` for more details):
+
+.. code-block:: text
+
+   some_kind_of_state {
+      [...]
+   };
+
+At barebox run-time this will result in a *state* variable set instance called
+*some_kind_of_state*. You can also store variables unrelated to *bootchooser* (a
+serial number, MAC address, …) in it.
+
+Extending this *state* variable set by information required by the *bootchooser*
+is simply done by adding so called 'boot targets' and optionally one ``last_chosen``
+node. It then looks like:
+
+.. code-block:: text
+
+   some_kind_of_state {
+     [...]
+     boot_target_1 {
+         [...]
+     };
+     boot_target_2 {
+         [...]
+     };
+   };
+
+It could makes sense to store the result of the last *bootchooser* operation
+in the *state* variable set as well. In order to do so, add a node with the name
+``last_chosen`` to the *state* variable set. *bootchooser* will use it if present.
+The *state' variable set definition then looks like:
+
+.. code-block:: text
+
+   some_kind_of_state {
+     [...]
+     boot_target_1 {
+         [...]
+     };
+     boot_target_2 {
+         [...]
+     };
+     last_chosen {
+         reg = <offset 0x4>;
+         type = "uint32";
+     };
+   };
+
+The ``boot_target_*`` names shown above aren't variables themselves (like the other
+variables in the *state* variable set), they are named containers instead, which
+are used to group variables specific to *bootchooser*.
+
+A 'boot target' container has the following fixed content:
+
+.. code-block:: text
+
+   some_boot_target {
+          #address-cells = <1>;
+          #size-cells = <1>;
+
+          remaining_attempts {
+              [...]
+              default = <some value>; /* -> read note below */
+          };
+
+          priority {
+              [...]
+              default = <some value>; /* -> read note below */
+          };
+   };
+
+.. important:: Since each variable in a *state* variable set requires a ``reg``
+   property, the value of its ``reg`` property must be unique, e.g. the offsets
+   must be consecutive from a global point of view, as they describe the
+   storage layout in the backend memory.
+
+So, ``remaining_attempts`` and ``priority`` are required variable nodes and are
+used to setup the corresponding run-time environment variables in the
+``global.bootchooser.<targetname>`` namespace.
+
+.. important:: It is important to provide a ``default`` value for each variable
+   for the case when the *state* variable set backend memory is uninitialized.
+   This is also true if default values through the *bootchooser's* environment
+   variables are defined (e.g. ``bootchooser.default_attempts``,
+   ``bootchooser.default_priority`` and their corresponding boot target specific
+   variables). The former ones are forwarded to the *bootchooser* to make a
+   decision, the latter ones are used by the *bootchooser* to make a decision
+   the next time.
+
+Example
+#######
+
+For this example we use the same system and its setup described in
+:ref:`setup example <bootchooser,setup_example>`. The resulting devicetree
+content for the *state* variable set looks like:
+
+.. code-block:: text
+
+   system_state {
+        [...]
+        system1 {
+             #address-cells = <1>;
+             #size-cells = <1>;
+             remaining_attempts@0 {
+                 reg = <0x0 0x4>;
+                 type = "uint32";
+                 default = <3>;
+             };
+             priority@4 {
+                 reg = <0x4 0x4>;
+                 type = "uint32";
+                 default = <20>;
+             };
+        };
+
+        system2 {
+             #address-cells = <1>;
+             #size-cells = <1>;
+             remaining_attempts@8 {
+                 reg = <0x8 0x4>;
+                 type = "uint32";
+                 default = <3>;
+             };
+             priority@c {
+                 reg = <0xc 0x4>;
+                 type = "uint32";
+                 default = <21>;
+             };
+        };
+
+        last_chosen@10 {
+             reg = <0x10 0x4>;
+             type = "uint32";
+        };
+   };
+
+.. important:: While the ``system1/2`` nodes suggest a different namespace inside the
+   *state* variable set, the actual variable's ``reg``-properties and their offset
+   part are always relative to the whole *state* variable set and thus must be
+   consecutive globally.
+
+To make *bootchooser* use the so called ``system_state`` *state* variable set
+instead of the NV run-time environment variables, we just set:
+
+.. code-block:: text
+
+   global.bootchooser.state_prefix=system_state
+
+.. note:: Its a good idea to keep the ``bootchooser.<targetname>.default_priority``
+   and ``bootchooser.<targetname>.default_attempts`` values in sync with the
+   corresponding default values in the devicetree.
 
 Updating systems
 ----------------
 
-Updating a slot is the same among the different scenarios. It is assumed that the
-update is done under a running Linux system which can be one of the regular bootchooser
-slots or a dedicated recovery system. For the regular slots updating is done like:
-
-- Set the priority of the inactive slot to 0.
-- Update the inactive slot.
-- Set priority of the inactive slot to a higher value than the active slot.
-- Set remaining_attempts of the inactive slot to nonzero.
+Updating a boot target is the same among the different scenarios. It is assumed
+that the update is done under a running Linux system which can be one of the
+regular *bootchooser* boot targets or a dedicated recovery system. For the
+regular *bootchooser* boot targets updating is done like:
+
+- Disable the inactive (e.g. not used right now) boot target by setting its
+  ``priority`` to 0.
+- Update the inactive boot target.
+- Set ``remaining_attempts`` of the inactive boot target to nonzero.
+- Enable the inactive boot target by setting its ``priority`` to a higher value
+  than any other boot target (including the used one right now).
 - Reboot.
-- If necessary update the now inactive, not yet updated slot the same way.
+- If necessary update the now inactive, not yet updated boot target the same way.
 
-One way of updating systems is using RAUC_ which integrates well with the bootchooser
+One way of updating systems is using RAUC_ which integrates well with the *bootchooser*
 in barebox.
 
-.. _RAUC: https://rauc.readthedocs.io/en/latest/ RAUC (
+.. _RAUC: https://rauc.readthedocs.io/en/latest/
diff --git a/Documentation/user/state.rst b/Documentation/user/state.rst
index 73c4be8159..7d6c5770d5 100644
--- a/Documentation/user/state.rst
+++ b/Documentation/user/state.rst
@@ -3,65 +3,643 @@
 Barebox State Framework
 =======================
 
-The state framework is build to exchange data between Barebox and Linux
-userspace using a non-volatile storage. There are several components involved.
-Barebox has a state driver to access the variables. For the Linux Userspace
-there is a userspace tool.
-
-Devicetree
-----------
-
-Currently the devicetree defines the layout of the variables and data.
-Variables are fixed size. Several types are supported, see the binding
-documentation for details.
-
-Data Formats
-------------
-
-The state data can be stored in different ways. Currently two formats are
-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. 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.
-
-Commands
+Boards often have the need to store variable sets in persistent memory. barebox
+could handle that with its regular environment. But the constraints for such a
+variable set are often different from what the regular environment can do:
+
+* compact binary format to make it suitable for small non-volatile memories
+* atomic save/restore of the whole variable set
+* redundancy
+
+*state* is a framework to describe, access, store and restore a set of variables
+and is prepared to exchange/share data between barebox and Linux userspace using
+some kind of persistent memory.
+
+Already known users of the *state* information are the :ref:`bootchooser` and
+RAUC_.
+
+.. _RAUC: https://rauc.readthedocs.io/en/latest/
+
+barebox itself uses a *state* driver to access the variables in the
+persistent memory. For the Linux run-time there is a userspace tool_ to do
+the same.
+
+.. _tool: https://git.pengutronix.de/cgit/tools/dt-utils/
+
+To define a *state* variable set, a devicetree based description is used. Refer to
+:ref:`barebox,state` for further details.
+
+There are several software components involved, which are described in this
+section.
+
+.. _state_framework,backends:
+
+Backends (e.g. Supported Memory Types)
+--------------------------------------
+
+Some non-volatile memory is need for storing a *state* variable set:
+
+- all kinds of NOR flash memories
+- all kinds of NAND flash memories
+- MRAM
+- EEPROM
+- all kind of SRAMs (backup battery assumed)
+
+For classic MTDs (NOR/NAND/SRAM), a partition is required and understood by
+the Linux kernel as well to define the location inside the device where to store
+the *state* variable set. For non-MTDs (MRAM/EEPROM) a different approach is
+required to define the location where to store the *state* variable set.
+
+.. _state_framework,backend_types:
+
+Backend-Types (e.g. *state* storage format)
+-------------------------------------------
+
+The *state* variable set itself can be stored in different ways. Currently two
+formats are available, ``raw`` and ``dtb``.
+
+Both serialize the *state* variable set differently.
+
+.. note:: The ``raw`` serializer additionally supports an HMAC algorithm to
+   detect manipulations. Refer to :ref:`HMAC <barebox,state_hmac>` for further
+   details.
+
+.. _state_framework,raw:
+
+The ``raw`` *state* storage format
+##################################
+
+``raw`` means the *state* variable set is a simple binary data blob only. In
+order to handle it, the *state* framework puts a management header in front of
+the binary data blob with the following content and layout:
+
+ +---------+---------+---------------------------------------------------+
+ | Offset  |   Size  |    Content                                        |
+ +---------+---------+---------------------------------------------------+
+ |  0x00   | 4 bytes | 'magic value'                                     |
+ +---------+---------+---------------------------------------------------+
+ |  0x04   | 2 bytes | reserved, filled with zero bits                   |
+ +---------+---------+---------------------------------------------------+
+ |  0x06   | 2 bytes | byte count of binary data blob                    |
+ +---------+---------+---------------------------------------------------+
+ |  0x08   | 4 bytes | CRC32 of binary data blob (offset 0x10...)        |
+ +---------+---------+---------------------------------------------------+
+ |  0x0c   | 4 bytes | CRC32 of header (offset 0x00...0x0b)              |
+ +---------+---------+---------------------------------------------------+
+ | 0x10... |         | binary data blob                                  |
+ +---------+---------+---------------------------------------------------+
+
+- 'magic value' is an unsigned value with native endianness, refer to
+  :ref:`'magic' property <barebox,state_magic>` about its value.
+- 'byte count' is an unsigned value with native endianness
+- 'binary data blob CRC32' is an unsigned value with native endianness
+- 'header CRC32' is an unsigned value with native endianness
+
+.. note:: the 32-bit CRC calculation uses the polynomial:
+
+  x^32+x^26+x^23+x^22+x^16+x^12+x^11+x^10+x^8+x^7+x^5+x^4+x^2+x+1
+
+Since the binary data blob has no built-in description of the embedded *state*
+variable set, it depends on an external layout definition to encode
+and decode it correctly. A devicetree based description is used to describe the
+embedded *state* variable set. Refer to
+:ref:`Variable Subnodes <barebox,state_variable>` for further details.
+
+.. important:: It is important to share this layout definition in all
+   'worlds' which want to read or manipulate the *state* variable set. This
+   includes offsets, sizes and endianesses of the binary data. Refer to
+   :ref:`Configuring the state variable set <barebox,state_setup>` on how to
+   setup barebox to ensure this is done automatically for devicetree based
+   operating systems.
+
+.. note:: When calculating the ``backend-stridesize`` take the header overhead
+   into account. The header overhead is always 16 bytes.
+
+.. _state_framework,dtb:
+
+The ``dtb`` *state* storage format
+##################################
+
+.. note:: The ``dtb`` backend type isn't well tested. Use the ``raw`` backend
+          when in doubt.
+
+The ``dtb`` backend type stores the *state* variable set as a devicetree binary
+blob. This is exactly the original devicetree description of the *state* variable
+set itself, but additionally contains the actual values of the variable set.
+Unlike the ``raw`` *state* backend the ``dtb`` *state* backend can describe itself.
+
+.. _state_framework,backend_storage_type:
+
+Backend Storage Types (e.g. media storage layout)
+-------------------------------------------------
+
+The serialized data (``raw`` or ``dtb``) can be stored to different backend
+storage types. These types are dedicated to different memory types.
+
+Currently two backend storage type implementations do exist, ``circular`` and
+``direct``.
+
+The state framework can select the correct backend storage type depending on the
+backend medium. Media requiring erase operations (NAND, NOR flash) defaults to
+the ``circular`` backend storage type automatically. In contrast EEPROMs and
+RAMs are candidates for the ``direct`` backend storage type.
+
+Direct Storage Backend
+######################
+
+This kind of backend storage type is intended to be used with persistent RAMs or
+EEPROMs.
+These media are characterized by:
+
+- memory cells can be simply written at any time (no previous erase required)
+- memory cells can be written as often as required (unlimted or very high endurance)
+- can be written on a byte-by-byte manner
+
+Example: MRAM with 64 bytes at device's offset 0:
+
+.. code-block:: text
+
+    0                                                                 0x3f
+    +-------------------------------------------------------------------+
+    |                                                                   |
+    +-------------------------------------------------------------------+
+
+Writing the *state* variable set always happens at the same offset:
+
+.. code-block:: text
+
+    0                                                                 0x3f
+    +-------------------------------------------+-----------------------+
+    |                 copy                      |                       |
+    +-------------------------------------------+-----------------------+
+
+.. important:: The ``direct`` storage backend needs 8 bytes of additional space
+   per *state* variable set for its meta data.
+
+Circular Storage Backend
+########################
+
+This kind of backend storage type is intended to be used with regular flash memory devices.
+
+Flash memories are characterized by:
+
+- only erased memory cells can be written with new data
+- written data cannot be written twice (at least not for modern flash devices)
+- erase can happen on eraseblock sizes only (detectable, physical value)
+- an eraseblock only supports a limited number of write-erase-cycles (as low as a few thousand cycles)
+
+The purpose of the ``circular`` backend storage type is to save erase cycles
+which may wear out the flash's eraseblocks. This type instead incrementally fills
+an eraseblock with updated data and only when an eraseblock
+is fully written, it erases it and starts over writing new data to the same
+eraseblock again.
+
+**NOR type flash memory is additionally characterized by**
+
+- can be written on a byte-by-byte manner
+
+.. _state_framework,nor:
+
+Example: NOR type flash memory with 64 kiB eraseblock size
+
+.. code-block:: text
+
+    0                                                                0x0ffff
+    +--------------------------------------------------------------------+
+    |                                                                    |
+    +--------------------------------------------------------------------+
+    |<--------------------------- eraseblock --------------------------->|
+
+Writing the *state* variable set the very first time:
+
+.. code-block:: text
+
+    0
+    +------------+------------
+    |   copy     |
+    |    #1      |
+    +------------+------------
+    |<- stride ->|
+    |<---- eraseblock -------
+
+'copy#1' will be used.
+
+Changing the *state* variable set the first time (e.g. writing it the second time):
+
+.. code-block:: text
+
+    0
+    +------------+------------+------------
+    |   copy     |   copy     |
+    |    #1      |    #2      |
+    +------------+------------+------------
+    |<- stride ->|<- stride ->|
+    |<------------- eraseblock -----------
+
+'copy#2' will now be used and 'copy#1' will be ignored.
+
+Changing the *state* variable set the n-th time:
+
+.. code-block:: text
+
+    0                                                                0x0ffff
+    +------------+------------+-------- -------+------------+------------+
+    |   copy     |   copy     |                |    copy    |   copy     |
+    |    #1      |    #2      |                |    #n-1    |    #n      |
+    +------------+------------+-------- -------+------------+------------+
+    |<- stride ->|<- stride ->|                |<- stride ->|<- stride ->|
+    |<---------------------------- eraseblock -------------------------->|
+
+'copy#n' will now be used and all other copies will be ignored.
+
+The next time the *state* variable set changes again, the whole block will be
+erased and the *state* variable set gets stored at the first position inside
+the eraseblock again. This reduces the need for a flash memory erase by factors.
+
+**NAND type flash memory is additionally characterized by**
+
+- organized in pages (size is a detectable, physical value)
+- writes can only happen in multiples of the page size (which much less than the eraseblock size)
+- partially writing a page can be limited in count or be entirely forbidden (in
+  the case of *MLC* NANDs)
+
+Example: NAND type flash memory with 128 kiB eraseblock size and 2 kiB page
+size and a 2 kiB write size
+
+.. code-block:: text
+
+    0                                                             0x20000
+    +------+------+------+------+---- ----+------+------+------+------+
+    | page | page | page | page |         | page | page | page | page |
+    |  #1  |  #2  |  #3  |  #4  |         | #61  | #62  | #63  | #64  |
+    +------+------+------+------+---- ----+------+------+------+------+
+    |<-------------------------- eraseblock ------------------------->|
+
+Writing the *state* variable set the very first time:
+
+.. code-block:: text
+
+    |<--- page #1---->|
+    +-------+---------+--
+    | copy  |         |
+    |  #1   |         |
+    +-------+---------+--
+    |<---- eraseblock ---
+
+'copy#1' will be used.
+
+Changing the *state* variable set the first time (e.g. writing it the second time):
+
+.. code-block:: text
+
+    |<-- page #1 -->|<-- page #2 -->|
+    +-------+-------+-------+-------+----
+    | copy  |       | copy  |       |
+    |  #1   |       |  #2   |       |
+    +-------+-------+-------+-------+----
+    |<--------- eraseblock --------------
+
+'copy#2' will now be used and 'copy#1' will be ignored.
+
+Changing the *state* variable set the 64th time:
+
+.. code-block:: text
+
+    |<-- page #1 -->|<-- page #2 -->|        |<- page #63 -->|<- page #64 -->|
+    +-------+-------+-------+-------+--    --+-------+-------+-------+-------+
+    | copy  |       | copy  |       |        | copy  |       | copy  |       |
+    |  #1   |       |  #2   |       |        |  #63  |       |  #64  |       |
+    +-------+-------+-------+-------+--    --+-------+-------+-------+-------+
+    |<----------------------------- eraseblock ----------------------------->|
+
+'copy#n' will now be used and all other copies will be ignored.
+
+The next time the *state* variable set changes again, the eraseblock will be
+erased and the *state* variable set gets stored at the first position inside
+the eraseblock again. This significantly reduces the need for a block erases.
+
+.. important:: One copy of the *state* variable set is limited to the page size
+   of the used backend (e.g. NAND type flash memory)
+
+Redundant *state* variable set copies
+-------------------------------------
+
+To avoid data loss when changing the *state* variable set, more than one
+*state* variable set copy can be stored into the backend. Whenever the *state*
+variable set changes, only one *state* variable set copy gets changed at a time.
+In the case of an interruption and/or power loss resulting into an incomplete
+write to the backend, the system can fall back to a different *state* variable
+set copy (previous *state* variable set).
+
+Direct Storage Backend Redundancy
+#################################
+
+For this kind of backend storage type a value for the stride size must be
+defined by the developer (refer to
+:ref:`backend-stridesize <barebox,state_backend_stridesize>`).
+
+It always stores **three** redundant copies of the backend-type. Keep this in
+mind when calculating the stride size and defining the backend size (e.g. the
+size of a partition).
+
+.. code-block:: text
+
+    +----------------+------+----------------+------+----------------+------+
+    | redundant copy | free | redundant copy | free | redundant copy | free |
+    +----------------+------+----------------+------+----------------+------+
+    |<---- stride size ---->|<---- stride size ---->|<---- stride size ---->|
+
+.. important:: The ``direct`` storage backend needs 8 bytes of additional space
+   per *state* variable set for its meta data. Keep this in mind when calculating
+   the stridesize. For example, if your variable set needs 8 bytes, the ``raw``
+   header needs 16 bytes and the ``direct`` storage backend additionally 8 bytes.
+   The full space for one *state* variable set is now 8 + 16 + 8 = 32 bytes.
+
+Circular Storage Backend Redundancy
+###################################
+
+**NOR type flash memory**
+
+Redundant copies of the *state* variable set are stored based on the memory's
+eraseblocks and this size is automatically detected at run-time.
+It needs a stride size as well, because a NOR type flash memory can be written
+on a byte-by-byte manner.
+In contrast to the ``direct`` storage backend redundancy, the
+stride size for the ``circular`` storage backend redundancy defines the
+side-by-side location of the *state* variable set copies.
+
+.. code-block:: text
+
+    |<X>|<X>|...
+    +--------------------------------+--------------------------------+--
+    |C#1|C#2|C#3|C#4|C#5|            |C#1|C#2|C#3|C#4|C#5|            |
+    +--------------------------------+--------------------------------+--
+    |<--------- eraseblock --------->|<--------- eraseblock --------->|<-
+    |<------- redundant area ------->|<------- redundant area ------->|<-
+
+*<X>* defines the stride size, *C#1*, *C#2* the *state* variable set copies.
+
+Since these kinds of MTD devices are partitioned, its a good practice to always
+reserve multiple eraseblocks for the barebox's *state* feature. Keep in mind:
+Even NOR type flash memories can be worn out.
+
+**NAND type flash memory**
+
+Redundant copies of the *state* variable set are stored based on the memory's
+eraseblocks and this size is automatically detected at run-time.
+
+.. code-block:: text
+
+    +------+------+--- ---+------+------+------+------+--- ---+------+------+--
+    | copy | copy |       | copy | copy | copy | copy |       | copy | copy |
+    |  #1  |  #2  |       | #63  | #64  |  #1  |  #2  |       | #63  | #64  |
+    +------+------+--- ---+------+------+------+------+--- ---+------+------+--
+    |<----------- eraseblock ---------->|<----------- eraseblock ---------->|<-
+    |<-------- redundant area --------->|<-------- redundant area --------->|<-
+
+Since these kinds of MTD devices are partitioned, its a good practice to always
+reserve multiple eraseblocks for the barebox's *state* feature. Keep in mind:
+NAND type flash memories can be worn out, factory bad blocks can exist from the
+beginning.
+
+Handling of Bad Blocks
+----------------------
+
+NAND type flash memory can have factory bad eraseblocks and more bad
+eraseblocks can appear over the life time of the memory. They are detected by
+the MTD layer, marked as bad and never used again.
+
+.. important:: If NAND type flash memory should be used as a backend, at least
+   three eraseblocks are used to keep three redundant copies of the *state*
+   variable set. You should add some spare eraseblocks to the backend
+   partition by increasing the partition's size to a suitable value to handle
+   factory bad eraseblocks and worn-out eraseblocks.
+
+Examples
+--------
+
+The following examples intends to show how to setup and interconnect all
+required components for various non-volatile memories.
+
+All examples use just one *state* variable of type *uint8* named ``variable``
+to keep them simple. For the ``raw`` backend-type it means one *state*
+variable set has a size of 17 bytes (16 bytes header plus one byte variables).
+
+.. note:: The mentioned ``aliases`` and the *state* variable set node entries
+   are members of the devicetree's root node.
+
+.. note:: For a more detailed description of the used *state* variable set
+   properties here, refer to :ref:`barebox,state`.
+
+NOR flash memories
+##################
+
+This type of memory can be written on a single byte/word basis (depending on its bus
+width), but must be erased prior writing the same byte/word again and erasing
+must happen on an eraseblock basis. Typical eraseblock sizes are 128 kiB or
+(much) larger for parallel NOR flashes and 4 kiB or larger for serial NOR
+flashes.
+
+From the Linux kernel perspective this type of memory is a *Memory Technologie
+Device* (aka 'MTD') and handled by barebox in the same manner. It needs a
+partition configuration.
+
+The following devicetree node entry defines some kind of NOR flash memory and
+a partition at a specific offset to be used as the backend for the
+*state* variable set.
+
+.. code-block:: text
+
+	norflash@0 {
+		backend_state_nor: partition@120000 {
+			[...]
+		};
+	};
+
+With this 'backend' definition its possible to define the *state* variable set
+content, its backend-type and *state* variable set layout.
+
+.. code-block:: text
+
+	aliases {
+		state = &state_nor;
+	};
+
+	state_nor: nor_state_memory {
+		#address-cells = <1>;
+		#size-cells = <1>;
+		compatible = "barebox,state";
+		magic = <0x512890a0>;
+		backend-type = "raw";
+		backend = <&backend_state_nor>;
+		backend-storage-type = "circular";
+		backend-stridesize = <32>;
+
+		variable {
+			reg = <0x0 0x1>;
+			type ="uint8";
+			default = <0x1>;
+		};
+	};
+
+NAND flash memories
+###################
+
+This type of memory can be written on a *page* base (typically 512 bytes,
+2048 or (much) larger), but must be erased prior writing the same page again and
+erasing must happen on an eraseblock base. Typical eraseblock sizes are
+64 kiB or (much) larger.
+
+From the Linux kernel perspective this type of memory is a *Memory Technologie
+Device* (aka 'MTD') and handled by barebox in the same manner. It needs a
+partition configuration.
+
+The following devicetree node entry defines some kind of NAND flash memory and
+a partition at a specific offset inside it to be used as the backend for the
+*state* variable set.
+
+.. code-block:: text
+
+	nandflash@0 {
+		backend_state_nand: partition@500000 {
+			[...]
+		};
+	};
+
+With this 'backend' definition its possible to define the *state* variable set
+content, its backend-type and *state* variable layout.
+
+.. code-block:: text
+
+	aliases {
+		state = &state_nand;
+	};
+
+	state_nand: nand_state_memory {
+		#address-cells = <1>;
+		#size-cells = <1>;
+		compatible = "barebox,state";
+		magic = <0xab67421f>;
+		backend-type = "raw";
+		backend = <&backend_state_nand>;
+		backend-storage-type = "circular";
+
+		variable {
+			reg = <0x0 0x1>;
+			type ="uint8";
+			default = <0x1>;
+		};
+	};
+
+SRAM
+####
+
+This type of memory can be written on a byte base and there is no need for an
+erase prior writing a new value.
+
+From the Linux kernel perspective this type of memory is a *Memory Technologie
+Device* (aka 'MTD') and handled by barebox in the same manner. It needs a
+partition definition.
+
+The following devicetree node entry defines some kind of SRAM memory and
+a partition at a specific offset inside it to be used as the backend for the
+*state* variable set.
+
+.. code-block:: text
+
+	sram@0 {
+		backend_state_sram: partition@10000 {
+			[...]
+		};
+	};
+
+With this 'backend' definition its possible to define the *state* variable set
+content, its backend-type and *state* variable layout.
+
+.. code-block:: text
+
+	aliases {
+		state = &state_sram;
+	};
+
+	state_sram: sram_state_memory {
+		#address-cells = <1>;
+		#size-cells = <1>;
+		compatible = "barebox,state";
+		magic = <0xab67421f>;
+		backend-type = "raw";
+		backend = <&backend_state_sram>;
+		backend-storage-type = "direct";
+		backend-stridesize = <32>;
+
+		variable {
+			reg = <0x0 0x1>;
+			type ="uint8";
+			default = <0x1>;
+		};
+	};
+
+EEPROM
+######
+
+This type of memory can be written on a byte base and must be erased prior
+writing, but in contrast to the other flash memories, an EEPROM does the erase
+of the address to be written to by its own, so its transparent to the
+application.
+
+While from the Linux kernel perspective this type of memory does not support
+partitions, barebox and the *state* userland tool will use partition definitions
+on an EEPROM memory as well, to exactly define the location in a generic manner
+within the EEPROM.
+
+.. code-block:: text
+
+	eeprom@50 {
+		partitions {
+			compatible = "fixed-partitions";
+			#size-cells = <1>;
+			#address-cells = <1>;
+			backend_state_eeprom: eeprom_state_memory@400 {
+				reg = <0x400 0x100>;
+				label = "state-eeprom";
+			};
+		};
+	};
+};
+
+With this 'backend' definition its possible to define the *state* variable set
+content, its backend-type and *state* variable layout.
+
+.. code-block:: text
+
+	aliases {
+		state = &state_eeprom;
+	};
+
+	state_eeprom: eeprom_memory {
+		#address-cells = <1>;
+		#size-cells = <1>;
+		compatible = "barebox,state";
+		magic = <0x344682db>;
+		backend-type = "raw";
+		backend = <&backend_state_eeprom>;
+		backend-storage-type = "direct";
+		backend-stridesize = <32>;
+
+		variable {
+			reg = <0x0 0x1>;
+			type ="uint8";
+			default = <0x1>;
+		};
+	};
+
+Frontend
 --------
 
-The ``state`` command can be used to store and manipulate the state. Using
-``state`` without argument lists you all available states with their name.
-``devinfo STATE_NAME`` shows you all variables and their values. ``state -s``
-stores the state.
+As frontend a *state* instance is a regular barebox device which has
+device parameters for the *state* variables. With this the variables can
+be accessed like normal shell variables. The ``state`` command is used
+to save/restore a *state* variable set to the backend device.
 
-Starting Barebox will automatically load the last written state. If loading the
-state fails the defaults are used.
+After initializing the variable can be accessed with ``$state.foo``.
+``state -s`` stores the *state* to the backend device.