[PATCH 7/7] docs: rework and extend the 'state' and 'bootchooser' documentation
Juergen Borleis
jbe at pengutronix.de
Tue Aug 15 06:46:36 PDT 2017
Many links between sections and examples were added to give the developer
the help to get it work.
Signed-off-by: Juergen Borleis <jbe at pengutronix.de>
---
.../devicetree/bindings/barebox/barebox,state.rst | 332 ++++++----
Documentation/user/bootchooser.rst | 493 +++++++++++----
Documentation/user/state.rst | 696 +++++++++++++++++++--
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 40d7bc2e6..4b1aade66 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 at 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 at 0 {
+ reg = <0x0 0x1>;
+ type = "uint8";
+ default = <0x00>;
+ };
+
+``uint32``:
+
+.. code-block:: text
+
+ uint32_example at 0 {
+ reg = <0x0 0x4>;
+ type = "uint32";
+ default = <100>;
+ };
+
+``enum32``:
+
+.. code-block:: text
+
+ enum_example at 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 at 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 at 01``
+to define its own *state* variable set backend.
+
+Barebox's devicetree defines:
+
+.. code-block:: text
+
+ persistent_state_memory at 01 {
+ compatible = "somevalue";
+ reg = <1>;
+
+ #address-cells = <1>;
+ #size-cells = <1>;
+
+ state: partition at 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 at 01 {
+ compatible = "somevalue";
+ reg = <1>;
+ };
diff --git a/Documentation/user/bootchooser.rst b/Documentation/user/bootchooser.rst
index cef1d4abb..3d473b596 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 at 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 at 0 {
+ reg = <0x0 0x4>;
+ type = "uint32";
+ default = <3>;
+ };
+ priority at 4 {
+ reg = <0x4 0x4>;
+ type = "uint32";
+ default = <20>;
+ };
+ };
+
+ system2 {
+ #address-cells = <1>;
+ #size-cells = <1>;
+ remaining_attempts at 8 {
+ reg = <0x8 0x4>;
+ type = "uint32";
+ default = <3>;
+ };
+ priority at c {
+ reg = <0xc 0x4>;
+ type = "uint32";
+ default = <21>;
+ };
+ };
+
+ last_chosen at 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 73c4be815..7d6c5770d 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 at 0 {
+ backend_state_nor: partition at 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 at 0 {
+ backend_state_nand: partition at 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 at 0 {
+ backend_state_sram: partition at 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 at 50 {
+ partitions {
+ compatible = "fixed-partitions";
+ #size-cells = <1>;
+ #address-cells = <1>;
+ backend_state_eeprom: eeprom_state_memory at 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.
--
2.11.0
More information about the barebox
mailing list