.. _state_framework: 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 -------- 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. Starting Barebox will automatically load the last written state. If loading the state fails the defaults are used.