[U-Boot] [PATCH v1] Document padding between GPT header and partition entries

[Dr. Philipp Tomsich]

> On 17 Oct 2017, at 19:55, Stefan Brüns <stefan.bruens at rwth-aachen.de> wrote:
> 
> Commit 02e43537b322 ("part_efi: support padding between the GPT
> header and partition entries") added support for deviating from
> the typical GPT layout.
> 
> Explicitly state deviations are allowed/possible, and mention when
> (SoC SPL) and when not (compatibility) deviations are useful. Also
> mention support for non-standard layouts in gdisk 1.0.3.

There is nothing in the GPT specification that mandates that the
partition entries are to follow immediately after the header and it
is even assumed that this does not have to be the case (i.e. the
address needs to be computed from the info in the header).

So I object to the “non-standard”.

> 
> Signed-off-by: Stefan Brüns <stefan.bruens at rwth-aachen.de>

Reviewed-by: Philipp Tomsich <philipp.tomsich at theobroma-systems.com>

> 
> ---
> 
> doc/README.gpt | 33 +++++++++++++++++++++++++++++----
> 1 file changed, 29 insertions(+), 4 deletions(-)
> 
> diff --git a/doc/README.gpt b/doc/README.gpt
> index d3db8bce1c..7134f3b3cf 100644
> --- a/doc/README.gpt
> +++ b/doc/README.gpt
> @@ -44,8 +44,8 @@ uuid command line tool).
> GPT brief explanation:
> ======================
> 
> -	Layout:
> -	-------
> +	Default layout:
> +	---------------
> 
> 	--------------------------------------------------
> 	LBA 0          |Protective MBR                   |
> @@ -82,7 +82,29 @@ For a legacy reasons, GPT's LBA 0 sector has a MBR structure. It is called
> Its first partition entry ID has 0xEE value, and disk software, which is not
> handling the GPT sees it as a storage device without free space.
> 
> -It is possible to define 128 linearly placed partition entries.
> +By default, the first partition entry of the primary GPT is stored in LBA 2,

The “default" is merely the most compact representation (i.e. tries to waste
no space). I would not even call this “default” (it is a common behaviour found
“in the wild”, but in no way a “default”).

> +although this is not explicitly mandated by the UEFI specification. The
> +start LBAs of the partition entries are given in the corresponding GPT
> +headers (Primary/Backup) (offset 72 bytes).
> +
> +The UEFI specification mandates at least 128 contigously stored partition
> +entries, the number is specified in the GPT headers (offset 80).
> +
> +As several SoCs require the SPL to be located at a fixed position, often
> +below LBA 34 (17 kByte for 512 byte blocks), it is possible to deviate
> +from the standard layout:
> +
> +1. Lower the number of partition entries. This violates the UEFI/GPT
> +   specification, but usually works.

If you deviate from the UEFI/GPT specification, then you don’t have a
GPT partition table. So this is not a permissible change and thus should
not be listed here.

> +2. Insert a gap between Primary GPT Header and partition entries. This
> +   is in line with the specification, but may cause problems with tools
> +   or operating systems hardcoding the partition entries LBA to 2.

In which the operating systems do not support GPT partitions (but something
that is close enough to work, as long as the stars are aligned just right) and
there is no reason not to break compatibility against these.

> +
> +There is limited support for both variants in U-Boot - reading is fully
> +supported, while the "gpt write" command always creates a GPT with 128
> +entries. A gap is created when CONFIG_EFI_PARTITION_ENTRIES_OFF is set
> +or when the device tree "/config" node contains a property
> +"u-boot,efi-partition-entries-offset".
> 
> "LBA -1" means the last addressable block (in the mmc subsystem:
> "dev_desc->lba - 1")
> @@ -103,7 +125,7 @@ Offset  Size    Description
> 		LBA + 1)
> 48      8 B     Last usable LBA (secondary partition table first LBA - 1)
> 56      16 B    Disk GUID (also referred as UUID on UNIXes)
> -72      8 B     Partition entries starting LBA (always 2 in primary copy)
> +72      8 B     Partition entries starting LBA (usually 2 in primary copy)
> 80      4 B     Number of partition entries
> 84      4 B     Size of a partition entry (usually 128)
> 88      4 B     CRC32 of partition array
> @@ -283,6 +305,9 @@ Two programs, namely: 'gdisk' and 'parted' are recommended to work with GPT
> recovery. Both are able to handle GUID partitions.
> Please, pay attention at -l switch for parted.
> 
> +'gdisk' as of version 1.0.3 is able to create tables with a number of partition
> +entries different to 128, and insert padding after the GPT header.
> +
> "uuid" program is recommended to generate UUID string. Moreover it can decode
> (-d switch) passed in UUID string. It can be used to generate partitions UUID
> passed to u-boot environment variables.
> -- 
> 2.14.2
>