diff options
Diffstat (limited to 'Documentation/user/state.rst')
| -rw-r--r-- | Documentation/user/state.rst | 112 |
1 files changed, 93 insertions, 19 deletions
diff --git a/Documentation/user/state.rst b/Documentation/user/state.rst index 78ce24f9ed..9054a37923 100644 --- a/Documentation/user/state.rst +++ b/Documentation/user/state.rst @@ -24,7 +24,7 @@ barebox itself uses a *state* driver to access the variables in the persistent memory. Currently there is only one implementation, enabled by -``CONFIG_STATE_DRV=y``. Without driver, the state framework will silently +``CONFIG_STATE_DRV=y``. Without driver, the state framework will silently fail and be non-functional. For the Linux run-time there is a userspace tool_ to do @@ -540,22 +540,14 @@ content, its backend-type and *state* variable layout. SD/eMMC and ATA ############### -The following devicetree node entry defines some kind of SD/eMMC memory and -a partition at a specific offset inside it to be used as the backend for the -*state* variable set. Note that currently there is no support for on-disk -partition tables. Instead, an ofpart partition description must be used. You -have to make sure that this partition does not conflict with any other partition -in the partition table. - -.. code-block:: text - - backend_state_sd: part@100000 { - label = "state"; - reg = <0x100000 0x20000>; - }; +*state* node definition +^^^^^^^^^^^^^^^^^^^^^^^ -With this 'backend' definition it's possible to define the *state* variable set -content, its backend-type and *state* variable layout. +These storage types have integrated wear-levelling and can be addressed on the +byte level. The *raw* backend type is suitable for this situation. +We will explain the possible variants of referring to a backend below, +but an exemplary definition of the *state* layout and variable set will look +as follows: .. code-block:: text @@ -579,6 +571,88 @@ content, its backend-type and *state* variable layout. }; }; + +Backend definition +^^^^^^^^^^^^^^^^^^ + +SD/eMMC and ATA devices usually have an on-disk partition table (MBR or GPT), +which Barebox will parse when a block device is probed. +There are multiple options to refer to these partitions as the *state* backend +(i.e. the ``&backend_state_sd`` reference in the example above). + +Referencing the partition by GUID +""""""""""""""""""""""""""""""""" + +When using GPT, the backend reference may point directly to a block device's +device tree node. In this case Barebox will search for a GPT partition with Type +UUID ``4778ed65-bf42-45fa-9c5b-287a1dc4aab1``, and if that partition exists, +Barebox will use it as the *state* backend. + +Here is an abridged example: + +.. code-block:: text + + / { + soc { + bus@2100000 { + mmc1: mmc@2190000 { + // … MMC device definition … + }; + }; + + aliases { + state = &state_sd; + }; + + state_sd: state { + backend = <&mmc1>; + // … rest of definition as per above section + }; + }; + +This is the recommended approach for device tree enabled system with state +located on SD or eMMC. + +Referencing the partition by *partuuid* +""""""""""""""""""""""""""""""""""""""" + +For systems where block devices are not probed from device tree (e.g. with +storage on ATA or PCI buses), the *state* partition can be looked up globally +by specifying its *partuuid*. See the documentation for the :ref:`partuuid +device tree binding <devicetree_binding_mtd_partition>` for more details. + +The *partuuid* is expected to be unique across all block devices. + +Referencing the partition by offset +""""""""""""""""""""""""""""""""""" + +As a fallback it is still possible to refer to the *state* partition by +specifying its offset and size, like in the examples for NAND and NOR flash +above: + +.. code-block:: text + + &mmc1 { + partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <1>; + […] + backend_state_sd: partition@100000 { + label = "state"; + reg = <0x100000 0x20000>; + }; + }; + }; + +.. note:: + + If the medium has an on-disk partition table, the device tree partition + must either be identical in start offset and size to the MBR/GPT partition + or it must reside in non-partitioned space. If this constraint is not + satisfied, barebox will emit an error message and refuse to register + the device tree partition. + SRAM #### @@ -684,9 +758,9 @@ Frontend -------- As frontend a *state* instance is a regular barebox device which has -device parameters for the *state* variables. With this the variables can +:ref:`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. -After initializing the variable can be accessed with ``$state.foo``. -``state -s`` stores the *state* to the backend device. +After initializing the variable can be accessed with ``${state.foo}`` or +:ref:`command_setenv`. ``state -s`` stores the *state* to the backend device. |