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