Merge branch 'for-next/state'

2 files changed, 214 insertions, 121 deletions

diff --git a/Documentation/devicetree/bindings/barebox/barebox,state.rst b/Documentation/devicetree/bindings/barebox/barebox,state.rst
index 40d7bc2e6f..cebb5f8287 100644
--- a/Documentation/devicetree/bindings/barebox/barebox,state.rst
+++ b/Documentation/devicetree/bindings/barebox/barebox,state.rst
@@ -1,55 +1,91 @@
 .. _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``,
+  ``circular`` or ``noncircular``. If the backend memory needs to be erased
+  prior a write it defaults to the ``circular`` storage backend type, for backend
+  memories like RAMs or EEPROMs it defaults to the ``direct`` storage backend type.
+* ``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 +93,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/devicetree/index.rst b/Documentation/devicetree/index.rst
index c5992c0fc9..de571547e0 100644
--- a/Documentation/devicetree/index.rst
+++ b/Documentation/devicetree/index.rst
@@ -12,3 +12,4 @@ Contents:
    bindings/leds/*
    bindings/misc/*
    bindings/mtd/*
+   bindings/rtc/*