mail archive of the barebox mailing list
 help / color / mirror / Atom feed
From: Markus Pargmann <mpa@pengutronix.de>
To: barebox@lists.infradead.org
Cc: mgr@pengutronix.de
Subject: [PATCH v2 3/6] docs: Add/Update state documentation
Date: Fri, 24 Jun 2016 12:05:59 +0200	[thread overview]
Message-ID: <1466762762-15212-4-git-send-email-mpa@pengutronix.de> (raw)
In-Reply-To: <1466762762-15212-1-git-send-email-mpa@pengutronix.de>

Signed-off-by: Markus Pargmann <mpa@pengutronix.de>
---
 .../devicetree/bindings/barebox/barebox,state.rst  |  7 +++-
 Documentation/user/state.rst                       | 46 ++++++++++++++++++++++
 Documentation/user/user-manual.rst                 |  1 +
 3 files changed, 53 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/user/state.rst

diff --git a/Documentation/devicetree/bindings/barebox/barebox,state.rst b/Documentation/devicetree/bindings/barebox/barebox,state.rst
index d50765705348..e39245f6c0bf 100644
--- a/Documentation/devicetree/bindings/barebox/barebox,state.rst
+++ b/Documentation/devicetree/bindings/barebox/barebox,state.rst
@@ -36,7 +36,12 @@ Optional properties:
 
 * ``algo``: A HMAC algorithm used to detect manipulation of the data
   or header, sensible values follow this pattern ``hmac(<HASH>)``,
-  e.g. ``hmac(sha256)``.
+  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.
 
 Variable nodes
 --------------
diff --git a/Documentation/user/state.rst b/Documentation/user/state.rst
new file mode 100644
index 000000000000..c401f105bd64
--- /dev/null
+++ b/Documentation/user/state.rst
@@ -0,0 +1,46 @@
+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.
+
+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.
+
+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.
diff --git a/Documentation/user/user-manual.rst b/Documentation/user/user-manual.rst
index be44f0d64541..5841ea625c09 100644
--- a/Documentation/user/user-manual.rst
+++ b/Documentation/user/user-manual.rst
@@ -31,6 +31,7 @@ Contents:
    system-setup
    reset-reason
    system-reset
+   state
 
 * :ref:`search`
 * :ref:`genindex`
-- 
2.8.1


_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

  parent reply	other threads:[~2016-06-24 10:07 UTC|newest]

Thread overview: 10+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2016-06-24 10:05 [PATCH v2 0/6] state: Refactor backend Markus Pargmann
2016-06-24 10:05 ` [PATCH v2 1/6] libfile: Change write_full to be have const buf Markus Pargmann
2016-06-24 10:05 ` [PATCH v2 2/6] state: Refactor state framework Markus Pargmann
2016-06-24 10:05 ` Markus Pargmann [this message]
2016-06-24 10:06 ` [PATCH v2 4/6] state: also append backend storage stridesize Markus Pargmann
2016-06-24 10:06 ` [PATCH v2 5/6] state: backend_storage_direct: also use cached data on write Markus Pargmann
2016-06-28  6:18   ` Sascha Hauer
2016-06-28  6:55     ` Michael Grzeschik
2016-06-29  5:56       ` Markus Pargmann
2016-06-24 10:06 ` [PATCH v2 6/6] barebox-state: handle flush errno correctly Markus Pargmann

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=1466762762-15212-4-git-send-email-mpa@pengutronix.de \
    --to=mpa@pengutronix.de \
    --cc=barebox@lists.infradead.org \
    --cc=mgr@pengutronix.de \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox