[v2] docs/manual/writing-rules: align use of genimage partition types

Buildroot boards use a mixture of the GPT Partition Type "L" (generic
Linux filesystem) and "root-x86", "root-arm", etc (UAPI Root
Filesystem) for root filesystem partitions.

To have consistent guidance on building disk images with genimage,
update the docs to recommend using the UAPI Root Filesystem types. The
UAPI Root Filesystem types are part of the UAPI Discoverable Partitions
Specification (DPS) which helps set a wider standard for system boot.

See https://uapi-group.org/specifications/specs/discoverable_partitions_specification/

Signed-off-by: Brandon Maier <brandon.maier@gmail.com>
---
Changes in v2:
- Update docs to call out root-* partition type [Niklas, Thomas]
- Drop GUID board updates for a later patch series
- Link to v1: https://lore.kernel.org/r/20241109-genimage-partition-type-uuid-v1-0-9f23180c7195@gmail.com
---
 docs/manual/writing-rules.adoc | 37 ++++++++++++++++++++++++++-----------
 1 file changed, 26 insertions(+), 11 deletions(-)


---
base-commit: 0df7dfb804457a62c7751eec6555ad75158e3e3d
change-id: 20241109-genimage-partition-type-uuid-8e4c62ee041f

Best regards,

On Sun, Nov 17, 2024 at 03:00:38PM -0600, Brandon Maier wrote:
> Buildroot boards use a mixture of the GPT Partition Type "L" (generic
> Linux filesystem) and "root-x86", "root-arm", etc (UAPI Root
> Filesystem) for root filesystem partitions.
> 
> To have consistent guidance on building disk images with genimage,
> update the docs to recommend using the UAPI Root Filesystem types. The
> UAPI Root Filesystem types are part of the UAPI Discoverable Partitions
> Specification (DPS) which helps set a wider standard for system boot.
> 
> See https://uapi-group.org/specifications/specs/discoverable_partitions_specification/
> 
> Signed-off-by: Brandon Maier <brandon.maier@gmail.com>
> ---
> Changes in v2:
> - Update docs to call out root-* partition type [Niklas, Thomas]
> - Drop GUID board updates for a later patch series
> - Link to v1: https://lore.kernel.org/r/20241109-genimage-partition-type-uuid-v1-0-9f23180c7195@gmail.com
> ---
>  docs/manual/writing-rules.adoc | 37 ++++++++++++++++++++++++++-----------
>  1 file changed, 26 insertions(+), 11 deletions(-)
> 
> diff --git a/docs/manual/writing-rules.adoc b/docs/manual/writing-rules.adoc
> index 03e4f2c61cfe4820fe6d06d193b9215d423bf4d7..3964deca867494ca4df70f3c0d92f9982ec6deec 100644
> --- a/docs/manual/writing-rules.adoc
> +++ b/docs/manual/writing-rules.adoc
> @@ -198,17 +198,32 @@ image sdimage.img {
>    chance, the byte count.  In comments instead use +GB+, +MB+, +KB+
>    (not +kb+) in place of +G+, +M+, +K+.
>  
> -* For GPT partitions, the +partition-type-uuid+ value must be +U+ for
> -  the EFI System Partition (expanded to
> -  +c12a7328-f81f-11d2-ba4b-00a0c93ec93b+ by _genimage_), +F+ for a FAT
> -  partition (expanded to +ebd0a0a2-b9e5-4433-87c0-68b6b72699c7+ by
> -  _genimage_) or +L+ for the root filesystem or other filesystems
> -  (expanded to +0fc63daf-8483-4772-8e79-3d69d8477de4+ by
> -  _genimage_). Even though +L+ is the default value of _genimage_, we
> -  prefer to have it explicitly specified in our +genimage.cfg+
> -  files. Finally, these shortcuts should be used without double
> -  quotes, e.g +partition-type-uuid = U+. If an explicit GUID is
> -  specified, lower-case letters should be used.
> +* Every +partition+ of a GPT image (e.g. +partition-table-type = gpt+) must
> +  explicitly set +partition-type-uuid+.
> +
> +** Every +partition-type-uuid+ value must not be double quoted

s/quoted/quoted./


> +
> +** Every +partition-type-uuid+ value must be written with _genimage_ GUID
> +   shortcuts (for example, use +U+ instead of +c12a7328-...+). For a list of
> +   GUID shortcuts, see
> +   https://github.com/pengutronix/genimage/?tab=readme-ov-file#the-image-section
> +   If a GUID shortcut is not supported by _genimage_, the full GUID must be
> +   written in lower-case letters.
> +
> +** Every +partition-type-uuid+ must use a GUID from the
> +   https://uapi-group.org/specifications/specs/discoverable_partitions_specification/[UAPI
> +   Discoverable Partitions Specification] when possible. Some common partition
> +   types are as follows.

