From 529df0b58030cebd7773d1bec4900af1716bb42d Mon Sep 17 00:00:00 2001 From: Brandon Maier Date: Sun, 17 Nov 2024 15:00:38 -0600 Subject: [PATCH] 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 [Arnout: some additional rewording mainly based on input from Niklas Cassel] Signed-off-by: Arnout Vandecappelle --- docs/manual/writing-rules.adoc | 44 ++++++++++++++++++++-------------- 1 file changed, 26 insertions(+), 18 deletions(-) diff --git a/docs/manual/writing-rules.adoc b/docs/manual/writing-rules.adoc index 03e4f2c61c..1e3e9e1c9f 100644 --- a/docs/manual/writing-rules.adoc +++ b/docs/manual/writing-rules.adoc @@ -141,9 +141,9 @@ endif === The +genimage.cfg+ file +genimage.cfg+ files contain the output image layout that genimage utility -uses to create final .img file. - -An example follows: +uses to create final .img file. See the +https://github.com/pengutronix/genimage/blob/master/README.rst[upstream +documentation] for details. In Buildroot it is formatted as follows. ---- image efi-part.vfat { @@ -198,22 +198,30 @@ 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+. It must not be double-quoted. Buildroot + follows the + https://uapi-group.org/specifications/specs/discoverable_partitions_specification/[UAPI + Discoverable Partitions Specification] whenever possible. This means that the + partitions define a specific +partition-type-uuid+ depending on the intended + mountpoint. + + + _genimage_ provides + https://github.com/pengutronix/genimage/?tab=readme-ov-file#the-image-section[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: -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 -details about the _genimage_ language, refer to -https://github.com/pengutronix/genimage/blob/master/README.rst[]. +** +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 documentation