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

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.

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

---

 doc/README.gpt | 33 +++++++++++++++++++++++++++++----
 1 file changed, 29 insertions(+), 4 deletions(-)

On Dienstag, 17. Oktober 2017 20:05:40 CEST you wrote:
> > On 17 Oct 2017, at 19:55, Stefan Brüns <stefan.bruens@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”.

non-standard != non-compliant
 
> > Signed-off-by: Stefan Brüns <stefan.bruens@rwth-aachen.de>
> 
> Reviewed-by: Philipp Tomsich <philipp.tomsich@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”).

It is the default for gdisk, parted, u-boots gpt command, likely also for the 
partitioners in MacOS and Windows. It also matches the example in the UEFI 
specification.
 
> > +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.

It is commonly used. E.g. with gdisk prior to version 1.0.2, it was the only 
option to use a GPT on one of the problematic SoCs.
 
> > +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.

Ever heard of reality? Nobody cares why something breaks or whose fault it is 
- if you break something, *you* have screwed up. U-Boot is no fuzzer. It is a 
boot loader.

If you do some research, you will find plenty of places which claim the 
partition entries *have to* start at LBA 2 - even this README.gpt stated 
"always 2". What happens if an implementation rejects the GPT when the entries 
are not located in LBA?

A warning is completely in line here.
 
> > +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.