1# SPDX-License-Identifier: GPL-2.0+ 2# 3# Copyright (C) 2012 Samsung Electronics 4# 5# Lukasz Majewski <l.majewski@samsung.com> 6 7Glossary: 8======== 9- UUID -(Universally Unique Identifier) 10- GUID - (Globally Unique ID) 11- EFI - (Extensible Firmware Interface) 12- UEFI - (Unified EFI) - EFI evolution 13- GPT (GUID Partition Table) - it is the EFI standard part 14- partitions - lists of available partitions (defined at u-boot): 15 ./include/configs/{target}.h 16 17Introduction: 18============= 19This document describes the GPT partition table format and usage of 20the gpt command in u-boot. 21 22UUID introduction: 23==================== 24 25GPT for marking disks/partitions is using the UUID. It is supposed to be a 26globally unique value. A UUID is a 16-byte (128-bit) number. The number of 27theoretically possible UUIDs is therefore about 3 x 10^38. 28More often UUID is displayed as 32 hexadecimal digits, in 5 groups, 29separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters 30(32 digits and 4 hyphens) 31 32For instance, GUID of Basic data partition: EBD0A0A2-B9E5-4433-87C0-68B6B72699C7 33and GUID of Linux filesystem data: 0FC63DAF-8483-4772-8E79-3D69D8477DE4 34 35Historically there are 5 methods to generate this number. The oldest one is 36combining machine's MAC address and timer (epoch) value. 37 38Successive versions are using MD5 hash, random numbers and SHA-1 hash. All major 39OSes and programming languages are providing libraries to compute UUID (e.g. 40uuid command line tool). 41 42GPT brief explanation: 43====================== 44 45 Layout: 46 ------- 47 48 -------------------------------------------------- 49 LBA 0 |Protective MBR | 50 ---------------------------------------------------------- 51 LBA 1 |Primary GPT Header | Primary 52 -------------------------------------------------- GPT 53 LBA 2 |Entry 1|Entry 2| Entry 3| Entry 4| 54 -------------------------------------------------- 55 LBA 3 |Entries 5 - 128 | 56 | | 57 | | 58 ---------------------------------------------------------- 59 LBA 34 |Partition 1 | 60 | | 61 ----------------------------------- 62 |Partition 2 | 63 | | 64 ----------------------------------- 65 |Partition n | 66 | | 67 ---------------------------------------------------------- 68 LBA -34 |Entry 1|Entry 2| Entry 3| Entry 4| Backup 69 -------------------------------------------------- GPT 70 LBA -33 |Entries 5 - 128 | 71 | | 72 | | 73 LBA -2 | | 74 -------------------------------------------------- 75 LBA -1 |Backup GPT Header | 76 ---------------------------------------------------------- 77 78For a legacy reasons, GPT's LBA 0 sector has a MBR structure. It is called 79"protective MBR". 80Its first partition entry ID has 0xEE value, and disk software, which is not 81handling the GPT sees it as a storage device without free space. 82 83It is possible to define 128 linearly placed partition entries. 84 85"LBA -1" means the last addressable block (in the mmc subsystem: 86"dev_desc->lba - 1") 87 88Primary/Backup GPT header: 89---------------------------- 90Offset Size Description 91 920 8 B Signature ("EFI PART", 45 46 49 20 50 41 52 54) 938 4 B Revision (For version 1.0, the value is 00 00 01 00) 9412 4 B Header size (in bytes, usually 5C 00 00 00 meaning 92 bytes) 9516 4 B CRC32 of header (0 to header size), with this field zeroed 96 during calculation 9720 4 B Reserved (ZERO); 9824 8 B Current LBA (location of this header copy) 9932 8 B Backup LBA (location of the other header copy) 10040 8 B First usable LBA for partitions (primary partition table last 101 LBA + 1) 10248 8 B Last usable LBA (secondary partition table first LBA - 1) 10356 16 B Disk GUID (also referred as UUID on UNIXes) 10472 8 B Partition entries starting LBA (always 2 in primary copy) 10580 4 B Number of partition entries 10684 4 B Size of a partition entry (usually 128) 10788 4 B CRC32 of partition array 10892 * Reserved; must be ZERO (420 bytes for a 512-byte LBA) 109 110TOTAL: 512 B 111 112 113IMPORTANT: 114 115GPT headers and partition entries are protected by CRC32 (the POSIX CRC32). 116 117Primary GPT header and Backup GPT header have swapped values of "Current LBA" 118and "Backup LBA" and therefore different CRC32 check-sum. 119 120CRC32 for GPT headers (field "CRC of header") are calculated up till 121"Header size" (92), NOT 512 bytes. 122 123CRC32 for partition entries (field "CRC32 of partition array") is calculated for 124the whole array entry ( Number_of_partition_entries * 125sizeof(partition_entry_size (usually 128))) 126 127Observe, how Backup GPT is placed in the memory. It is NOT a mirror reflect 128of the Primary. 129 130 Partition Entry Format: 131 ---------------------- 132 Offset Size Description 133 134 0 16 B Partition type GUID (Big Endian) 135 16 16 B Unique partition GUID in (Big Endian) 136 32 8 B First LBA (Little Endian) 137 40 8 B Last LBA (inclusive) 138 48 8 B Attribute flags [+] 139 56 72 B Partition name (text) 140 141 Attribute flags: 142 Bit 0 - System partition 143 Bit 1 - Hide from EFI 144 Bit 2 - Legacy BIOS bootable 145 Bit 48-63 - Defined and used by the individual partition type 146 For Basic data partition : 147 Bit 60 - Read-only 148 Bit 62 - Hidden 149 Bit 63 - Not mount 150 151Creating GPT partitions in U-Boot: 152============== 153 154To restore GUID partition table one needs to: 1551. Define partition layout in the environment. 156 Format of partitions layout: 157 "uuid_disk=...;name=u-boot,size=60MiB,uuid=...; 158 name=kernel,size=60MiB,uuid=...;" 159 or 160 "uuid_disk=${uuid_gpt_disk};name=${uboot_name}, 161 size=${uboot_size},uuid=${uboot_uuid};" 162 163 The fields 'name' and 'size' are mandatory for every partition. 164 The field 'start' is optional. 165 166 If field 'size' of the last partition is 0, the partition is extended 167 up to the end of the device. 168 169 The fields 'uuid' and 'uuid_disk' are optional if CONFIG_RANDOM_UUID is 170 enabled. A random uuid will be used if omitted or they point to an empty/ 171 non-existent environment variable. The environment variable will be set to 172 the generated UUID. The 'gpt guid' command reads the current value of the 173 uuid_disk from the GPT. 174 175 The field 'bootable' is optional, it is used to mark the GPT partition 176 bootable (set attribute flags "Legacy BIOS bootable"). 177 "name=u-boot,size=60MiB;name=boot,size=60Mib,bootable;name=rootfs,size=0" 178 It can be used to locate bootable disks with command 179 "part list <interface> <dev> -bootable <varname>", 180 please check out doc/README.distro for use. 181 1822. Define 'CONFIG_EFI_PARTITION' and 'CONFIG_CMD_GPT' 183 1843. From u-boot prompt type: 185 gpt write mmc 0 $partitions 186 187Checking (validating) GPT partitions in U-Boot: 188=============================================== 189 190Procedure is the same as above. The only change is at point 3. 191 192At u-boot prompt one needs to write: 193 gpt verify mmc 0 [$partitions] 194 195where [$partitions] is an optional parameter. 196 197When it is not provided, only basic checks based on CRC32 calculation for GPT 198header and PTEs are performed. 199When provided, additionally partition data - name, size and starting 200offset (last two in LBA) - are compared with data defined in '$partitions' 201environment variable. 202 203After running this command, return code is set to 0 if no errors found in 204on non-volatile medium stored GPT. 205 206Following line can be used to assess if GPT verification has succeed: 207 208U-BOOT> gpt verify mmc 0 $partitions 209U-BOOT> if test $? = 0; then echo "GPT OK"; else echo "GPT ERR"; fi 210 211Renaming GPT partitions from U-Boot: 212==================================== 213 214GPT partition names are a mechanism via which userspace and U-Boot can 215communicate about software updates and boot failure. The 'gpt guid', 216'gpt read', 'gpt rename' and 'gpt swap' commands facilitate 217programmatic renaming of partitions from bootscripts by generating and 218modifying the partitions layout string. Here is an illustration of 219employing 'swap' to exchange 'primary' and 'backup' partition names: 220 221U-BOOT> gpt swap mmc 0 primary backup 222 223Afterwards, all partitions previously named 'primary' will be named 224'backup', and vice-versa. Alternatively, single partitions may be 225renamed. In this example, mmc0's first partition will be renamed 226'primary': 227 228U-BOOT> gpt rename mmc 0 1 primary 229 230The GPT functionality may be tested with the 'sandbox' board by 231creating a disk image as described under 'Block Device Emulation' in 232doc/arch/index.rst: 233 234=>host bind 0 ./disk.raw 235=> gpt read host 0 236[ . . . ] 237=> gpt swap host 0 name othername 238[ . . . ] 239 240Modifying GPT partition layout from U-Boot: 241=========================================== 242 243The entire GPT partition layout can be exported to an environment 244variable and then modified enmasse. Users can change the partition 245numbers, offsets, names and sizes. The resulting variable can used to 246reformat the device. Here is an example of reading the GPT partitions 247into a variable and then modifying them: 248 249U-BOOT> gpt read mmc 0 current_partitions 250U-BOOT> env edit current_partitions 251edit: uuid_disk=[...];name=part1,start=0x4000,size=0x4000,uuid=[...]; 252name=part2,start=0xc000,size=0xc000,uuid=[...];[ . . . ] 253 254U-BOOT> gpt write mmc 0 $current_partitions 255U-BOOT> gpt verify mmc 0 $current_partitions 256 257Partition type GUID: 258==================== 259 260For created partition, the used partition type GUID is 261PARTITION_BASIC_DATA_GUID (EBD0A0A2-B9E5-4433-87C0-68B6B72699C7). 262 263If you define 'CONFIG_PARTITION_TYPE_GUID', a optionnal parameter 'type' 264can specify a other partition type guid: 265 266 "uuid_disk=...;name=u-boot,size=60MiB,uuid=...; 267 name=kernel,size=60MiB,uuid=..., 268 type=0FC63DAF-8483-4772-8E79-3D69D8477DE4;" 269 270Some strings can be also used at the place of known GUID : 271 "system" = PARTITION_SYSTEM_GUID 272 (C12A7328-F81F-11D2-BA4B-00A0C93EC93B) 273 "mbr" = LEGACY_MBR_PARTITION_GUID 274 (024DEE41-33E7-11D3-9D69-0008C781F39F) 275 "msft" = PARTITION_MSFT_RESERVED_GUID 276 (E3C9E316-0B5C-4DB8-817D-F92DF00215AE) 277 "data" = PARTITION_BASIC_DATA_GUID 278 (EBD0A0A2-B9E5-4433-87C0-68B6B72699C7) 279 "linux" = PARTITION_LINUX_FILE_SYSTEM_DATA_GUID 280 (0FC63DAF-8483-4772-8E79-3D69D8477DE4) 281 "raid" = PARTITION_LINUX_RAID_GUID 282 (A19D880F-05FC-4D3B-A006-743F0F84911E) 283 "swap" = PARTITION_LINUX_SWAP_GUID 284 (0657FD6D-A4AB-43C4-84E5-0933C84B4F4F) 285 "lvm" = PARTITION_LINUX_LVM_GUID 286 (E6D6D379-F507-44C2-A23C-238F2A3DF928) 287 "u-boot-env" = PARTITION_U_BOOT_ENVIRONMENT 288 (3DE21764-95BD-54BD-A5C3-4ABE786F38A8) 289 290 "uuid_disk=...;name=u-boot,size=60MiB,uuid=...; 291 name=kernel,size=60MiB,uuid=...,type=linux;" 292 293They are also used to display the type of partition in "part list" command. 294 295 296Useful info: 297============ 298 299Two programs, namely: 'gdisk' and 'parted' are recommended to work with GPT 300recovery. Both are able to handle GUID partitions. 301Please, pay attention at -l switch for parted. 302 303"uuid" program is recommended to generate UUID string. Moreover it can decode 304(-d switch) passed in UUID string. It can be used to generate partitions UUID 305passed to u-boot environment variables. 306If optional CONFIG_RANDOM_UUID is defined then for any partition which environment 307uuid is unset, uuid is randomly generated and stored in correspond environment 308variable. 309 310note: 311Each string block of UUID generated by program "uuid" is in big endian and it is 312also stored in big endian in disk GPT. 313Partitions layout can be printed by typing "mmc part". Note that each partition 314GUID has different byte order than UUID generated before, this is because first 315three blocks of GUID string are in Little Endian. 316