mail archive of the barebox mailing list
 help / color / mirror / Atom feed
From: Roland Hieber <rhi@pengutronix.de>
To: barebox@lists.infradead.org
Cc: Roland Hieber <rhi@pengutronix.de>,
	Ahmad Fatoum <a.fatoum@pengutronix.de>
Subject: [PATCH 4/4] doc: user: state: document backend references using GPT/MBR partitions
Date: Tue,  8 Aug 2023 11:26:17 +0200	[thread overview]
Message-ID: <20230808092617.2037996-4-rhi@pengutronix.de> (raw)
In-Reply-To: <20230808092617.2037996-1-rhi@pengutronix.de>

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@pengutronix.de>
Signed-off-by: Roland Hieber <rhi@pengutronix.de>
---
 .../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




  parent reply	other threads:[~2023-08-08  9:27 UTC|newest]

Thread overview: 6+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2023-08-08  9:26 [PATCH 1/4] doc: dt-bindings: barebox,environment: fix typo Roland Hieber
2023-08-08  9:26 ` [PATCH 2/4] doc: dt-bindings: improve docs for barebox 'partuuid' property Roland Hieber
2023-08-08  9:26 ` [PATCH 3/4] doc: user: state: update note about redefining existing partitions Roland Hieber
2023-08-08  9:26 ` Roland Hieber [this message]
2023-08-08  9:37 ` [PATCH 1/4] doc: dt-bindings: barebox,environment: fix typo Ahmad Fatoum
2023-08-09  5:40 ` Sascha Hauer

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=20230808092617.2037996-4-rhi@pengutronix.de \
    --to=rhi@pengutronix.de \
    --cc=a.fatoum@pengutronix.de \
    --cc=barebox@lists.infradead.org \
    /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