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

[Stefan Brüns]

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 at rwth-aachen.de>

---

 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,
+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.
+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.
+
+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