[U-Boot] [PATCH 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(-)
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.
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”.
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”).
+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
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.
participants (3)
-
Dr. Philipp Tomsich -
Stefan Bruens -
Stefan Brüns