+# SPDX-License-Identifier: GPL-2.0+
#
# Copyright (C) 2012 Samsung Electronics
#
# Lukasz Majewski <l.majewski@samsung.com>
-#
-#
-# SPDX-License-Identifier: GPL-2.0+
-
Glossary:
========
This document describes the GPT partition table format and usage of
the gpt command in u-boot.
-
UUID introduction:
====================
separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters
(32 digits and 4 hyphens)
-For instance, GUID of Linux data partition: EBD0A0A2-B9E5-4433-87C0-68B6B72699C7
+For instance, GUID of Basic data partition: EBD0A0A2-B9E5-4433-87C0-68B6B72699C7
+and GUID of Linux filesystem data: 0FC63DAF-8483-4772-8E79-3D69D8477DE4
Historically there are 5 methods to generate this number. The oldest one is
combining machine's MAC address and timer (epoch) value.
|Partition n |
| |
----------------------------------------------------------
- LBA -34 |Entry 1|Entry 2| Entry 3| Entry 4| Secondary
- -------------------------------------------------- (bkp)
- LBA -33 |Entries 5 - 128 | GPT
+ LBA -34 |Entry 1|Entry 2| Entry 3| Entry 4| Backup
+ -------------------------------------------------- GPT
+ LBA -33 |Entries 5 - 128 |
| |
| |
LBA -2 | |
--------------------------------------------------
- LBA -1 |Secondary GPT Header |
+ LBA -1 |Backup GPT Header |
----------------------------------------------------------
-
For a legacy reasons, GPT's LBA 0 sector has a MBR structure. It is called
"protective MBR".
Its first partition entry ID has 0xEE value, and disk software, which is not
"LBA -1" means the last addressable block (in the mmc subsystem:
"dev_desc->lba - 1")
-Primary/Secondary GPT header:
+Primary/Backup GPT header:
----------------------------
Offset Size Description
TOTAL: 512 B
-
IMPORTANT:
GPT headers and partition entries are protected by CRC32 (the POSIX CRC32).
-Primary GPT header and Secondary GPT header have swapped values of "Current LBA"
+Primary GPT header and Backup GPT header have swapped values of "Current LBA"
and "Backup LBA" and therefore different CRC32 check-sum.
CRC32 for GPT headers (field "CRC of header") are calculated up till
the whole array entry ( Number_of_partition_entries *
sizeof(partition_entry_size (usually 128)))
-Observe, how Secondary GPT is placed in the memory. It is NOT a mirror reflect
+Observe, how Backup GPT is placed in the memory. It is NOT a mirror reflect
of the Primary.
-
Partition Entry Format:
----------------------
Offset Size Description
- 0 16 B Partition type GUID
- 16 16 B Unique partition GUID
+ 0 16 B Partition type GUID (Big Endian)
+ 16 16 B Unique partition GUID in (Big Endian)
32 8 B First LBA (Little Endian)
40 8 B Last LBA (inclusive)
48 8 B Attribute flags [+]
Attribute flags:
Bit 0 - System partition
+ Bit 1 - Hide from EFI
+ Bit 2 - Legacy BIOS bootable
+ Bit 48-63 - Defined and used by the individual partition type
+ For Basic data partition :
Bit 60 - Read-only
Bit 62 - Hidden
Bit 63 - Not mount
-
Creating GPT partitions in U-Boot:
==============
To restore GUID partition table one needs to:
1. Define partition layout in the environment.
Format of partitions layout:
- "partitions=uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
+ "uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
name=kernel,size=60MiB,uuid=...;"
or
- "partitions=uuid_disk=${uuid_gpt_disk};name=${uboot_name},
+ "uuid_disk=${uuid_gpt_disk};name=${uboot_name},
size=${uboot_size},uuid=${uboot_uuid};"
- Fields 'name', 'size' and 'uuid' are mandatory for every partition.
+ The fields 'name' and 'size' are mandatory for every partition.
The field 'start' is optional.
+ If field 'size' of the last partition is 0, the partition is extended
+ up to the end of the device.
+
+ The fields 'uuid' and 'uuid_disk' are optional if CONFIG_RANDOM_UUID is
+ enabled. A random uuid will be used if omitted or they point to an empty/
+ non-existent environment variable. The environment variable will be set to
+ the generated UUID. The 'gpt guid' command reads the current value of the
+ uuid_disk from the GPT.
+
+ The field 'bootable' is optional, it is used to mark the GPT partition
+ bootable (set attribute flags "Legacy BIOS bootable").
+ "name=u-boot,size=60MiB;name=boot,size=60Mib,bootable;name=rootfs,size=0"
+ It can be used to locate bootable disks with command
+ "part list <interface> <dev> -bootable <varname>",
+ please check out doc/README.distro for use.
+
2. Define 'CONFIG_EFI_PARTITION' and 'CONFIG_CMD_GPT'
-2. From u-boot prompt type:
+3. From u-boot prompt type:
gpt write mmc 0 $partitions
+Checking (validating) GPT partitions in U-Boot:
+===============================================
+
+Procedure is the same as above. The only change is at point 3.
+
+At u-boot prompt one needs to write:
+ gpt verify mmc 0 [$partitions]
+
+where [$partitions] is an optional parameter.
+
+When it is not provided, only basic checks based on CRC32 calculation for GPT
+header and PTEs are performed.
+When provided, additionally partition data - name, size and starting
+offset (last two in LBA) - are compared with data defined in '$partitions'
+environment variable.
+
+After running this command, return code is set to 0 if no errors found in
+on non-volatile medium stored GPT.
+
+Following line can be used to assess if GPT verification has succeed:
+
+U-BOOT> gpt verify mmc 0 $partitions
+U-BOOT> if test $? = 0; then echo "GPT OK"; else echo "GPT ERR"; fi
+
+Renaming GPT partitions from U-Boot:
+====================================
+
+GPT partition names are a mechanism via which userspace and U-Boot can
+communicate about software updates and boot failure. The 'gpt guid',
+'gpt read', 'gpt rename' and 'gpt swap' commands facilitate
+programmatic renaming of partitions from bootscripts by generating and
+modifying the partitions layout string. Here is an illustration of
+employing 'swap' to exchange 'primary' and 'backup' partition names:
+
+U-BOOT> gpt swap mmc 0 primary backup
+
+Afterwards, all partitions previously named 'primary' will be named
+'backup', and vice-versa. Alternatively, single partitions may be
+renamed. In this example, mmc0's first partition will be renamed
+'primary':
+
+U-BOOT> gpt rename mmc 0 1 primary
+
+The GPT functionality may be tested with the 'sandbox' board by
+creating a disk image as described under 'Block Device Emulation' in
+doc/arch/index.rst:
+
+=>host bind 0 ./disk.raw
+=> gpt read host 0
+[ . . . ]
+=> gpt swap host 0 name othername
+[ . . . ]
+
+Partition type GUID:
+====================
+
+For created partition, the used partition type GUID is
+PARTITION_BASIC_DATA_GUID (EBD0A0A2-B9E5-4433-87C0-68B6B72699C7).
+
+If you define 'CONFIG_PARTITION_TYPE_GUID', a optionnal parameter 'type'
+can specify a other partition type guid:
+
+ "uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
+ name=kernel,size=60MiB,uuid=...,
+ type=0FC63DAF-8483-4772-8E79-3D69D8477DE4;"
+
+Some strings can be also used at the place of known GUID :
+ "system" = PARTITION_SYSTEM_GUID
+ (C12A7328-F81F-11D2-BA4B-00A0C93EC93B)
+ "mbr" = LEGACY_MBR_PARTITION_GUID
+ (024DEE41-33E7-11D3-9D69-0008C781F39F)
+ "msft" = PARTITION_MSFT_RESERVED_GUID
+ (E3C9E316-0B5C-4DB8-817D-F92DF00215AE)
+ "data" = PARTITION_BASIC_DATA_GUID
+ (EBD0A0A2-B9E5-4433-87C0-68B6B72699C7)
+ "linux" = PARTITION_LINUX_FILE_SYSTEM_DATA_GUID
+ (0FC63DAF-8483-4772-8E79-3D69D8477DE4)
+ "raid" = PARTITION_LINUX_RAID_GUID
+ (A19D880F-05FC-4D3B-A006-743F0F84911E)
+ "swap" = PARTITION_LINUX_SWAP_GUID
+ (0657FD6D-A4AB-43C4-84E5-0933C84B4F4F)
+ "lvm" = PARTITION_LINUX_LVM_GUID
+ (E6D6D379-F507-44C2-A23C-238F2A3DF928)
+
+ "uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
+ name=kernel,size=60MiB,uuid=...,type=linux;"
+
+They are also used to display the type of partition in "part list" command.
+
Useful info:
============
-Two programs, namely: 'fdisk' and 'parted' are recommended to work with GPT
-recovery. Parted is able to handle GUID partitions. Unfortunately the 'fdisk'
-hasn't got such ability.
+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.
"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.
+If optional CONFIG_RANDOM_UUID is defined then for any partition which environment
+uuid is unset, uuid is randomly generated and stored in correspond environment
+variable.
+
+note:
+Each string block of UUID generated by program "uuid" is in big endian and it is
+also stored in big endian in disk GPT.
+Partitions layout can be printed by typing "mmc part". Note that each partition
+GUID has different byte order than UUID generated before, this is because first
+three blocks of GUID string are in Little Endian.
projects / oweals / u-boot.git / blobdiff