[PATCH 1/4] doc: dt-bindings: barebox,environment: fix typo

[PATCH 1/4] doc: dt-bindings: barebox,environment: fix typo

[Roland Hieber]

Signed-off-by: Roland Hieber <rhi@pengutronix.de>

---
 .../devicetree/bindings/barebox/barebox,environment.rst         | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/devicetree/bindings/barebox/barebox,environment.rst b/Documentation/devicetree/bindings/barebox/barebox,environment.rst
index 40239f424ac0..67d1173b2fdc 100644
--- a/Documentation/devicetree/bindings/barebox/barebox,environment.rst
+++ b/Documentation/devicetree/bindings/barebox/barebox,environment.rst
@@ -23,7 +23,7 @@ the path to the environment. Supported values for <type>:
   be the label for MTD partitions, the number for DOS
   partitions (beginning with 0) or the name for GPT partitions.
 
-If the *environmnet* is located in a GPT partition, use
+If the *environment* is located in a GPT partition, use
 ``6C3737F2-07F8-45D1-AD45-15D260AAB24D`` as partition type GUID.
 
 The file-path is the name of a file located in a FAT filesystem on the
-- 
2.39.2

[PATCH 2/4] doc: dt-bindings: improve docs for barebox 'partuuid' property

[Roland Hieber]

Explain what the partuuid is, and make the lists valid reStructuredText
syntax.

Signed-off-by: Roland Hieber <rhi@pengutronix.de>
---
 .../devicetree/bindings/mtd/partition.rst       | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/Documentation/devicetree/bindings/mtd/partition.rst b/Documentation/devicetree/bindings/mtd/partition.rst
index 627b59eda04b..0f64dee3c3b3 100644
--- a/Documentation/devicetree/bindings/mtd/partition.rst
+++ b/Documentation/devicetree/bindings/mtd/partition.rst
@@ -4,13 +4,22 @@ Representing flash partitions in devicetree
 In addition to the upstream binding, another property is added:
 
 Optional properties:
-- ``partuuid`` : The global partition UUID for this partition.
+
+* ``partuuid``: The global partition UUID for this partition.
+  For GPT partitions, the partuuid is the 16-byte GPT Partition UUID (e.g.
+  ``de6f4f5c-c055-4374-09f7-8c6821dfb60e``).
+  For MBR partitions, the partuuid is the 4-byte disk identifier
+  followed by a dash and the partition number (starting with 1, e.g.
+  ``c9178f9d-01``).
+
+  The partuuid is case-insensitive.
 
 Additionally, barebox also supports partitioning the eMMC boot partitions if
 the partition table node is named appropriately:
-- ``partitions`` : user partition
-- ``boot0-partitions`` : boot0 partition
-- ``boot1-partitions`` : boot1 partition
+
+* ``partitions`` : user partition
+* ``boot0-partitions`` : boot0 partition
+* ``boot1-partitions`` : boot1 partition
 
 Examples:
 
-- 
2.39.2

[PATCH 3/4] doc: user: state: update note about redefining existing partitions

[Roland Hieber]

Fixes: ec34c2f5333adfee4724 (2023-06-07, "cdev: have devfs_add_partition return existing identical partition, not NULL")
Suggested-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
Signed-off-by: Roland Hieber <rhi@pengutronix.de>
---
 Documentation/user/state.rst | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/Documentation/user/state.rst b/Documentation/user/state.rst
index 594c2c15945b..7f4547f75507 100644
--- a/Documentation/user/state.rst
+++ b/Documentation/user/state.rst
@@ -542,10 +542,15 @@ 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 that currently there is no support for on-disk
-partition tables. Instead, an ofpart partition description must be used. You
-have to make sure that this partition does not conflict with any other partition
-in the partition table.
+*state* variable set.
+
+.. 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.
 
 .. code-block:: text
 
-- 
2.39.2

[PATCH 4/4] doc: user: state: document backend references using GPT/MBR partitions

[Roland Hieber]

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

Re: [PATCH 1/4] doc: dt-bindings: barebox,environment: fix typo

[Ahmad Fatoum]

On 08.08.23 11:26, Roland Hieber wrote:
> Signed-off-by: Roland Hieber <rhi@pengutronix.de>

Reviewed-by: Ahmad Fatoum <a.fatoum@pengutronix.de>

(For those wondering, s/environmnet/environment/)

> 
> ---
>  .../devicetree/bindings/barebox/barebox,environment.rst         | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/devicetree/bindings/barebox/barebox,environment.rst b/Documentation/devicetree/bindings/barebox/barebox,environment.rst
> index 40239f424ac0..67d1173b2fdc 100644
> --- a/Documentation/devicetree/bindings/barebox/barebox,environment.rst
> +++ b/Documentation/devicetree/bindings/barebox/barebox,environment.rst
> @@ -23,7 +23,7 @@ the path to the environment. Supported values for <type>:
>    be the label for MTD partitions, the number for DOS
>    partitions (beginning with 0) or the name for GPT partitions.
>  
> -If the *environmnet* is located in a GPT partition, use
> +If the *environment* is located in a GPT partition, use
>  ``6C3737F2-07F8-45D1-AD45-15D260AAB24D`` as partition type GUID.
>  
>  The file-path is the name of a file located in a FAT filesystem on the

-- 
Pengutronix e.K.                           |                             |
Steuerwalder Str. 21                       | http://www.pengutronix.de/  |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |

Re: [PATCH 1/4] doc: dt-bindings: barebox,environment: fix typo

[Sascha Hauer]

On Tue, Aug 08, 2023 at 11:26:14AM +0200, Roland Hieber wrote:
> Signed-off-by: Roland Hieber <rhi@pengutronix.de>
> 
> ---
>  .../devicetree/bindings/barebox/barebox,environment.rst         | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Applied, thanks

Sascha

> 
> diff --git a/Documentation/devicetree/bindings/barebox/barebox,environment.rst b/Documentation/devicetree/bindings/barebox/barebox,environment.rst
> index 40239f424ac0..67d1173b2fdc 100644
> --- a/Documentation/devicetree/bindings/barebox/barebox,environment.rst
> +++ b/Documentation/devicetree/bindings/barebox/barebox,environment.rst
> @@ -23,7 +23,7 @@ the path to the environment. Supported values for <type>:
>    be the label for MTD partitions, the number for DOS
>    partitions (beginning with 0) or the name for GPT partitions.
>  
> -If the *environmnet* is located in a GPT partition, use
> +If the *environment* is located in a GPT partition, use
>  ``6C3737F2-07F8-45D1-AD45-15D260AAB24D`` as partition type GUID.
>  
>  The file-path is the name of a file located in a FAT filesystem on the
> -- 
> 2.39.2
> 
> 
> 

-- 
Pengutronix e.K.                           |                             |
Steuerwalder Str. 21                       | http://www.pengutronix.de/  |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |