Explain first how to define the state node and variable set, and then
go into detail about the different variations of backend definitions,
including the options of referring to a backend partition by its
partuuid or letting barebox auto-detect it by its Type GUID.
Fixes: 776714d9570253c46635 (2023-06-07, "state: allow lookup of barebox state partition by Type GUID")
Suggested-by: Ahmad Fatoum <a.fatoum@xxxxxxxxxxxxxx>
Signed-off-by: Roland Hieber <rhi@xxxxxxxxxxxxxx>
---
.../devicetree/bindings/mtd/partition.rst | 2 +
Documentation/user/state.rst | 110 ++++++++++++++----
2 files changed, 90 insertions(+), 22 deletions(-)
diff --git a/Documentation/devicetree/bindings/mtd/partition.rst b/Documentation/devicetree/bindings/mtd/partition.rst
index 0f64dee3c3b3..0ba117dffcd3 100644
--- a/Documentation/devicetree/bindings/mtd/partition.rst
+++ b/Documentation/devicetree/bindings/mtd/partition.rst
@@ -1,3 +1,5 @@
+.. _devicetree_binding_mtd_partition:
+
Representing flash partitions in devicetree
===========================================
diff --git a/Documentation/user/state.rst b/Documentation/user/state.rst
index 7f4547f75507..9054a3792337 100644
--- a/Documentation/user/state.rst
+++ b/Documentation/user/state.rst
@@ -540,27 +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::
+*state* node definition
+^^^^^^^^^^^^^^^^^^^^^^^
- 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.
-
-.. code-block:: text
-
- backend_state_sd: part@100000 {
- label = "state";
- reg = <0x100000 0x20000>;
- };
-
-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
@@ -584,8 +571,87 @@ content, its backend-type and *state* variable layout.
};
};
-If the *state* variable set is set to be located in a GPT partition, use
-``4778ed65-bf42-45fa-9c5b-287a1dc4aab1`` as the partition type GUID.
+
+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
####
--
2.39.2
