diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/devicetree/bindings/barebox/barebox,state.rst | 33 | ||||
| -rw-r--r-- | Documentation/user/state.rst | 33 |
2 files changed, 49 insertions, 17 deletions
diff --git a/Documentation/devicetree/bindings/barebox/barebox,state.rst b/Documentation/devicetree/bindings/barebox/barebox,state.rst index 438cc434a2..00fb592614 100644 --- a/Documentation/devicetree/bindings/barebox/barebox,state.rst +++ b/Documentation/devicetree/bindings/barebox/barebox,state.rst @@ -29,7 +29,8 @@ Required properties: * ``compatible``: should be ``barebox,state``; * ``magic``: A 32bit number used as a magic to identify the state -* ``backend``: describes where the data for this state is stored +* ``backend``: contains a phandle to the device/partition which holds the + actual state data. * ``backend-type``: should be ``raw`` or ``dtb``. Optional properties: @@ -39,9 +40,9 @@ Optional properties: 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``: Type of the storage. This has two options at the - moment. For MTD with erasing the correct type is ``circular``. For all other - devices and files, ``direct`` is the needed type. +* ``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. Variable nodes -------------- @@ -77,19 +78,31 @@ Example:: magic = <0x27031977>; compatible = "barebox,state"; backend-type = "raw"; - backend = &eeprom, "partname:state"; + backend = &state_part; foo { - reg = <0x00 0x4>; - type = "uint32"; + reg = <0x00 0x4>; + type = "uint32"; default = <0x0>; }; bar { - reg = <0x10 0x4>; - type = "enum32"; + reg = <0x10 0x4>; + type = "enum32"; names = "baz", "qux"; - default = <1>; + default = <1>; + }; + }; + + &nand_flash { + partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <1>; + state_part: state@10000 { + label = "state"; + reg = <0x10000 0x10000>; + }; }; }; diff --git a/Documentation/user/state.rst b/Documentation/user/state.rst index 5dd5c486e2..73c4be8159 100644 --- a/Documentation/user/state.rst +++ b/Documentation/user/state.rst @@ -23,16 +23,35 @@ 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 which are automatically -selected depending on the defined backend in the devicetree. Currently two -implementations exist, ``circular`` and ``direct``. ``circular`` writes the -data sequentially on the backend storage device. Each save is appended until -the storage area is full. It then erases the block and starts from offset 0. -``circular`` is used for MTD devices with erase functionality. ``direct`` -writes the data directly to the file without erasing. +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. |