state: add framework for persistent state handling

This patch adds 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.

For more information see:
    Documentation/devicetree/bindings/barebox/barebox,state.rst

Signed-off-by: Sascha Hauer <s.hauer@pengutronix.de>
Signed-off-by: Jan Luebbe <jlu@pengutronix.de>
Signed-off-by: Marc Kleine-Budde <mkl@pengutronix.de>
Signed-off-by: Sascha Hauer <s.hauer@pengutronix.de>

1 files changed, 107 insertions, 0 deletions

diff --git a/Documentation/devicetree/bindings/barebox/barebox,state.rst b/Documentation/devicetree/bindings/barebox/barebox,state.rst
new file mode 100644
index 0000000000..42b2a34d3a
--- /dev/null
+++ b/Documentation/devicetree/bindings/barebox/barebox,state.rst
@@ -0,0 +1,107 @@
+barebox,state
+=============
+
+Overview
+--------
+
+
+Boards often have the need to store variables in persistent memory.
+The constraints are often different from what the regular environment
+can do:
+
+* compact binary format to make it suitable for small EEPROMs/MRAMs
+* atomic save/restore of the whole variable set
+* redundancy
+
+``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.
+
+A state node contains a description of a set of variables along with a
+place where the variables are stored.
+
+Required properties:
+
+* ``compatible``: should be ``barebox,state``;
+* ``magic``: A 32bit number used as a magic to identify the state
+
+Optional properties:
+
+* ``backend``: describes where the data for this state is stored
+* ``backend-type``: should be ``raw`` or ``dtb``.
+
+Variable nodes
+--------------
+
+These are subnodes of a state node each describing a single
+variable. The node name may end with ``@<ADDRESS>``, but the suffix is
+sripped from the variable name.
+
+State variables have a type. Currenty supported types are: ``uint32``,
+``enum32`` and ``mac`` address. Fixed length strings are planned but
+not implemented. Variable length strings are not planned.
+
+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
+  ``type``. Variables are not allowed to overlap.
+* ``type``: Should be ``uint32``, ``enum32`` or ``mac`` 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::
+
+  state: state@0 {
+  	magic = <0x27031977>;
+  	compatible = "barebox,state";
+  	backend-type = "raw";
+  	backend = &eeprom, "partname:state";
+
+  	foo {
+		reg = <0x00 0x4>;
+  		type = "u32";
+  		default = <0x0>;
+  	};
+
+  	bar {
+		reg = <0x10 0x4>;
+  		type = "enum32";
+  		names = "baz", "qux";
+  		default ="qux";
+  	};
+  };
+
+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.
+
+Frontend
+--------
+
+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.
+
+After initializing the variable can be accessed with ``$state.foo``.
+``state -s`` stores the state to eeprom.