s/follows./follows:/


I think that it makes more sense if these two sentences above are swapped,
such that you mention the Discoverable Partitions Specification first.

Otherwise it is a bit confusing, should I follow genimage or the
Discoverable Partitions Specification?


Perhaps something like:

Buildroot follows the
https://uapi-group.org/specifications/specs/discoverable_partitions_specification/[Discoverable
Partitions Specification] whenever possible. This means that the partitions define a
specific +partition-type-uuid+ depending on the mountpoint.

_genimage_ provides shortcuts for many of the partition types in the Discoverable
Partitions Specification, and these shortcuts must be used whenever possible.
If a GUID shortcut is not supported by _genimage_, the full GUID must be written
in lower-case letters. Some common shortcuts are as follows:

+*** +U+ for the EFI System Partition (expanded to
+    +c12a7328-f81f-11d2-ba4b-00a0c93ec93b+ by _genimage_)
+
+*** +root-\{arch\}+ for the root filesystem partition, where +\{arch\}+ is the
+    system architecture (for example +root-x86+, +root-x86-64+, +root-arm+, or
+    +root-arm64+)
+
+*** +L+ for other Linux filesystem partitions (expanded to
+    +0fc63daf-8483-4772-8e79-3d69d8477de4+ by _genimage_).


>  The +genimage.cfg+ files are the input for the genimage tool used in
>  Buildroot to generate the final image file(i.e. sdcard.img). For further

Perhaps you do:
s/file(/file (/
here.


Kind regards,
Niklas

On Mon, Nov 18, 2024 at 03:05:40PM +0000, Niklas Cassel wrote:
> On Sun, Nov 17, 2024 at 03:00:38PM -0600, Brandon Maier wrote:
> 
> Perhaps something like:
> 
> Buildroot follows the
> https://uapi-group.org/specifications/specs/discoverable_partitions_specification/[Discoverable
> Partitions Specification] whenever possible. This means that the partitions define a
> specific +partition-type-uuid+ depending on the mountpoint.
> 
> _genimage_ provides shortcuts for many of the partition types in the Discoverable
> Partitions Specification, and these shortcuts must be used whenever possible.
> If a GUID shortcut is not supported by _genimage_, the full GUID must be written
> in lower-case letters. Some common shortcuts are as follows:
> 
> +*** +U+ for the EFI System Partition (expanded to
> +    +c12a7328-f81f-11d2-ba4b-00a0c93ec93b+ by _genimage_)
> +
> +*** +root-\{arch\}+ for the root filesystem partition, where +\{arch\}+ is the
> +    system architecture (for example +root-x86+, +root-x86-64+, +root-arm+, or
> +    +root-arm64+)
> +
> +*** +L+ for other Linux filesystem partitions (expanded to
> +    +0fc63daf-8483-4772-8e79-3d69d8477de4+ by _genimage_).

For a list of all _genimage_ GUID shortcuts, see
https://github.com/pengutronix/genimage/?tab=readme-ov-file#the-image-section


> 
> >  The +genimage.cfg+ files are the input for the genimage tool used in
> >  Buildroot to generate the final image file(i.e. sdcard.img). For further
> 
> Perhaps you do:
> s/file(/file (/
> here.

Looking at other examples in the file, it looks like there shouldn't
be a space before the opening '(', so perhaps I was wrong here.


Kind regards,
Niklas